Синхронізація замовлень з інтернет-магазином через API

Що будуємо

Односторонній або двосторонній обмін замовленнями між Bimp і вашою системою (інтернет-магазин, CRM, маркетплейс): нові замовлення потрапляють у Bimp як замовлення покупця, а зміни статусів і оплат повертаються у вашу систему. Усі виклики виконуються з токеном компанії в заголовку access-token — див. Початок роботи з API.

Ключова ідея: кожне замовлення має пару ідентифікаторів. uuid — в Bimp, externalId — у вашій системі. Пару зберігає метод api-saveExternalId під назвою джерела source (наприклад, myshop). За цією парою ви шукаєте замовлення, а не за номером документа.

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

Крок	Метод	Навіщо
1	invoiceForCustomerPayment/api-readByExternalId	Перевірити, чи замовлення вже є в Bimp. Якщо є — перейти до оновлення (крок 8)
2	counterparty/api-readByExternalId	Знайти покупця за ID клієнта у вашій системі
3	counterparty/api-insert і counterparty/api-saveExternalId	Якщо покупця немає — створити (isCustomer: true) і зберегти зіставлення
4	nomenclature/api-readByExternalId	Знайти товар для кожної позиції (див. синхронізацію каталогу)
5	invoiceForCustomerPayment/api-create	Створити замовлення покупця з позиціями, складом, прайс-листом і статусом
6	invoiceForCustomerPayment/api-saveExternalId	Записати зіставлення uuid замовлення і номера у вашій системі
7	customerPayment/api-create	Зафіксувати оплату, якщо магазин прийняв її онлайн — див. Оплати через API
8	invoiceForCustomerPayment/api-updateStatus	Змінити статус замовлення в Bimp за подією у вашій системі
9	invoiceForCustomerPayment/api-cancel	Скасувати замовлення, якщо клієнт відмовився

Довідкові значення (організація, склад, прайс-лист, напрям діяльності, проєкт, статуси) отримайте один раз і збережіть у конфігурації інтеграції:

Що потрібно	Метод
Організація	organization/api-readList
Склад	warehouse/api-readList
Прайс-лист	priceList/api-readList
Напрям діяльності	lineOfBusiness/api-readList
Проєкт	project/api-readList
Договір покупця	contract/api-readList
Статуси замовлення	invoiceForCustomerPayment/api-readStatuses

Як створити замовлення в Bimp

Замовлення створюється одним запитом invoiceForCustomerPayment/api-create: обов’язковий покупець buyer, а позиції передаються масивом products, де для кожного рядка обов’язкові nomenclature і count.

curl -X POST https://app.bimpsoft.com/org2/invoiceForCustomerPayment/api-create \
  -H "access-token: $COMPANY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "buyer": "<buyer-uuid>",
    "organization": "<organization-uuid>",
    "contract": "<contract-uuid>",
    "warehouse": "<warehouse-uuid>",
    "priceList": "<price-list-uuid>",
    "status": "<status-uuid>",
    "date": "2026-11-06T10:15:00",
    "comment": "Замовлення myshop №10452",
    "deliveryMethod": "Нова Пошта",
    "deliveryAddress": "м. Київ, відділення №12",
    "recipient": "Іваненко Олена",
    "recipientPhone": "+380501112233",
    "products": [
      { "nomenclature": "<product-1-uuid>", "count": 2, "reserve": 2, "cost": 3100 },
      { "nomenclature": "<product-2-uuid>", "count": 1, "reserve": 1, "cost": 6200 }
    ]
  }'

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

{ "success": true, "data": { "uuid": "<order-uuid>" } }

Одразу збережіть зіставлення:

curl -X POST https://app.bimpsoft.com/org2/invoiceForCustomerPayment/api-saveExternalId \
  -H "access-token: $COMPANY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "orderUuid": "<order-uuid>", "source": "myshop", "externalId": "10452" }'

Правила для полів:

• date — у форматі YYYY-MM-DDTHH:MM:SS. Замовлення покупця не оформлюється майбутньою датою (див. Замовлення покупця), тому передавайте поточний або минулий момент.
• reserve — кількість до резервування. Резерв створюється в межах доступного залишку, як і в інтерфейсі: Резервування товарів.
• cost — ціна за одиницю.
• Номер документа Bimp присвоює сам. Власний номер можна передати в docNumber, але ідентифікувати замовлення за ним не варто — використовуйте зовнішній ID.

Як не створити дублі

Дублі виникають, коли api-create виконано, а відповідь не дійшла, і ваша система повторила виклик. Захист складається з трьох правил.

