taler-docs

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

post-private-templates.rst (4050B)

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