taler-docs

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

post-private-templates.rst (3825B)

      1 .. http:post:: [/instances/$INSTANCE]/private/templates
      2 
      3   This is used to create a template.
      4 
      5   **Required permission:** ``templates-write``
      6 
      7   **Request:**
      8 
      9   The request must be a `TemplateAddDetails`.
     10 
     11 
     12   **Response:**
     13 
     14   :http:statuscode:`204 No content`:
     15     The creation of the template is successful.
     16   :http:statuscode:`404 Not found`:
     17     The merchant instance is unknown or it is not in our data.
     18 
     19   **Details:**
     20 
     21 
     22   .. ts:def:: TemplateAddDetails
     23 
     24     interface TemplateAddDetails {
     25 
     26       // Template ID to use.
     27       template_id: string;
     28 
     29       // Human-readable description for the template.
     30       template_description: string;
     31 
     32       // OTP device ID.
     33       // This parameter is optional.
     34       otp_id?: string;
     35 
     36       // Fixed contract information for orders created from
     37       // this template.
     38       template_contract: TemplateContractDetails;
     39 
     40       // Key-value pairs matching a subset of the
     41       // fields from ``template_contract`` that are
     42       // user-editable defaults for this template.
     43       // Since protocol **v13**.
     44       editable_defaults?: Object;
     45     }
     46 
     47 
     48   .. ts:def:: TemplateContractDetails
     49 
     50     type TemplateContractDetails = (TemplateContractFixedOrder | TemplateContractInventoryCart | TemplateContractPaivana) & TemplateContractCommon;
     51 
     52   .. ts:def:: TemplateContractCommon
     53 
     54     interface TemplateContractCommon {
     55       // Template type to apply. Defaults to "fixed-order" if omitted.
     56       // Prescribes which interface has to be followed
     57       // Since protocol **v25**.
     58       template_type?: TemplateType;
     59 
     60       // Human-readable summary for the template.
     61       summary?: string;
     62 
     63       // Required currency for payments to the template.
     64       // This parameter is optional and should not be present
     65       // if "amount" is given.
     66       currency?: string;
     67 
     68       // The time the customer need to pay before his order will be deleted.
     69       // It is deleted if the customer did not pay and if the duration is over.
     70       pay_duration?: RelativeTime;
     71 
     72       // Minimum age buyer must have (in years). Default is 0.
     73       minimum_age?: Integer;
     74 
     75       // Inventory-cart: request a tip during instantiation.
     76       // Since protocol **v25**.
     77       request_tip?: boolean;
     78     }
     79 
     80   .. ts:def:: TemplateType
     81 
     82     enum TemplateType {
     83       FIXED_ORDER = "fixed-order",
     84       INVENTORY_CART = "inventory-cart",
     85       PAIVANA = "paivana"
     86     }
     87 
     88   .. ts:def:: TemplateContractFixedOrder
     89 
     90     interface TemplateContractFixedOrder {
     91 
     92       // The price is imposed by the merchant and cannot be changed by the customer.
     93       // This parameter is optional.
     94       amount?: Amount;
     95 
     96     }
     97 
     98   .. ts:def:: TemplateContractInventoryCart
     99 
    100     interface TemplateContractInventoryCart {
    101 
    102       // Inventory-cart: allow any inventory item to be selected.
    103       // Since protocol **v25**.
    104       selected_all?: boolean;
    105 
    106       // Inventory-cart: only products in these categories are selectable.
    107       // Since protocol **v25**.
    108       selected_categories?: Integer[];
    109 
    110       // Inventory-cart: only these products are selectable.
    111       // Since protocol **v25**.
    112       selected_products?: string[];
    113 
    114       // Inventory-cart: require exactly one selection entry.
    115       // Since protocol **v25**.
    116       choose_one?: boolean;
    117 
    118       // Inventory-cart: backend-provided payload with selectable data.
    119       // Only present in ``GET /templates/$TEMPLATE_ID`` responses.
    120       // Since protocol **v25**.
    121       inventory_payload?: InventoryPayload;
    122    }
    123 
    124   .. ts:def:: TemplateContractPaivana
    125 
    126     interface TemplateContractPaivana {
    127 
    128       // Regular expression over URLs for which
    129       // this template is valid.
    130       // Optional, if not given all URLs are accepted.
    131       // Since protocol **v25**.
    132       website_regex?: string;
    133 
    134       // Methods to pay for the contract.
    135       choices: OrderChoice[];
    136    }