post-private-products-PRODUCT_ID-lock.rst (2581B)
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 :http:statuscode:`404 Not found`: 32 The backend has does not know this product. 33 :http:statuscode:`410 Gone`: 34 The backend does not have enough of product in stock. Returns an `OutOfStockResponse`. 35 :http:statuscode:`500 Internal Server Error`: 36 The server experienced an internal failure. 37 Returned with ``TALER_EC_GENERIC_DB_STORE_FAILED``. 38 39 **Details:** 40 41 .. ts:def:: LockRequest 42 43 interface LockRequest { 44 45 // UUID that identifies the frontend performing the lock 46 // Must be unique for the lifetime of the lock. 47 lock_uuid: string; 48 49 // How long does the frontend intend to hold the lock? 50 duration: RelativeTime; 51 52 // Legacy integer quantity to lock. Deprecated; defaults to 1 if both 53 // ``quantity`` and ``unit_quantity`` are absent. 54 quantity?: Integer; 55 56 // Preferred way to express the requested quantity using "<integer>[.<fraction>]" syntax. 57 unit_quantity?: string; 58 59 } 60 61 At least one of ``quantity`` or ``unit_quantity`` must be supplied; omitting both defaults to a 62 quantity of one. ``unit_quantity`` follows the same decimal-string format described for 63 ``unit_total_stock``. 64 65 .. note:: 66 67 The ``GNUNET_CRYPTO_random_timeflake()`` C API can be used 68 to generate such timeflakes for clients written in C.