Початок роботи з API Bimp: користувач, токени, перший запит

Що потрібно для роботи з API

Для роботи з API потрібен окремий користувач Bimp, створений саме для інтеграції. Підписка для нього оплачується за стандартними умовами. Створіть його, як описано в статті Користувачі. Усі статті розділу зібрано на сторінці «Для розробників».

Базова адреса API — https://app.bimpsoft.com. Усі шляхи методів починаються з /org2/, наприклад /org2/auth/api-login. Більшість методів — POST з тілом JSON; деякі (наприклад, залишки /org2/inventory/api-readList) — GET з параметрами в рядку запиту. Специфікація OpenAPI та інтерактивна документація доступні на https://app.bimpsoft.com/docs, репозиторій відстеження — https://github.com/Bimpsoft/public-api.

Які бувають токени

В API діють два типи JWT-токенів, які передаються в заголовку access-token:

Токен	Для чого	Як отримати
Базовий токен доступу (accessToken)	Запити, не прив’язані до компанії, наприклад список компаній	/org2/auth/api-login
Токен доступу компанії (companyAccessToken)	Усі запити до даних конкретної компанії	/org2/auth/api-selectCompany

Як отримати токен і зробити перший запит

Щоб зробити перший запит, увійдіть, знайдіть компанію, оберіть її і викличте потрібний метод.

1. Отримайте базовий токен. Надішліть email і пароль API-користувача на /org2/auth/api-login:

   curl -X POST https://app.bimpsoft.com/org2/auth/api-login \
     -H "Content-Type: application/json" \
     -d '{"email": "api-user@example.com", "password": "<PASSWORD>"}'

   Відповідь містить пару токенів:

   {
     "success": true,
     "data": {
       "accessToken": "<ACCESS_TOKEN>",
       "refreshToken": "<REFRESH_TOKEN>"
     }
   }

2. Знайдіть компанію. Викличте /org2/company/api-readDetailedList з базовим токеном (метод POST). У відповіді кожна компанія має поля name, uuid, code, createdAt:

   curl -X POST https://app.bimpsoft.com/org2/company/api-readDetailedList \
     -H "access-token: <ACCESS_TOKEN>"

3. Отримайте токен компанії. Передайте uuid або code компанії на /org2/auth/api-selectCompany з базовим токеном:

   curl -X POST https://app.bimpsoft.com/org2/auth/api-selectCompany \
     -H "access-token: <ACCESS_TOKEN>" \
     -H "Content-Type: application/json" \
     -d '{"code": "<COMPANY_CODE>"}'

   { "success": true, "data": { "companyAccessToken": "<COMPANY_ACCESS_TOKEN>" } }

4. Виконайте запит до даних компанії, передавши companyAccessToken у заголовку access-token. Наприклад, перші 10 замовлень покупців:

   curl -X POST https://app.bimpsoft.com/org2/invoiceForCustomerPayment/api-readList \
     -H "access-token: <COMPANY_ACCESS_TOKEN>" \
     -H "Content-Type: application/json" \
     -d '{"pagination": {"offset": 0, "count": 10}}'

Як оновити токен

Токен доступу (базовий або компанії) дійсний 1 годину, токен оновлення — 1 тиждень. Коли токен доступу спливає, надішліть refreshToken на /org2/auth/api-refresh:

curl -X POST https://app.bimpsoft.com/org2/auth/api-refresh \
  -H "access-token: <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"refreshToken": "<REFRESH_TOKEN>"}'

Відповідь має ту саму форму, що й у api-login: data.accessToken і data.refreshToken. Якщо спливає й токен оновлення, увійдіть знову через /org2/auth/api-login. Після оновлення базового токена повторіть api-selectCompany, щоб отримати свіжий токен компанії.

Для перевірки токена компанії є службовий метод /org2/auth/api-verifyCompanyAccess: він повертає дані авторизації, прив’язані до токена.

Загальні правила запитів і відповідей

Ці правила діють для більшості методів:

Тема	Правило
Формат	Тіло запиту і відповіді — JSON; заголовок Content-Type: application/json
Мова повідомлень	Заголовок Accept-Language, за замовчуванням uk-UA
Дати	ISO 8601 в UTC із завершальною Z, наприклад 2025-05-16T09:17:49.000Z; поле date документів — 2025-05-16T09:17:49
Ідентифікатори	Усі ID — UUID у форматі xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Успішна відповідь	{"success": true, "data": ...}
Необов’язкові поля	Поля, позначені в довіднику ?, можна не передавати
Фільтри	Більшість методів readList приймають необов’язкові фільтри (період, статус, організація, номер)

Пагінацію, ліміти запитів і формат помилок описано в статті Ліміти, пагінація і помилки. Зіставлення об’єктів Bimp з вашою системою — у статті Зовнішні ID. Усі методи — у довіднику API.

Типові проблеми

Сесія API-користувача в Bimp раптово завершується. Причина: інтеграція користується тим самим обліковим записом, що й людина. Рішення: створіть окремого користувача лише для API.

Запит повертає помилку авторизації після години роботи. Причина: токен доступу дійсний 1 годину. Рішення: оновіть його через /org2/auth/api-refresh, а коли спливе токен оновлення — увійдіть знову.

Запит до даних компанії не працює з базовим токеном. Причина: базовий токен не прив’язаний до компанії. Рішення: отримайте companyAccessToken через /org2/auth/api-selectCompany.