Остатки

Остатки показывают, сколько товара можно продать прямо сейчас. Их можно получить двумя способами:

• блоком 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, а полную сверку можно делать реже. Как принимать такое сообщение, описано на странице «Сообщения партнёру (вебхуки)».