post-private-products.rst (6304B)
1 .. http:post:: [/instances/$INSTANCE]/private/products 2 3 This is used to add a product to the inventory. 4 5 **Required permission:** ``products-write`` 6 7 **Request:** 8 9 The request must be a `ProductAddDetailRequest`. 10 11 **Response:** 12 13 :http:statuscode:`204 No content`: 14 The backend has successfully expanded the inventory. 15 :http:statuscode:`404 Not found`: 16 The instance, category, product group or money pot specified are 17 unknown. Possible error ``code`` values are thus: 18 ``TALER_EC_MERCHANT_GENERIC_INSTANCE_UNKNOWN`` (instance unknown), 19 ``TALER_EC_MERCHANT_GENERIC_PRODUCT_GROUP_UNKNOWN`` (product group unknown) 20 ``TALER_EC_MERCHANT_GENERIC_MONEY_POT_UNKNOWN`` (money pot unknown), 21 ``TALER_EC_MERCHANT_GENERIC_CATEGORY_UNKNOWN`` 22 (category unknown, specific category is given in the details). 23 24 :http:statuscode:`409 Conflict`: 25 The backend already knows a product with this product ID, 26 but with different details. Returned with a ``code`` of 27 ``TALER_EC_MERCHANT_PRIVATE_POST_PRODUCTS_CONFLICT_PRODUCT_EXISTS``. 28 29 **Details:** 30 31 .. ts:def:: ProductAddDetailRequest 32 33 interface ProductAddDetailRequest { 34 35 // Product ID to use. 36 product_id: string; 37 38 // Human-readable product name. 39 // Since API version **v20**. Optional only for 40 // backwards-compatibility, should be considered mandatory 41 // moving forward! 42 product_name?: string; 43 44 // Human-readable product description. 45 description: string; 46 47 // Map from IETF BCP 47 language tags to localized descriptions. 48 description_i18n?: { [lang_tag: string]: string }; 49 50 // Categories into which the product belongs. 51 // Used in the POS-endpoint. 52 // Since API version **v16**. 53 categories?: Integer[]; 54 55 // Unit in which the product is measured (liters, kilograms, packages, etc.). 56 unit: string; 57 58 // Optional override to control whether fractional quantities are permitted. 59 // Defaults to the policy implied by ``unit``. 60 unit_allow_fraction?: boolean; 61 62 // Override for the fractional precision level (0-6). Only relevant if 63 // ``unit_allow_fraction`` is true. Defaults come from ``unit``. 64 unit_precision_level?: Integer; 65 66 // Preferred way to express inventory counts using "<integer>[.<fraction>]" syntax. 67 // Use "-1" for unlimited stock. Required unless ``total_stock`` is provided. 68 unit_total_stock?: DecimalQuantity; 69 70 // Legacy stock counter. Deprecated, use ``unit_total_stock`` instead. 71 // Still required when ``unit_total_stock`` is omitted. 72 total_stock?: Integer; 73 74 // Preferred way to express the per-unit price of the product. Supply at least one entry; 75 // the first entry must match ``price``. 76 // The price given MUST include applicable taxes if ``price_is_net`` 77 // is false, and MUST exclude applicable taxes if ``price_is_net`` 78 // is true. 79 // Zero implies that the product is not sold separately or that the price must be supplied 80 // by the frontend. 81 // Each entry must use a distinct currency. 82 // Since API version **v25**. 83 // Currency uniqueness enforced since protocol **v25**. 84 unit_price?: Amount[]; 85 86 // True if the price(s) given are a net prices, false if they are 87 // gross prices. 88 // Since protocol **vTAXES**. 89 price_is_net?: boolean; 90 91 // Legacy price field. 92 // Deprecated since **v25**; 93 // when present it must match the first element of ``unit_price``. 94 price?: Amount; 95 96 // An optional base64-encoded product image. 97 image?: ImageDataUrl; 98 99 // A list of taxes paid by the merchant for one unit of this product. 100 taxes?: Tax[]; 101 102 // Identifies where the product is in stock. 103 address?: Location; 104 105 // Identifies when we expect the next restocking to happen. 106 next_restock?: Timestamp; 107 108 // Minimum age buyer must have (in years). Default is 0. 109 minimum_age?: Integer; 110 111 // Product group the product belongs to. 0 and missing both 112 // means default. 113 // Since **v25**. 114 product_group_id?: Integer; 115 116 // Money pot revenue on the product should be accounted in. 117 // 0 and missing both mean no money pot (revenue accounted 118 // in money pot of the overall order or not at all). 119 // Since **v25**. 120 money_pot_id?: Integer; 121 122 } 123 124 Clients SHOULD migrate to the new ``unit_*`` fields and treat ``total_stock`` and ``price`` 125 as deprecated compatibility shims. If both the legacy and the new representation are supplied, 126 their values must match. Omitting both ``unit_total_stock`` and ``total_stock`` (or both 127 ``unit_price`` and ``price``) results in a ``400 Bad Request``. When only ``price`` is given, 128 the backend treats it as a one-element ``unit_price`` array. 129 130 ``unit_total_stock`` uses a fixed-point decimal string in the form ``INTEGER[.FRACTION]`` with 131 at most six fractional digits. Scientific notation or special values such as ``NaN`` are not 132 accepted. Supply ``"-1"`` to represent unlimited stock. See 133 :ref:`DecimalQuantity <decimal-quantity>`. 134 135 Fractional behaviour defaults to the value of ``unit``. The backend disables fractions for 136 ``Piece``, ``Set``, ``Custom``, ``WeightUnitMg`` and ``SizeUnitMm``. Other predefined units 137 allow fractional quantities with the following default precision levels: 138 139 - Precision ``1``: ``WeightUnitG``, ``SizeUnitCm``, ``SurfaceUnitMm2``, ``VolumeUnitMm3``. 140 - Precision ``2``: ``WeightUnitOunce``, ``SizeUnitInch``, ``SurfaceUnitCm2``, 141 ``VolumeUnitInch3``, ``VolumeUnitOunce``, ``TimeUnitHour``, ``TimeUnitMonth``. 142 - Precision ``3``: ``WeightUnitTon``, ``WeightUnitKg``, ``WeightUnitPound``, ``SizeUnitM``, 143 ``SizeUnitDm``, ``SizeUnitFoot``, ``SurfaceUnitDm2``, ``SurfaceUnitFoot2``, ``VolumeUnitCm3``, 144 ``VolumeUnitLitre``, ``VolumeUnitGallon``, ``TimeUnitSecond``, ``TimeUnitMinute``, 145 ``TimeUnitDay``, ``TimeUnitWeek``. 146 - Precision ``4``: ``SurfaceUnitM2``, ``SurfaceUnitInch2``, ``TimeUnitYear``. 147 - Precision ``5``: ``VolumeUnitDm3``, ``VolumeUnitFoot3``. 148 - Precision ``6``: ``VolumeUnitM3``. 149 150 Integrations can override these defaults by explicitly setting ``unit_allow_fraction`` and/or 151 ``unit_precision_level``.