View Issue Details

IDProjectCategoryView StatusLast Update
0008260Talerdocumentationpublic2024-03-07 20:47
ReporterStefan Assigned ToChristian Grothoff  
PrioritylowSeveritytextReproducibilityN/A
Status closedResolutionfixed 
Product Versiongit (master) 
Target Version0.9.4Fixed in Version0.9.4 
Summary0008260: ContractTerm's FulfillmentURL incomplete in documentation
DescriptionThe 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.
TagsNo tags attached.

Activities

Stefan

2024-01-24 16:51

developer   ~0021029

Who feels competent to solve this issue respectively who is in charge of minor edits to the documentation?

Christian Grothoff

2024-02-26 21:36

manager   ~0021526

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.

Issue History

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