taler-docs

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

post-private-templates.rst (4573B)

      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       // Minimum age buyer must have (in years). Default is 0.
     88       minimum_age?: Integer;
     89 
     90       // Inventory-cart: request a tip during instantiation.
     91       // Since protocol **v25**.
     92       request_tip?: boolean;
     93     }
     94 
     95   .. ts:def:: TemplateType
     96 
     97     enum TemplateType {
     98       FIXED_ORDER = "fixed-order",
     99       INVENTORY_CART = "inventory-cart",
    100       PAIVANA = "paivana"
    101     }
    102 
    103   .. ts:def:: TemplateContractFixedOrder
    104 
    105     interface TemplateContractFixedOrder {
    106 
    107       // The price is imposed by the merchant and cannot be changed by the customer.
    108       // This parameter is optional.
    109       amount?: Amount;
    110 
    111     }
    112 
    113   .. ts:def:: TemplateContractInventoryCart
    114 
    115     interface TemplateContractInventoryCart {
    116 
    117       // Inventory-cart: allow any inventory item to be selected.
    118       // Since protocol **v25**.
    119       selected_all?: boolean;
    120 
    121       // Inventory-cart: only products in these categories are selectable.
    122       // Since protocol **v25**.
    123       selected_categories?: Integer[];
    124 
    125       // Inventory-cart: only these products are selectable.
    126       // Since protocol **v25**.
    127       selected_products?: string[];
    128 
    129       // Inventory-cart: require exactly one selection entry.
    130       // Since protocol **v25**.
    131       choose_one?: boolean;
    132 
    133       // Inventory-cart: backend-provided payload with selectable data.
    134       // Only present in ``GET /templates/$TEMPLATE_ID`` responses.
    135       // Since protocol **v25**.
    136       inventory_payload?: InventoryPayload;
    137    }
    138 
    139   .. ts:def:: TemplateContractPaivana
    140 
    141     interface TemplateContractPaivana {
    142 
    143       // Regular expression over URLs for which
    144       // this template is valid.
    145       // Optional, if not given all URLs are accepted.
    146       // Since protocol **v25**.
    147       website_regex?: string;
    148 
    149       // Methods to pay for the contract.
    150       choices: OrderChoice[];
    151    }