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

Що будуємо

Регулярне вивантаження даних Bimp (продажі, закупівлі, залишки, ціни, гроші) у ваше сховище, дашборд чи BI-систему. Якщо вам достатньо готових звітів у Looker Studio або Power BI, скористайтеся інтеграцією з BigQuery: BigQuery і Looker Studio, Power BI, Довідник полів BigQuery. API підходить, коли потрібно самостійно вибрати набір полів, розклад і місце зберігання. Токен компанії передається в заголовку access-token (Початок роботи з API).

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

Крок	Метод	Що вивантажуємо
1	organization/api-readList, warehouse/api-readList, currency/api-readList, lineOfBusiness/api-readList, project/api-readList	Довідники для розшифрування uuid у звітах
2	counterparty/api-readList, nomenclature/api-readList, nomenclature-group/api-readList	Контрагенти, товари, групи
3	invoiceForCustomerPayment/api-readList і invoiceForCustomerPayment/api-read	Замовлення покупців: шапка і позиції
4	salesInvoice/api-readList і salesInvoice/api-read	Відвантаження (продаж товарів і послуг)
5	customerPayment/api-readList	Оплати від покупців
6	invoiceForSupplierPayment/api-readList, purchaseInvoice/api-readList, paymentToSupplier/api-readList	Закупівлі: замовлення, надходження, оплати
7	inventory/api-readList/cursor і nomenclature/api-readLeftovers	Поточні залишки і залишки на дату або їх зміна за період
8	nomenclature/api-readPrices	Ціни по прайс-листах
9	financing-balance/api-readList	Залишки коштів на рахунках і в касах
10	otherExpenses/api-readList, otherIncome/api-readList	Витрати й доходи

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

Усі методи 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)

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

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.
• Залишки, резерви і собівартість — nomenclature/api-readStocks: stock, reserve, leftover, minimumLeftover, maximumLeftover, primeCost (фільтри warehouseUuid[], nomenclatureUuid[]).
• Партії — nomenclature/api-readBatches (nomenclatureUuid): дата надходження, кількість, ціна, постачальник, термін придатності (shelfLife).
• Ціни — nomenclature/api-readPrices; деталі й приклади — у статті Вивантаження залишків і цін.

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

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

1. Довідники — першими. Завантажте організації, склади, валюти, проєкти, напрями діяльності, групи й товари. Документи містять лише uuid цих об’єктів.
2. Документи — за періодами. Обробляйте місяць за місяцем, щоб при збої повторювати лише один період.
3. Деталізація. api-readList повертає шапку документа (для замовлень покупців — масив products лише з uuid рядків). Позиції з кількістю, ціною й знижкою повертає api-read за uuid документа. Для великих обсягів плануйте по одному api-read на документ.
4. Швидкість. Не перевищуйте 15 запитів на секунду з одного IP, інакше запити потраплять у чергу, а надлишок — отримає 429. Запускайте паралельні потоки обережно і ставте паузу при 429 (Ліміти).
5. Токен. Токен доступу діє 1 годину: у довгих вивантаженнях оновлюйте його методом auth/api-refresh, а після закінчення тижня входьте знову.
6. Окремий користувач. Для вивантаження створіть окремого API-користувача з правами лише на читання потрібних розділів: Ролі та права доступу.

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

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

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

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

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

Суми не збігаються зі звітами Bimp. Причина: у вивантаженні не враховано скасовані документи, валюту або ПДВ. Рішення: звіряйте з потрібним звітом у Bimp на тому самому періоді; для швидкої звірки використовуйте Рух грошових коштів. Позначки managerialAccounting і bookkeperAccounting у відвантаженнях і надходженнях розділяють управлінський та бухгалтерський облік.

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

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