1. Спершу читайте. Перед кожним api-create викликайте invoiceForCustomerPayment/api-readByExternalId із вашим source і externalId. Відповідь "data": null означає, що замовлення немає.
2. Пишіть зіставлення негайно. api-saveExternalId — наступний виклик після api-create, до будь-якої іншої логіки.
3. Звіряйте дані. Раз на добу викликайте api-readExternalIdsList з фільтром source і порівнюйте з вашою базою замовлень. Метод api-readWithoutExternalId показує замовлення Bimp без зіставлення — наприклад, створені менеджерами вручну.

Назва source не залежить від регістру — її нормалізує система. Один source на одну зовнішню систему: не змішуйте магазин і маркетплейс. Детально про зіставлення — у статті Зовнішні ID. Окремого ключа ідемпотентності для api-create у специфікації немає, тому порядок «прочитати, створити, записати» обов’язковий.

Як отримувати зміни статусів

Найнадійніший спосіб — вебхук, а опитування лишається запасним.

Вебхук order_status. Створіть вебхук методом webhook/api-upsert з eventKind: "order_status", адресою url і списком statusIds — статусів, зміна яких вас цікавить. Те саме можна зробити в інтерфейсі: Налаштування компанії → Webhooks → Додати. Bimp надсилає на ваш URL JSON із замовленням: order_id, status (uuid і name), sumPayed, sumShipped, TTN, buyer, warehouse та масив products. Формат подій і вимоги до приймача — у статті Вебхуки.

curl -X POST https://app.bimpsoft.com/org2/webhook/api-upsert \
  -H "access-token: $COMPANY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "eventKind": "order_status",
    "name": "Статуси замовлень для myshop",
    "url": "https://shop.example.com/hooks/bimp-order-status",
    "enabled": true,
    "statusIds": [ { "name": "Оплачено", "GUID": "<status-uuid>" } ]
  }'

Вебхук містить order_id — uuid замовлення в Bimp. Щоб знайти замовлення у вашій системі, викличте api-readExternalIdsList з orderUuid або ведіть зворотну таблицю в себе.

Запасне опитування. Якщо вебхук недоступний або подію втрачено, раз на 5–10 хвилин викликайте invoiceForCustomerPayment/api-readList з періодом у changeStatusTime:

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 },
    "changeStatusTime": ["2026-11-06T09:00:00.000Z", "2026-11-06T09:10:00.000Z"]
  }'

У відповіді для кожного замовлення є status, sumOrdered, sumPayed, sumShipped, quantityShipped і TTN. Дати передавайте в UTC у форматі ISO 8601 із літерою Z. Кожне наступне вікно починайте з кінця попереднього, з невеликим перекриттям, і прибирайте повтори за uuid.

Як змінити статус із вашого боку

Метод invoiceForCustomerPayment/api-updateStatus приймає invoiceUuid і statusUuid:

curl -X POST https://app.bimpsoft.com/org2/invoiceForCustomerPayment/api-updateStatus \
  -H "access-token: $COMPANY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "invoiceUuid": "<order-uuid>", "statusUuid": "<status-uuid>" }'

Перелік доступних статусів повертає api-readStatuses (uuid, name, color). Зміна статусу може зняти резерв або закрити замовлення — залежно від налаштувань статусу, див. Статуси замовлення. Не відправляйте статус у відповідь на вебхук про той самий статус: так утворюється цикл.

Як змінити або скасувати замовлення

Для зміни використовуйте invoiceForCustomerPayment/api-update: обов’язкове поле uuid, решту передавайте за потреби (comment, TTN, deliveryAddress, status, позиції). Для скасування — api-cancel з uuid. Оплату, відвантаження і повернення створюють окремими документами: оплату — див. Оплати через API, відвантаження — salesInvoice/api-create з посиланням invoiceForCustomerPayment на замовлення.

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

Створилося два замовлення на одне замовлення магазину. Причина: api-create повторили без перевірки зіставлення. Рішення: додайте крок api-readByExternalId перед створенням і скасуйте зайвий документ методом api-cancel.

Помилка 429. Причина: з однієї IP-адреси надійшло понад 15 запитів на секунду, а черга з 30 запитів заповнена. Рішення: обмежте швидкість і повторюйте запит із затримкою. Подробиці — у статті Ліміти.

Токен більше не діє. Токен доступу живе 1 годину, токен оновлення — 1 тиждень. Оновіть пару методом auth/api-refresh, а після закінчення тижня увійдіть знову через auth/api-login. Для API використовуйте окремого користувача, а не основний обліковий запис: інакше сесія користувача в системі завершується автоматично.

Замовлення створилося без резерву. Причина: бракує доступного залишку або reserve не передано. Рішення: перевірте залишок (inventory/api-readList) і передайте reserve у рядку; причини — у статті Товар не резервується.

Товар за зовнішнім ID не знайдено. nomenclature/api-readByExternalId повертає null. Спершу синхронізуйте каталог — див. Синхронізація каталогу — або знайдіть товар за артикулом через nomenclature/api-readList (фільтр article) і запишіть зіставлення.