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

URL: https://bimpsoft.com/help/developers/api-getting-started/
Updated: 2026-11-06

> API Bimp — це JSON-API за адресою https://app.bimpsoft.com. Для роботи потрібен окремий користувач для API. Спершу login повертає базовий токен, далі selectCompany обмінює його на токен компанії, який передається в заголовку access-token. Токен доступу живе 1 годину, токен оновлення — 1 тиждень.

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

Для роботи з API потрібен окремий користувач Bimp, створений саме для інтеграції. Підписка для нього оплачується за стандартними умовами. Створіть його, як описано в статті [Користувачі](https://bimpsoft.com/help/access/users/). Усі статті розділу зібрано на сторінці «[Для розробників](https://bimpsoft.com/help/developers/)».

> [!WARNING] Не використовуйте основний обліковий запис для 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`:

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

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

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

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

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

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

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

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

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

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

```bash
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` приймають необов'язкові фільтри (період, статус, організація, номер) |

Пагінацію, ліміти запитів і формат помилок описано в статті [Ліміти, пагінація і помилки](https://bimpsoft.com/help/developers/api-limits/). Зіставлення об'єктів Bimp з вашою системою — у статті [Зовнішні ID](https://bimpsoft.com/help/developers/api-external-ids/). Усі методи — у [довіднику API](https://bimpsoft.com/help/developers/api-reference/).

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

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

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

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

## FAQ

**Чи можна використовувати для API мій основний обліковий запис?**

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

**Як довго діє токен доступу до API?**

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

**У якому заголовку передавати токен: access-token чи Authorization?**

За специфікацією OpenAPI — у заголовку access-token. Старі примітки згадували Authorization: Bearer, але специфікація описує лише схему apiKey із заголовком access-token.

**Де знайти повний опис методів?**

У довіднику методів на сторінках ресурсів, а також в інтерактивній документації https://app.bimpsoft.com/docs.