Залишки

Залишки показують, скільки товару можна продати просто зараз. Їх можна отримати двома способами:

• блоком stock у кожного артикула в /products, /products/{id} і /skus, якщо ключ має право inventory:read;
• окремим списком /inventory. Йому потрібне лише право inventory:read, право на каталог не потрібне.

Що налаштовує власник#

У формі ключа є блок «Залишки». Він з’являється, коли позначено право «Бачити залишки». Як видати ключ, описано на сторінці «Ключі доступу та права».

«Як віддавати залишки».

• «Однією сумою» (типово). Ви отримуєте лише загальне число за всіма складами ключа, поля warehouses у відповіді немає.
• «По кожному складу». У відповіді є ще масив warehouses. У блоці stock у кожного складу вказано, скільки можна продати, а в /inventory ще й скільки лежить і скільки відкладено під замовлення.

«З яких складів».

• Порожньо (типово). Залишки рахуються за складами, з яких продає вітрина відповіді. Це ввімкнені справжні склади, у налаштуваннях яких не вибрано жодної вітрини або вибрано цю. У розбивці за складами приходять лише ті склади, де артикул лежить.
• Вибрано склади. Залишки рахуються лише за ними, навіть якщо вітрина з них не продає. Так дропшиперу показують окремий склад, який завели для нього. У розбивці завжди приходять усі вибрані склади в порядку пріоритету, навіть якщо артикула на складі немає. У такого складу приходить нуль.

Якщо власник вимкне вибраний склад, цей склад залишається у відповіді, але з нулем, бо продати з нього не можна. Залишки інших складів вітрини магазин замість нього не підставляє.

Якщо вибраний склад видалять або зроблять об’єднаним, він зникне з розбивки й нічого не додасть до available. У налаштуваннях ключа такий склад залишається, доки власник не прибере його сам, і на склади вітрини ключ не перемикається. Якщо так зникли всі вибрані склади, available приходить "0.000", а розбивка порожня.

Якщо власник перейменує, переставить, увімкне, вимкне чи видалить вибраний склад або зробить його об’єднаним, зміненими вважаються всі артикули магазину, і ви дізнаєтеся про це через updated_since.

Зміна налаштувань «Як віддавати залишки» і «З яких складів» артикули зміненими не робить, навіть якщо власник прибрав склад із налаштувань ключа. Про таку зміну ви дізнаєтеся з поля settings_changed_at у відповіді GET /api/v1/me. Якщо цей час став пізнішим за вашу минулу звірку, заберіть залишки повністю.

Правила підрахунку#

• На складі доступне те, що лежить, мінус відкладене під замовлення. Якщо замовлень набрали більше, ніж лежить, склад дає нуль, а не мінус.
• Підсумок available — сума доступного за складами. Перепроданий склад не зменшує залишок інших складів.
• Залишок не ведеться. Якщо в артикула не задано залишок, товар продається без обмеження. Тоді available дорівнює null, а in_stock дорівнює true, якщо артикул продається.
• Залишок задано, але не розкладено за складами. Так буває, коли склади в магазині ще не завели. За складами вітрини тоді приходить залишок артикула як є (не менше за нуль), а розбивка порожня. У ключа з власними складами такого залишку немає на жодному з них, і приходять нулі.
• Знято з продажу. Якщо is_available в артикула false, то in_stock і preorder дорівнюють false, скільки б товару ні лежало.
• Під замовлення. preorder дорівнює true, коли артикул продається, товару немає, але в налаштуваннях складів магазину ввімкнено «Дозволити замовлення, коли товару немає».
• Кількості приходять рядком із трьома знаками після крапки: "2.250". Товари бувають дробовими, їх продають метрами й кілограмами.

Блок stock в артикула#

"stock": {
    "available": "14.500",
    "in_stock": true,
    "preorder": false,
    "warehouses": [
        { "id": 1, "name": "Основний", "available": "12.000" },
        { "id": 3, "name": "Склад у Львові", "available": "2.500" }
    ]
}

GET /api/v1/inventory#

Залишки артикулів опублікованих товарів. Право: inventory:read. Порядок: за номером артикула, за зростанням.

Помилки ті самі, що в /skus: невідомий параметр, product_id не ціле додатне число, sku чи barcode списком, неправильні updated_since, after_id, limit, offset чи storefront_id. Для sku_ids помилки ті самі, що в /prices: у списку є щось, крім номерів, список порожній або в ньому понад 100 різних номерів.

Номери в sku_ids, яких немає або які належать неопублікованим товарам, магазин мовчки пропускає, а повтори рахує один раз. Звіряйте відповідь за полем sku_id.

curl "https://shop.example.ua/api/v1/inventory?product_id=1045" \
  -H "Authorization: Bearer <ключ>"

Ключ у прикладі налаштовано «По кожному складу», склади не вибрано.

{
    "data": [
        {
            "sku_id": 2108,
            "product_id": 1045,
            "sku": "730601",
            "is_available": true,
            "available": "14.500",
            "in_stock": true,
            "preorder": false,
            "warehouses": [
                { "id": 1, "name": "Основний", "qty": "15.000", "reserved": "3.000", "available": "12.000" },
                { "id": 3, "name": "Склад у Львові", "qty": "2.500", "reserved": "0.000", "available": "2.500" }
            ]
        },
        {
            "sku_id": 2109,
            "product_id": 1045,
            "sku": "730602",
            "is_available": true,
            "available": "0.000",
            "in_stock": false,
            "preorder": false,
            "warehouses": [
                { "id": 1, "name": "Основний", "qty": "1.000", "reserved": "3.000", "available": "0.000" }
            ]
        },
        {
            "sku_id": 2110,
            "product_id": 1045,
            "sku": "730603",
            "is_available": true,
            "available": null,
            "in_stock": true,
            "preorder": false,
            "warehouses": []
        }
    ],
    "meta": { "total": 3, "limit": 50, "offset": 0 },
    "links": { "next": null, "prev": null }
}

У другому артикулі прикладу під замовлення відкладено більше, ніж лежить, тому склад дає нуль. У третьому артикулі залишок не ведеться.

Щоб тримати наявність свіжою, раз на кілька хвилин запитуйте /inventory?updated_since=…&after_id=0 із часом минулої звірки мінус невеликий запас. Як обрати запас, описано в розділі «Зміни: updated_since». Якщо власник увімкнув вам повідомлення «Змінилися залишки», магазин сам повідомить номери артикулів, у яких змінилися залишки на складах вашого ключа. Ці номери передайте в sku_ids, а повну звірку можна робити рідше. Як приймати таке повідомлення, описано на сторінці «Повідомлення партнерові (вебхуки)».