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