Вивантаження залишків і цін на сайт через API

Що будуємо

Регулярне оновлення залишків і цін товарів на сайті, маркетплейсі чи у вашій CRM. Схема: раз на початку — повна вигрузка, далі — події про зміни, а раз на добу — звірка, яка виправляє пропущене. Усі виклики виконуються з токеном компанії в заголовку access-token (Початок роботи з API). Зіставлення товарів сайту з товарами Bimp — за зовнішнім ID або артикулом: Синхронізація каталогу.

Які методи і в якому порядку

Крок	Метод	Навіщо
1	organization/api-readList і warehouse/api-readList	Отримати orgId і warehouseId для запитів залишків
2	inventory/api-readList/cursor	Повна вигрузка залишків складу з курсорною пагінацією
3	webhook/api-upsert (inventory_balance)	Отримувати зміни залишків подією, без опитування
4	inventory/api-read/{productHex}/stock	Точково перевірити доступність товару перед оформленням замовлення
5	priceList/api-readList	Знайти потрібний прайс-лист (поле main — основний)
6	nomenclature/api-readPrices	Ціни товарів у прайс-листах, зокрема зміни за період
7	priceList/api-readPrice	Усі ціни одного прайс-листа

Як вивантажити залишки

Метод GET /org2/inventory/api-readList/cursor повертає залишки складу порціями. Обов’язкові параметри запиту: orgId (організація) і warehouseId (склад). limit — від 1 до 200 (за замовчуванням 50), lastId — курсор для наступної порції.

curl -G https://app.bimpsoft.com/org2/inventory/api-readList/cursor \
  -H "access-token: $COMPANY_TOKEN" \
  --data-urlencode "orgId=<organization-uuid>" \
  --data-urlencode "warehouseId=<warehouse-uuid>" \
  --data-urlencode "limit=200"

Відповідь:

{
  "success": true,
  "data": {
    "items": [
      { "productId": "<product-uuid>", "barcode": "4820000000012", "quantity": 25, "reserved": 5, "available": 20 }
    ],
    "next_cursor": "<last-product-uuid>"
  }
}

Щоб отримати наступну порцію, передайте next_cursor у параметрі lastId. Закінчуйте, коли порція порожня.

Поля залишку:

Поле	Що означає
quantity	Фізичний залишок на складі
reserved	Зарезервована кількість, див. Резервування товарів
available	Доступна кількість: quantity мінус reserved
barcode	Штрихкод; може бути порожнім
batchId	Партія, лише при byBatches=true (тоді додайте lastBatchId для курсору, значення з next_cursor_batch_id)

Є також версія з номерами сторінок — GET /org2/inventory/api-readList з параметрами page і pageSize (до 100) та сортуванням sortBy (productId, quantity, reserved, available) і sortDirection. Для повної вигрузки надійніший курсор: він не «з’їжджає», якщо дані змінюються під час читання.

Залишки по кількох складах отримуйте окремими запитами по кожному warehouseId. Альтернатива з одним запитом на кілька складів — nomenclature/api-readStocks (фільтри warehouseUuid[], nomenclatureUuid[], пагінація offset/count); у відповіді є stock, reserve, leftover, minimumLeftover, maximumLeftover і primeCost.

Як отримувати зміни залишків вебхуком

Вебхук inventory_balance надсилає подію, коли залишки змінилися: продаж, надходження, списання, переміщення. Створіть його методом webhook/api-upsert:

curl -X POST https://app.bimpsoft.com/org2/webhook/api-upsert \
  -H "access-token: $COMPANY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "eventKind": "inventory_balance",
    "name": "Залишки для сайту",
    "url": "https://shop.example.com/hooks/bimp-stock",
    "enabled": true,
    "warehouseIds": [ { "name": "Основний склад", "GUID": "<warehouse-uuid>" } ]
  }'

У warehouseIds вказують склади, зміни на яких вас цікавлять. У події приходять id товару, barcode, sku, name, total_physical, total_reserved, total_available, масив stock_details по складах (storage_id, physical, reserved, available) і timestamp. На сайт передавайте total_available або available потрібного складу. Деталі приймача — у статті Вебхуки.

Події можуть надходити частіше, ніж ви встигаєте їх обробляти. Порівнюйте timestamp і не перезаписуйте новіше значення старішим.

Як вивантажити ціни

Ціни зберігаються в прайс-листах (Прайс-листи). Метод nomenclature/api-readPrices повертає для кожного товару ціни по прайс-листах. Обов’язковий параметр — periodable: момент часу або період [початок, кінець). Значення null або [null, null] означає весь період, [null, "дата"] — до дати, ["дата", null] — від дати.

curl -X POST https://app.bimpsoft.com/org2/nomenclature/api-readPrices \
  -H "access-token: $COMPANY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "priceListUuids": ["<price-list-uuid>"],
    "periodable": ["2026-11-05T00:00:00.000Z", "2026-11-06T00:00:00.000Z"],
    "pagination": { "offset": 0, "count": 100 }
  }'

У відповіді для кожного товару є uuid, name і масив priceLists: uuid, name, price та currency (uuid, iso, symbol).

Для повної вигрузки одного прайс-листа використовуйте priceList/api-readPrice з priceListUuid: відповідь — список товарів із масивом prices (amount, date, currency). Для списку прайс-листів — priceList/api-readList; поле main: true позначає основний.

Для коректної роботи з валютами порівнюйте currency.iso у відповіді з валютою вашого сайту: курси не перераховуються автоматично. Як ведуться ціни у валюті — Прайс-листи.

Як не перевантажити API

• Ліміт — 15 запитів на секунду з одного IP, далі черга з 30 запитів, решта отримує помилку 429. Для методів inventory у відповіді 429 є retryAfter — через скільки секунд повторити (Ліміти).
• Розмір порції. Для inventory/api-readList/cursor беріть limit=200, для POST-методів із pagination — count=100 (максимум).
• Вебхуки замість частого опитування. Повну вигрузку робіть при старті і раз на добу вночі, а протягом дня живіть на подіях.
• Не опитуйте по одному товару. Метод inventory/api-read/{productHex}/stock підходить для перевірки перед оформленням, але не для масового оновлення.

Типові помилки

Залишок на сайті більший, ніж доступний у Bimp. Причина: ви передаєте quantity замість available і не враховуєте резерв. Рішення: передавайте available.

Відповідь 422 на запит залишків. Причина: не передано обов’язкові orgId або warehouseId, або вони не є UUID. Рішення: отримайте значення з organization/api-readList і warehouse/api-readList.

Відповідь 404 на inventory/api-read/{productHex}/stock. Причина: товару немає в залишках цього складу або ідентифікатор невірний. Шлях приймає productHex у вигляді 0x… (16–32 шістнадцяткових символи) або UUID.

Ціни на сайті не збігаються з Bimp. Причина: вивантажено не той прайс-лист або валюту. Рішення: перевіряйте priceLists[].uuid і currency.iso.

Вебхук перестав надходити. Перевірте, що вебхук увімкнений (enabled) і що ваш URL відповідає успішним кодом — вимоги описані у статті Вебхуки.