taler-docs

Documentation for GNU Taler components, APIs and protocols
Log | Files | Refs | README | LICENSE

post-templates-TEMPLATE_ID.rst (6346B)

      1 .. http:post:: [/instances/$INSTANCE]/templates/$TEMPLATE_ID
      2 
      3   This using template can be modified by everyone and will be used to create order.
      4 
      5 
      6   **Request:**
      7 
      8   The request must be a `UsingTemplateDetailsRequest` and we accept JSON application and URL encoded.
      9 
     10   **Response:**
     11 
     12   :http:statuscode:`400 Bad Request`:
     13     The request body is malformed.
     14     Returned with ``TALER_EC_GENERIC_PARAMETER_MALFORMED``,
     15     ``TALER_EC_MERCHANT_POST_USING_TEMPLATES_NO_AMOUNT``,
     16     ``TALER_EC_MERCHANT_POST_USING_TEMPLATES_NO_CURRENCY``,
     17     ``TALER_EC_MERCHANT_POST_USING_TEMPLATES_NO_SUMMARY``,
     18     ``TALER_EC_MERCHANT_POST_USING_TEMPLATES_AMOUNT_CONFLICT_TEMPLATES_CONTRACT_AMOUNT``,
     19     ``TALER_EC_MERCHANT_POST_USING_TEMPLATES_SUMMARY_CONFLICT_TEMPLATES_CONTRACT_SUBJECT``,
     20     ``TALER_EC_MERCHANT_POST_USING_TEMPLATES_WRONG_PRODUCT``,
     21     ``TALER_EC_MERCHANT_POST_USING_TEMPLATES_WRONG_TYPE`` or
     22     ``TALER_EC_MERCHANT_GENERIC_CURRENCY_MISMATCH``.
     23   :http:statuscode:`404 Not found`:
     24     The template, instance, or product is unknown.
     25     Returned with ``TALER_EC_MERCHANT_GENERIC_TEMPLATE_UNKNOWN`` or
     26     ``TALER_EC_MERCHANT_GENERIC_PRODUCT_UNKNOWN``.
     27   :http:statuscode:`409 Conflict`:
     28     The request contradicts the template.  In particular, this is
     29     returned with ``TALER_EC_MERCHANT_POST_USING_TEMPLATES_AMOUNT_CONFLICT_TEMPLATES_CONTRACT_AMOUNT``
     30     if the template fixes the amount but the request provides one, if
     31     ``amount`` and ``choice_amounts`` are both given, if ``amount`` is
     32     used as a shorthand but the template has no or more than one choice
     33     with ``editable_amount``, if a ``choice_amounts`` entry selects a
     34     choice without ``editable_amount``, or if a client-chosen amount
     35     violates the ``min_amount`` or ``max_amount`` of the template.
     36     Returned with ``TALER_EC_MERCHANT_GENERIC_CURRENCY_MISMATCH`` if a
     37     client-chosen amount is in the wrong currency.
     38   :http:statuscode:`413 Request entity too large`:
     39     The uploaded body is to long, it exceeds the size limit.
     40     Returned with an error code of
     41     ``TALER_EC_GENERIC_UPLOAD_EXCEEDS_LIMIT``.
     42   :http:statuscode:`500 Internal Server Error`:
     43     The server experienced an internal failure.
     44     Returned with ``TALER_EC_GENERIC_DB_FETCH_FAILED``,
     45     ``TALER_EC_GENERIC_FAILED_COMPUTE_AMOUNT`` or
     46     ``TALER_EC_GENERIC_INTERNAL_INVARIANT_FAILURE``.
     47 
     48   The response is exactly the same type of response as when
     49   creating an order using :ref:`POST /private/orders <post-order>`.
     50 
     51   **Details:**
     52 
     53   .. ts:def:: UsingTemplateDetailsRequest
     54 
     55     type UsingTemplateDetailsRequest = (UsingTemplateFixedOrderRequest | UsingTemplateInventoryCartRequest | UsingTemplatePaivanaRequest) & UsingTemplateCommonRequest;
     56 
     57   .. ts:def:: UsingTemplateCommonRequest
     58 
     59     interface UsingTemplateCommonRequest {
     60 
     61       // Type of the template being instantiated.
     62       // Possible values include "fixed-order",
     63       // "inventory-cart" and "paivana".
     64       // Since protocol **v25**.
     65       // Defaults to "fixed-order" while supporting previous
     66       // protocol versions.
     67       template_type: string;
     68 
     69       // Summary to use in the contract. Only if
     70       // not already specified by the template.
     71       summary?: string;
     72 
     73       // The amount to be paid, including tip.
     74       // For a "paivana" template, this is a shorthand that is only
     75       // allowed if exactly one of the choices of the template has
     76       // "editable_amount" set: the amount then replaces the amount of
     77       // that choice, the tip is added on top of it (as for a choice
     78       // with a fixed amount), and the field is mutually exclusive with
     79       // "choice_amounts".
     80       amount?: Amount;
     81 
     82       // Optional tip amount. Must match the currency of ``amount`` or the
     83       // fixed template currency.
     84       // Since protocol **v25**.
     85       tip?: Amount;
     86 
     87       // Challenge obtained from an offline verifier, such as an
     88       // appliance or electronic tag: 32 bytes, Crockford Base32
     89       // encoded. Stored
     90       // with the order and signed by the OTP device associated with
     91       // the template when the POS confirmation is computed. Only
     92       // meaningful -- and then mandatory -- if the template's OTP
     93       // device uses a challenge-signature algorithm ("ECDSA_CHALLENGE"
     94       // or "EDDSA_CHALLENGE"); rejected otherwise.
     95       // Since protocol **vChallengeConfirmation**.
     96       challenge?: string;
     97 
     98     }
     99 
    100   .. ts:def:: UsingTemplateFixedOrderRequest
    101 
    102     interface UsingTemplateFixedOrderRequest {
    103        template_type: "fixed-order";
    104 
    105     }
    106 
    107   .. ts:def:: UsingTemplateInventoryCartRequest
    108 
    109     interface UsingTemplateInventoryCartRequest {
    110       template_type: "inventory-cart";
    111 
    112       // Inventory-cart: selected products and quantities.
    113       // Since protocol **v25**.
    114       inventory_selection?: InventorySelectionEntry[];
    115     }
    116 
    117   .. ts:def:: InventorySelectionEntry
    118 
    119     interface InventorySelectionEntry {
    120       // Inventory product to add.
    121       product_id: Slug;
    122 
    123       // Quantity in "<integer>[.<fraction>]" form using the product unit rules.
    124       quantity: DecimalQuantity;
    125     }
    126 
    127   .. ts:def:: UsingTemplatePaivanaRequest
    128 
    129     interface UsingTemplatePaivanaRequest {
    130       template_type: "paivana";
    131 
    132       // Website to which access is being sold.
    133       // Will become the fulfillment URL in the contract.
    134       website: WebURL;
    135 
    136       // Client Paivana ID to grant access to.
    137       // This becomes the "session_id" for session-based
    138       // access control.
    139       paivana_id: string;
    140 
    141       // Amounts chosen by the client for the choices of the template
    142       // that have "editable_amount" set.  Choices that are not
    143       // mentioned keep the amount given in the template.  Mutually
    144       // exclusive with the "amount" field.
    145       // Since protocol **v34**.
    146       choice_amounts?: TemplateChoiceAmount[];
    147 
    148     }
    149 
    150   .. ts:def:: TemplateChoiceAmount
    151 
    152     interface TemplateChoiceAmount {
    153       // Index of the choice in the "choices" array of the template
    154       // contract.  The choice must have "editable_amount" set.
    155       choice_index: Integer;
    156 
    157       // Amount to use for that choice, excluding any tip.  Must be in
    158       // the currency of the choice, and within the "min_amount" and
    159       // "max_amount" bounds of the template (if any).  Any "tip" given
    160       // in the request is added on top of this amount.
    161       amount: Amount;
    162     }