taler-docs

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

patch-private-products-PRODUCT_ID.rst (4922B)

      1 .. http:patch:: [/instances/$INSTANCE]/private/products/$PRODUCT_ID
      2 
      3   This is used to update product details in the inventory. Note that the
      4   ``total_stock`` and ``total_lost`` numbers MUST be greater or equal than
      5   previous values (this design ensures idempotency).  In case stocks were lost
      6   but not sold, increment the ``total_lost`` number.  All fields in the
      7   request are optional, those that are not given are simply preserved (not
      8   modified).  Note that the ``description_i18n`` and ``taxes`` can only be
      9   modified in bulk: if it is given, all translations must be provided, not
     10   only those that changed.  ``never`` should be used for the ``next_restock``
     11   timestamp to indicate no intention/possibility of restocking, while a time
     12   of zero is used to indicate "unknown".
     13 
     14   **Required permission:** ``products-write``
     15 
     16   **Request:**
     17 
     18   The request must be a `ProductPatchDetailRequest`.
     19 
     20   **Response:**
     21 
     22   :http:statuscode:`204 No content`:
     23     The backend has successfully expanded the inventory.
     24   :http:statuscode:`404 Not found`:
     25     The instance, product, category, product group or money pot specified are
     26     unknown. Possible error ``code`` values are thus:
     27     ``TALER_EC_MERCHANT_GENERIC_INSTANCE_UNKNOWN`` (instance unknown),
     28     ``TALER_EC_MERCHANT_GENERIC_PRODUCT_UNKNOWN`` (product unknown),
     29     ``TALER_EC_MERCHANT_GENERIC_PRODUCT_GROUP_UNKNOWN`` (product group unknown)
     30     ``TALER_EC_MERCHANT_GENERIC_MONEY_POT_UNKNOWN`` (money pot unknown),
     31     ``TALER_EC_MERCHANT_GENERIC_CATEGORY_UNKNOWN``
     32     (category unknown, specific category is given in the details).
     33   :http:statuscode:`409 Conflict`:
     34     The provided information is inconsistent with the current state of
     35     the inventory.
     36 
     37 
     38   .. ts:def:: ProductPatchDetailRequest
     39 
     40     interface ProductPatchDetailRequest {
     41 
     42       // Human-readable product name.
     43       // Since API version **v20**.  Optional only for
     44       // backwards-compatibility, should be considered mandatory
     45       // moving forward!
     46       product_name?: string;
     47 
     48       // Human-readable product description.
     49       description: string;
     50 
     51       // Map from IETF BCP 47 language tags to localized descriptions.
     52       description_i18n?: { [lang_tag: string]: string };
     53 
     54       // Unit in which the product is measured (liters, kilograms, packages, etc.).
     55       unit: string;
     56 
     57       // Optional override to control whether fractional quantities are permitted.
     58       unit_allow_fraction?: boolean;
     59 
     60       // Override for the fractional precision level (0-6). Only relevant if
     61       // ``unit_allow_fraction`` is true.
     62       unit_precision_level?: Integer;
     63 
     64       // Categories into which the product belongs.
     65       // Used in the POS-endpoint.
     66       // Since API version **v16**.
     67       categories?: Integer[];
     68 
     69       // Preferred way to express the per-unit price. Supply at least one entry;
     70       // the first entry represents the base price and MUST include applicable taxes.
     71       // Zero implies that the product is not sold separately or that the price must be supplied
     72       // by the frontend.
     73       // Each entry must use a distinct currency.
     74       // Since API version **v25**.
     75       // Currency uniqueness enforced since protocol **v25**.
     76       unit_price?: Amount[];
     77 
     78       // Legacy price field.
     79       // Deprecated since **v25**;
     80       // when present it must match the first element of ``unit_price``.
     81       price?: Amount;
     82 
     83       // True if the price(s) given are a net prices, false if they are
     84       // gross prices.
     85       // Since protocol **vTAXES**.
     86       price_is_net?: boolean;
     87 
     88       // An optional base64-encoded product image.
     89       image?: ImageDataUrl;
     90 
     91       // A list of taxes paid by the merchant for one unit of this product.
     92       taxes?: Tax[];
     93 
     94       // Preferred way to express inventory counts using "<integer>[.<fraction>]" syntax.
     95       // Use "-1" for unlimited stock.
     96       unit_total_stock?: DecimalQuantity;
     97 
     98       // Legacy stock counter. Deprecated, use ``unit_total_stock`` instead.
     99       total_stock?: Integer;
    100 
    101       // Number of units of the product that were lost (spoiled, stolen, etc.).
    102       total_lost?: Integer;
    103 
    104       // Identifies where the product is in stock.
    105       address?: Location;
    106 
    107       // Identifies when we expect the next restocking to happen.
    108       next_restock?: Timestamp;
    109 
    110       // Minimum age buyer must have (in years). Default is 0.
    111       minimum_age?: Integer;
    112 
    113       // Product group the product belongs to. 0 and missing both
    114       // means default.
    115       // Since **v25**.
    116       product_group_id?: Integer;
    117 
    118       // Money pot revenue on the product should be accounted in.
    119       // 0 and missing both mean no money pot (revenue accounted
    120       // in money pot of the overall order or not at all).
    121       // Since **v25**.
    122       money_pot_id?: Integer;
    123 
    124     }
    125 
    126   The same compatibility rules for the ``unit_*`` fields and their deprecated counterparts apply
    127   when patching an existing product.