View Issue Details
| ID | Project | Category | View Status | Date Submitted | Last Update |
|---|---|---|---|---|---|
| 0008260 | Taler | documentation | public | 2024-01-24 16:47 | 2024-03-07 20:47 |
| Reporter | Stefan | Assigned To | Christian Grothoff | ||
| Priority | low | Severity | text | Reproducibility | N/A |
| Status | closed | Resolution | fixed | ||
| Product Version | git (master) | ||||
| Target Version | 0.9.4 | Fixed in Version | 0.9.4 | ||
| Summary | 0008260: ContractTerm's FulfillmentURL incomplete in documentation | ||||
| Description | The ContractTerm's FulfillmentURL field has to be checked for completeness in the documentation. Slack Coder reported via e-mail: As a programmer, I check to the API documentation because it is the most authoritative. The 'MinimalOrderDetail' <https://docs.taler.net/core/api-merchant.html#tsref-type-MinimalOrderDetail> says of the field 'See documentation of fulfillment_url in ContractTerms.'. It is easy, though not correct, to follow the link to the design document's ContractTerms and assume it is not fully documented, because one would expect it to link to the authoritative definition. There is no mention of the fulfillment_url there. ``` interface MinimalOrderDetail { // Amount to be paid by the customer. amount: Amount; // Short summary of the order. summary: string; // See documentation of fulfillment_url in ContractTerms. // Either fulfillment_url or fulfillment_message must be specified. // When creating an order, the fulfillment URL can // contain ${ORDER_ID} which will be substituted with the // order ID of the newly created order. fulfillment_url?: string; // See documentation of fulfillment_message in ContractTerms. // Either fulfillment_url or fulfillment_message must be specified. fulfillment_message?: string; } ``` The fulfillment_url is expected to be unique for each order. One workaround is to mention this under MinimalOrderDetail's<https://docs.taler.net/core/api-merchant.html#tsref-type-MinimalOrderDetail>. Though as a fallible reader of documentation, like myself, I would still believe ContractTerms is left mostly undefined. The fulfillment_url is particularly annoying because a duplicate instance is not reported as an error. You find out only after a test purchase with the item being reported as already bought. Thanks! Slack Coder On 1/24/24 03:11, Stefan Kügel wrote: > Dear Slack Coder, > hi Christian (cc'ed), > > Thank you for reporting. I checked against the documentation at https://docs.taler.net/core/api-merchant.html#payment-processing and came to the conclusion that the link at `type Order : MinimalOrderDetail <https://docs.taler.net/core/api-merchant.html#tsref-type-MinimalOrderDetail> | ContractTerms <https://docs.taler.net/design-documents/024-age-restriction.html#tsref-type-ContractTerms>;` is correct as is. > > ContractTerms <https://docs.taler.net/design-documents/024-age-restriction.html#tsref-type-ContractTerms>; links to https://docs.taler.net/design-documents/024-age-restriction.html#tsref-type-ContractTerms (12.24. DD 24: Anonymous Age Restriction Extension) where we get detailed that the variable ContractTerms <https://docs.taler.net/design-documents/024-age-restriction.html#tsref-type-ContractTerms> is an integer for a minimum age as contract term if a seller needs this to be specified. > > interface ContractTerms { > ... > > // If the order requires a minimum age greater than 0, this field is set > // to the integer value of that age. In reality this value will not be > // smaller than, say, 8, and not larger than, say, 21. > minimum_age?:Integer <https://docs.taler.net/core/api-common.html#tsref-type-Integer>; > > ... > } > > > Consequently, the link to Design document #24 "Anonymous Age Restriction Extension" should be OK, at least to my understanding of the matter. If you think this still must be rectified please get back to me with further details. | ||||
| Tags | No tags attached. | ||||
|
|
Who feels competent to solve this issue respectively who is in charge of minor edits to the documentation? |
|
|
The link to the correct place in the specification (not the DD!) was fixed previously already. 2e03711..6b67d45 improves the API documentation on the fulfillment URL, clarifying WHEN it should be unique. |
| Date Modified | Username | Field | Change |
|---|---|---|---|
| 2024-01-24 16:47 | Stefan | New Issue | |
| 2024-01-24 16:47 | Stefan | Status | new => assigned |
| 2024-01-24 16:47 | Stefan | Assigned To | => Stefan |
| 2024-01-24 16:51 | Stefan | Assigned To | Stefan => dvn |
| 2024-01-24 16:51 | Stefan | Note Added: 0021029 | |
| 2024-02-26 13:13 | dvn | Assigned To | dvn => |
| 2024-02-26 13:50 | Christian Grothoff | Assigned To | => Christian Grothoff |
| 2024-02-26 21:36 | Christian Grothoff | Note Added: 0021526 | |
| 2024-02-26 21:37 | Christian Grothoff | Status | assigned => resolved |
| 2024-02-26 21:37 | Christian Grothoff | Resolution | open => fixed |
| 2024-02-26 21:37 | Christian Grothoff | Fixed in Version | => 0.9.4 |
| 2024-02-26 21:37 | Christian Grothoff | Product Version | => git (master) |
| 2024-02-26 21:37 | Christian Grothoff | Target Version | => 0.9.4 |
| 2024-03-07 20:47 | Christian Grothoff | Status | resolved => closed |
