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

URL: https://bimpsoft.com/help/developers/sync-stock-and-prices/
Updated: 2026-11-06

> Для залишків використовуйте GET /org2/inventory/api-readList/cursor (повна вигрузка по складу) і вебхук inventory_balance (зміни майже в реальному часі). Для цін — nomenclature/api-readPrices з періодом або priceList/api-readPrice. Доступний залишок у відповіді — це quantity мінус reserved.

## Що будуємо

Регулярне оновлення залишків і цін товарів на сайті, маркетплейсі чи у вашій CRM. Схема: раз на початку — повна вигрузка, далі — події про зміни, а раз на добу — звірка, яка виправляє пропущене. Усі виклики виконуються з токеном компанії в заголовку `access-token` ([Початок роботи з API](https://bimpsoft.com/help/developers/api-getting-started/)). Зіставлення товарів сайту з товарами Bimp — за [зовнішнім ID](https://bimpsoft.com/help/developers/api-external-ids/) або артикулом: [Синхронізація каталогу](https://bimpsoft.com/help/developers/sync-catalog/).

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

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

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

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

```bash
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"
```

Відповідь:

```json
{
  "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` | Зарезервована кількість, див. [Резервування товарів](https://bimpsoft.com/help/sales/reserves/) |
| `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` надсилає подію, коли залишки змінилися: продаж, надходження, списання, [переміщення](https://bimpsoft.com/help/inventory/stock-transfer/). Створіть його методом `webhook/api-upsert`:

```bash
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` потрібного складу. Деталі приймача — у статті [Вебхуки](https://bimpsoft.com/help/developers/webhooks/).

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

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

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

```bash
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` — через скільки секунд повторити ([Ліміти](https://bimpsoft.com/help/developers/api-limits/)).
- **Розмір порції.** Для `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 відповідає успішним кодом — вимоги описані у статті Вебхуки.

## FAQ

**Який залишок передавати на сайт: фізичний чи доступний?**

Доступний (available) — це фізичний залишок мінус резерви. Саме його можна продати. Поле available повертають методи inventory/api-readList і вебхук inventory_balance (total_available).

**Як часто опитувати залишки?**

Краще підписатися на вебхук inventory_balance і раз на добу робити повну звірку. Якщо вебхука немає, опитуйте раз на 10–30 хвилин, не перевищуючи 15 запитів на секунду з IP.

**Як отримати залишки з розбивкою по партіях?**

Передайте параметр byBatches=true в inventory/api-readList або api-readList/cursor. Кожен рядок міститиме batchId.

**Як вивантажити ціни зі змінами за період?**

Викличте nomenclature/api-readPrices з periodable у вигляді [початок, кінець) і за потреби з priceListUuids.