# Вивантаження даних Bimp для аналітики через API

URL: https://bimpsoft.com/help/developers/bi-export-via-api/
Updated: 2026-11-06

> Для власної аналітики читайте дані методами api-readList з пагінацією offset/count (до 100 записів) і періодом periodable, а залишки — курсорним inventory/api-readList/cursor. Повну вигрузку робіть один раз, далі завантажуйте лише зміни за період. Якщо потрібні готові таблиці для Looker Studio чи Power BI, використайте інтеграцію з BigQuery.

## Що будуємо

Регулярне вивантаження даних Bimp (продажі, закупівлі, залишки, ціни, гроші) у ваше сховище, дашборд чи BI-систему. Якщо вам достатньо готових звітів у Looker Studio або Power BI, скористайтеся інтеграцією з BigQuery: [BigQuery і Looker Studio](https://bimpsoft.com/help/bi/bigquery-looker-studio/), [Power BI](https://bimpsoft.com/help/bi/power-bi/), [Довідник полів BigQuery](https://bimpsoft.com/help/bi/bigquery-fields/). API підходить, коли потрібно самостійно вибрати набір полів, розклад і місце зберігання. Токен компанії передається в заголовку `access-token` ([Початок роботи з API](https://bimpsoft.com/help/developers/api-getting-started/)).

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

| Крок | Метод | Що вивантажуємо |
|---|---|---|
| 1 | [`organization/api-readList`](/help/developers/api-reference/organization/#api-read-list), [`warehouse/api-readList`](/help/developers/api-reference/warehouse/#api-read-list), [`currency/api-readList`](/help/developers/api-reference/currency/#api-read-list), [`lineOfBusiness/api-readList`](/help/developers/api-reference/line-of-business/#api-read-list), [`project/api-readList`](/help/developers/api-reference/project/#api-read-list) | Довідники для розшифрування `uuid` у звітах |
| 2 | [`counterparty/api-readList`](/help/developers/api-reference/counterparty/#api-read-list), [`nomenclature/api-readList`](/help/developers/api-reference/nomenclature/#api-read-list), [`nomenclature-group/api-readList`](/help/developers/api-reference/nomenclature-group/#api-read-list) | Контрагенти, товари, групи |
| 3 | [`invoiceForCustomerPayment/api-readList`](/help/developers/api-reference/invoice-for-customer-payment/#api-read-list) і `invoiceForCustomerPayment/api-read` | [Замовлення покупців](https://bimpsoft.com/help/sales/customer-order/): шапка і позиції |
| 4 | [`salesInvoice/api-readList`](/help/developers/api-reference/sales-invoice/#api-read-list) і `salesInvoice/api-read` | [Відвантаження](https://bimpsoft.com/help/sales/shipment/) (продаж товарів і послуг) |
| 5 | [`customerPayment/api-readList`](/help/developers/api-reference/customer-payment/#api-read-list) | Оплати від покупців |
| 6 | [`invoiceForSupplierPayment/api-readList`](/help/developers/api-reference/invoice-for-supplier-payment/#api-read-list), [`purchaseInvoice/api-readList`](/help/developers/api-reference/purchase-invoice/#api-read-list), [`paymentToSupplier/api-readList`](/help/developers/api-reference/payment-to-supplier/#api-read-list) | Закупівлі: замовлення, надходження, оплати |
| 7 | [`inventory/api-readList/cursor`](/help/developers/api-reference/inventory/) і `nomenclature/api-readLeftovers` | Поточні залишки і залишки на дату або їх зміна за період |
| 8 | `nomenclature/api-readPrices` | Ціни по [прайс-листах](https://bimpsoft.com/help/pricing/price-lists/) |
| 9 | [`financing-balance/api-readList`](/help/developers/api-reference/financing-balance/#api-read-list) | Залишки коштів на рахунках і в касах |
| 10 | [`otherExpenses/api-readList`](/help/developers/api-reference/other-expenses/#api-read-list), [`otherIncome/api-readList`](/help/developers/api-reference/other-income/#api-read-list) | Витрати й доходи |

## Як читати великі списки

Усі методи `api-readList` повертають дані порціями. Є три способи пагінації:

| Спосіб | Де застосовується | Параметри |
|---|---|---|
| `offset` і `count` | Більшість POST-методів | `pagination: { "offset": 0, "count": 100 }`, максимум `count` — 100 |
| Курсор | `inventory/api-readList/cursor` | `limit` (до 200), `lastId`; відповідь повертає `next_cursor` |
| Номер сторінки | `inventory/api-readList` | `page` і `pageSize` (до 100) |

Приклад пакетного читання замовлень за період:

```bash
curl -X POST https://app.bimpsoft.com/org2/invoiceForCustomerPayment/api-readList \
  -H "access-token: $COMPANY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "pagination": { "offset": 0, "count": 100 },
    "periodable": ["2026-10-01T00:00:00.000Z", "2026-10-31T23:59:59.999Z"]
  }'
```

Збільшуйте `offset` на `count`, доки відповідь не стане порожньою або коротшою за `count`. Дати передавайте в UTC у форматі ISO 8601 із літерою `Z`.

Щоб читання було стабільним, поки дані змінюються, сортуйте результат у своєму сховищі за `uuid` і робіть upsert (вставка або оновлення за `uuid`), а не додавання.

## Як завантажувати лише зміни

Повну вигрузку виконуйте один раз, потім переходьте на інкременти. Фільтри за часом залежать від ресурсу:

| Ресурс | Фільтр часу | Що означає |
|---|---|---|
| Замовлення покупців | `periodable` | Період за датою документа |
| Замовлення покупців | `changeStatusTime` | Період зміни статусу |
| Відвантаження, надходження, оплати | `periodable` | Період за датою документа |
| Номенклатура | `created`, `updated` | Пара дат `[від, до]` (кожну можна замінити `null`) |
| Ціни | `periodable` у `nomenclature/api-readPrices` | Ціни або їх зміни за період `[початок, кінець)` |
| Залишки | `periodable` у `nomenclature/api-readLeftovers` | Залишок на дату або зміна за період |
| Контрагенти | `periodable` | Період у `counterparty/api-readList` |

Алгоритм інкременту:

1. Перед початком запуску запишіть поточний час `T_start`.
2. Прочитайте дані за період `[T_prev, T_start]`, де `T_prev` — час початку попереднього успішного запуску. Беріть невелике перекриття (5–10 хвилин) і прибирайте повтори за `uuid`.
3. Після успішного завершення збережіть `T_start` як `T_prev`.

Фільтр за датою документа не бачить змін, зроблених у старих документах. Тому раз на добу або раз на тиждень перечитуйте глибший період (наприклад, останні 30 днів) і перезаписуйте його. Про документ, змінений заднім числом, вебхуки не повідомляють. 

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

- **Поточні залишки** — `GET /org2/inventory/api-readList/cursor` з `orgId`, `warehouseId` і `limit=200`. З `byBatches=true` кожен рядок розбивається за партіями.
- **Залишок на дату або зміна за період** — `nomenclature/api-readLeftovers` з `periodable` (пара `[початок, кінець]`), необов'язковими `warehouseUuid` і `nomenclatureUuids`. Відповідь: `uuid`, `name`, `leftover`.
- **Залишки, [резерви](https://bimpsoft.com/help/sales/reserves/) і собівартість** — `nomenclature/api-readStocks`: `stock`, `reserve`, `leftover`, `minimumLeftover`, `maximumLeftover`, `primeCost` (фільтри `warehouseUuid[]`, `nomenclatureUuid[]`).
- **Партії** — `nomenclature/api-readBatches` (`nomenclatureUuid`): дата надходження, кількість, ціна, постачальник, термін придатності (`shelfLife`).
- **Ціни** — `nomenclature/api-readPrices`; деталі й приклади — у статті [Вивантаження залишків і цін](https://bimpsoft.com/help/developers/sync-stock-and-prices/).

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

## Як організувати завантаження

1. **Довідники — першими.** Завантажте організації, склади, валюти, проєкти, [напрями діяльності](https://bimpsoft.com/help/getting-started/projects-and-business-directions/), групи й товари. Документи містять лише `uuid` цих об'єктів.
2. **Документи — за періодами.** Обробляйте місяць за місяцем, щоб при збої повторювати лише один період.
3. **Деталізація.** `api-readList` повертає шапку документа (для замовлень покупців — масив `products` лише з uuid рядків). Позиції з кількістю, ціною й знижкою повертає `api-read` за `uuid` документа. Для великих обсягів плануйте по одному `api-read` на документ.
4. **Швидкість.** Не перевищуйте 15 запитів на секунду з одного IP, інакше запити потраплять у чергу, а надлишок — отримає 429. Запускайте паралельні потоки обережно і ставте паузу при 429 ([Ліміти](https://bimpsoft.com/help/developers/api-limits/)).
5. **Токен.** Токен доступу діє 1 годину: у довгих вивантаженнях оновлюйте його методом `auth/api-refresh`, а після закінчення тижня входьте знову.
6. **Окремий користувач.** Для вивантаження створіть окремого API-користувача з правами лише на читання потрібних розділів: [Ролі та права доступу](https://bimpsoft.com/help/access/roles/).

## Вебхуки замість опитування

Для оперативних показників (залишки, статуси замовлень, зміни товарів) підписуйтесь на вебхуки `inventory_balance`, `order_status`, `product_upsert` і складайте події в сховище — це дешевше за часте опитування. Вебхуки не замінюють повну вигрузку: пропущена подія не повторюється, тому раз на добу робіть звірку. Формат подій — у статті [Вебхуки](https://bimpsoft.com/help/developers/webhooks/).

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

**У звіті замість назв — довгі `uuid`.** Причина: у `api-readList` поля `buyer`, `status`, `warehouse` повертаються як `uuid`. Рішення: завантажте довідники й зв'яжіть їх у сховищі.

**Дані задвоїлись.** Причина: інкремент із перекриттям записує повторні рядки. Рішення: upsert за `uuid`.

**Суми не збігаються зі звітами Bimp.** Причина: у вивантаженні не враховано скасовані документи, валюту або ПДВ. Рішення: звіряйте з потрібним звітом у Bimp на тому самому періоді; для швидкої звірки використовуйте [Рух грошових коштів](https://bimpsoft.com/help/reports/cash-flow-report/). Позначки `managerialAccounting` і `bookkeperAccounting` у відвантаженнях і надходженнях розділяють управлінський та бухгалтерський облік.

**Помилка 429 при масовому читанні.** Перевищено 15 запитів на секунду. Зменште паралельність і повторюйте запит із паузою.

**Дані за ранні періоди порожні.** Причина: передано `periodable` не в UTC або без `Z`. Рішення: використовуйте формат `2026-10-01T00:00:00.000Z`.

## FAQ

**Чим вивантаження через API відрізняється від BigQuery-інтеграції?**

BigQuery-інтеграція автоматично дає готові таблиці в сховищі Google для Looker Studio і Power BI. API потрібне, коли ви завантажуєте дані у власне сховище або сервіс і самі керуєте набором полів та розкладом.

**Як завантажувати лише нові й змінені дані?**

Передавайте періоди: periodable (для документів), changeStatusTime (замовлення покупців), created і updated (номенклатура). Запам'ятовуйте час останнього успішного запуску і беріть його як початок наступного періоду.

**Скільки записів повертає один запит?**

У POST-методів із pagination — до 100 (count). Курсорний inventory/api-readList/cursor — до 200 (limit).

**Які ліміти на запити?**

15 запитів на секунду з одного IP, далі черга з 30 запитів, решта отримує 429.