taler-docs

post-private-products.rst (6529B)

---

 .. http:post:: [/instances/$INSTANCE]/private/products
 
   This is used to add a product to the inventory.
 
   **Required permission:** ``products-write``
 
   **Request:**
 
   The request must be a `ProductAddDetailRequest`.
 
   **Response:**
 
   :http:statuscode:`204 No content`:
     The backend has successfully expanded the inventory.
   :http:statuscode:`400 Bad Request`:
     The request body is malformed.
   :http:statuscode:`404 Not found`:
     The instance, category, product group or money pot specified are
     unknown. Possible error ``code`` values are thus:
     ``TALER_EC_MERCHANT_GENERIC_INSTANCE_UNKNOWN`` (instance unknown),
     ``TALER_EC_MERCHANT_GENERIC_PRODUCT_GROUP_UNKNOWN`` (product group unknown)
     ``TALER_EC_MERCHANT_GENERIC_MONEY_POT_UNKNOWN`` (money pot unknown),
     ``TALER_EC_MERCHANT_GENERIC_CATEGORY_UNKNOWN``
     (category unknown, specific category is given in the details).
 
   :http:statuscode:`409 Conflict`:
     The backend already knows a product with this product ID,
     but with different details. Returned with a ``code`` of
     ``TALER_EC_MERCHANT_PRIVATE_POST_PRODUCTS_CONFLICT_PRODUCT_EXISTS``.
   :http:statuscode:`500 Internal Server Error`:
     The server experienced an internal failure.
     Returned with ``TALER_EC_GENERIC_DB_STORE_FAILED``.
 
   **Details:**
 
   .. ts:def:: ProductAddDetailRequest
 
     interface ProductAddDetailRequest {
 
       // Product ID to use.
       product_id: string;
 
       // Human-readable product name.
       // Since API version **v20**.  Optional only for
       // backwards-compatibility, should be considered mandatory
       // moving forward!
       product_name?: string;
 
       // Human-readable product description.
       description: string;
 
       // Map from IETF BCP 47 language tags to localized descriptions.
       description_i18n?: { [lang_tag: string]: string };
 
       // Categories into which the product belongs.
       // Used in the POS-endpoint.
       // Since API version **v16**.
       categories?: Integer[];
 
       // Unit in which the product is measured (liters, kilograms, packages, etc.).
       unit: string;
 
       // Optional override to control whether fractional quantities are permitted.
       // Defaults to the policy implied by ``unit``.
       unit_allow_fraction?: boolean;
 
       // Override for the fractional precision level (0-6). Only relevant if
       // ``unit_allow_fraction`` is true. Defaults come from ``unit``.
       unit_precision_level?: Integer;
 
       // Preferred way to express inventory counts using "<integer>[.<fraction>]" syntax.
       // Use "-1" for unlimited stock. Required unless ``total_stock`` is provided.
       unit_total_stock?: DecimalQuantity;
 
       // Legacy stock counter. Deprecated, use ``unit_total_stock`` instead.
       // Still required when ``unit_total_stock`` is omitted.
       total_stock?: Integer;
 
       // Preferred way to express the per-unit price of the product. Supply at least one entry;
       // the first entry must match ``price``.
       // The price given MUST include applicable taxes if ``price_is_net``
       // is false, and MUST exclude applicable taxes if ``price_is_net``
       // is true.
       // Zero implies that the product is not sold separately or that the price must be supplied
       // by the frontend.
       // Each entry must use a distinct currency.
       // Since API version **v25**.
       // Currency uniqueness enforced since protocol **v25**.
       unit_price?: Amount[];
 
       // True if the price(s) given are a net prices, false if they are
       // gross prices.
       // Since protocol **vTAXES**.
       price_is_net?: boolean;
 
       // Legacy price field.
       // Deprecated since **v25**;
       // when present it must match the first element of ``unit_price``.
       price?: Amount;
 
       // An optional base64-encoded product image.
       image?: ImageDataUrl;
 
       // A list of taxes paid by the merchant for one unit of this product.
       taxes?: Tax[];
 
       // Identifies where the product is in stock.
       address?: Location;
 
       // Identifies when we expect the next restocking to happen.
       next_restock?: Timestamp;
 
       // Minimum age buyer must have (in years). Default is 0.
       minimum_age?: Integer;
 
       // Product group the product belongs to. 0 and missing both
       // means default.
       // Since **v25**.
       product_group_id?: Integer;
 
       // Money pot revenue on the product should be accounted in.
       // 0 and missing both mean no money pot (revenue accounted
       // in money pot of the overall order or not at all).
       // Since **v25**.
       money_pot_id?: Integer;
 
     }
 
   Clients SHOULD migrate to the new ``unit_*`` fields and treat ``total_stock`` and ``price``
   as deprecated compatibility shims. If both the legacy and the new representation are supplied,
   their values must match. Omitting both ``unit_total_stock`` and ``total_stock`` (or both
   ``unit_price`` and ``price``) results in a ``400 Bad Request``. When only ``price`` is given,
   the backend treats it as a one-element ``unit_price`` array.
 
   ``unit_total_stock`` uses a fixed-point decimal string in the form ``INTEGER[.FRACTION]`` with
   at most six fractional digits. Scientific notation or special values such as ``NaN`` are not
   accepted. Supply ``"-1"`` to represent unlimited stock. See
   :ref:`DecimalQuantity <decimal-quantity>`.
 
   Fractional behaviour defaults to the value of ``unit``. The backend disables fractions for
   ``Piece``, ``Set``, ``Custom``, ``WeightUnitMg`` and ``SizeUnitMm``. Other predefined units
   allow fractional quantities with the following default precision levels:
 
   - Precision ``1``: ``WeightUnitG``, ``SizeUnitCm``, ``SurfaceUnitMm2``, ``VolumeUnitMm3``.
   - Precision ``2``: ``WeightUnitOunce``, ``SizeUnitInch``, ``SurfaceUnitCm2``,
     ``VolumeUnitInch3``, ``VolumeUnitOunce``, ``TimeUnitHour``, ``TimeUnitMonth``.
   - Precision ``3``: ``WeightUnitTon``, ``WeightUnitKg``, ``WeightUnitPound``, ``SizeUnitM``,
     ``SizeUnitDm``, ``SizeUnitFoot``, ``SurfaceUnitDm2``, ``SurfaceUnitFoot2``, ``VolumeUnitCm3``,
     ``VolumeUnitLitre``, ``VolumeUnitGallon``, ``TimeUnitSecond``, ``TimeUnitMinute``,
     ``TimeUnitDay``, ``TimeUnitWeek``.
   - Precision ``4``: ``SurfaceUnitM2``, ``SurfaceUnitInch2``, ``TimeUnitYear``.
   - Precision ``5``: ``VolumeUnitDm3``, ``VolumeUnitFoot3``.
   - Precision ``6``: ``VolumeUnitM3``.
 
   Integrations can override these defaults by explicitly setting ``unit_allow_fraction`` and/or
   ``unit_precision_level``.