post-private-products-PRODUCT_ID-lock.rst (2933B)
1 .. http:post:: [/instances/$INSTANCE]/private/products/$PRODUCT_ID/lock 2 3 This is used to lock a certain quantity of the product for a limited 4 duration while the customer assembles a complete order. Note that 5 frontends do not have to "unlock", they may rely on the timeout as 6 given in the ``duration`` field. Re-posting a lock with a different 7 ``duration`` or ``quantity`` updates the existing lock for the same UUID 8 and does not result in a conflict. 9 10 Unlocking by using a ``quantity`` of zero is 11 optional but recommended if customers remove products from the 12 shopping cart. Note that actually POSTing to ``/orders`` with set 13 ``inventory_products`` and using ``lock_uuids`` will **transition** the 14 lock to the newly created order (which may have a different ``duration`` 15 and ``quantity`` than what was requested in the lock operation). 16 If an order is for fewer items than originally locked, the difference 17 is automatically unlocked. 18 19 **Required permission:** ``products-lock`` 20 21 **Request:** 22 23 The request must be a `LockRequest`. 24 25 **Response:** 26 27 :http:statuscode:`204 No content`: 28 The backend has successfully locked (or unlocked) the requested ``quantity``. 29 :http:statuscode:`400 Bad Request`: 30 The request body is malformed. 31 Returned with ``TALER_EC_GENERIC_PARAMETER_MALFORMED``. 32 :http:statuscode:`404 Not found`: 33 The backend has does not know this product. 34 Returned with ``TALER_EC_MERCHANT_GENERIC_PRODUCT_UNKNOWN``. 35 :http:statuscode:`410 Gone`: 36 The backend does not have enough of product in stock. Returns an `OutOfStockResponse`. 37 Returned with ``TALER_EC_MERCHANT_PRIVATE_POST_PRODUCTS_LOCK_INSUFFICIENT_STOCKS``. 38 :http:statuscode:`500 Internal Server Error`: 39 The server experienced an internal failure. 40 Returned with ``TALER_EC_GENERIC_DB_STORE_FAILED``, 41 ``TALER_EC_GENERIC_DB_FETCH_FAILED``, 42 ``TALER_EC_GENERIC_DB_SOFT_FAILURE`` or 43 ``TALER_EC_GENERIC_INTERNAL_INVARIANT_FAILURE``. 44 45 **Details:** 46 47 .. ts:def:: LockRequest 48 49 interface LockRequest { 50 51 // UUID that identifies the frontend performing the lock 52 // Must be unique for the lifetime of the lock. 53 lock_uuid: string; 54 55 // How long does the frontend intend to hold the lock? 56 duration: RelativeTime; 57 58 // Legacy integer quantity to lock. Deprecated; defaults to 1 if both 59 // ``quantity`` and ``unit_quantity`` are absent. 60 quantity?: Integer; 61 62 // Preferred way to express the requested quantity using "<integer>[.<fraction>]" syntax. 63 unit_quantity?: string; 64 65 } 66 67 At least one of ``quantity`` or ``unit_quantity`` must be supplied; omitting both defaults to a 68 quantity of one. ``unit_quantity`` follows the same decimal-string format described for 69 ``unit_total_stock``. 70 71 .. note:: 72 73 The ``GNUNET_CRYPTO_random_timeflake()`` C API can be used 74 to generate such timeflakes for clients written in C.