taler-docs

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

post-private-templates.rst (4868B)

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