# Синхронізація замовлень з інтернет-магазином через API URL: https://bimpsoft.com/help/developers/sync-orders/ Updated: 2026-11-06 > Щоб синхронізувати замовлення, створюйте в Bimp замовлення покупця методом invoiceForCustomerPayment/api-create і одразу зберігайте номер замовлення вашої системи через api-saveExternalId. Перед створенням перевіряйте api-readByExternalId — так не виникає дублів. Зміни статусів з Bimp отримуйте вебхуком order_status, а зі свого боку змінюйте статус методом api-updateStatus. ## Що будуємо Односторонній або двосторонній обмін замовленнями між Bimp і вашою системою (інтернет-магазин, CRM, маркетплейс): нові замовлення потрапляють у Bimp як [замовлення покупця](https://bimpsoft.com/help/sales/customer-order/), а зміни статусів і оплат повертаються у вашу систему. Усі виклики виконуються з токеном компанії в заголовку `access-token` — див. [Початок роботи з API](https://bimpsoft.com/help/developers/api-getting-started/). Ключова ідея: кожне замовлення має пару ідентифікаторів. `uuid` — в Bimp, `externalId` — у вашій системі. Пару зберігає метод `api-saveExternalId` під назвою джерела `source` (наприклад, `myshop`). За цією парою ви шукаєте замовлення, а не за номером документа. ## Які методи і в якому порядку | Крок | Метод | Навіщо | |---|---|---| | 1 | [`invoiceForCustomerPayment/api-readByExternalId`](/help/developers/api-reference/invoice-for-customer-payment/#api-read-by-external-id) | Перевірити, чи замовлення вже є в Bimp. Якщо є — перейти до оновлення (крок 8) | | 2 | [`counterparty/api-readByExternalId`](/help/developers/api-reference/counterparty/#api-read-by-external-id) | Знайти покупця за ID клієнта у вашій системі | | 3 | `counterparty/api-insert` і `counterparty/api-saveExternalId` | Якщо покупця немає — створити (`isCustomer: true`) і зберегти зіставлення | | 4 | [`nomenclature/api-readByExternalId`](/help/developers/api-reference/nomenclature/#api-read-by-external-id) | Знайти товар для кожної позиції (див. [синхронізацію каталогу](https://bimpsoft.com/help/developers/sync-catalog/)) | | 5 | `invoiceForCustomerPayment/api-create` | Створити замовлення покупця з позиціями, складом, [прайс-листом](https://bimpsoft.com/help/pricing/price-lists/) і статусом | | 6 | `invoiceForCustomerPayment/api-saveExternalId` | Записати зіставлення `uuid` замовлення і номера у вашій системі | | 7 | [`customerPayment/api-create`](/help/developers/api-reference/customer-payment/#api-create) | Зафіксувати оплату, якщо магазин прийняв її онлайн — див. [Оплати через API](https://bimpsoft.com/help/developers/payments-via-api/) | | 8 | `invoiceForCustomerPayment/api-updateStatus` | Змінити статус замовлення в Bimp за подією у вашій системі | | 9 | `invoiceForCustomerPayment/api-cancel` | Скасувати замовлення, якщо клієнт відмовився | Довідкові значення (організація, склад, прайс-лист, [напрям діяльності](https://bimpsoft.com/help/getting-started/projects-and-business-directions/), проєкт, статуси) отримайте один раз і збережіть у конфігурації інтеграції: | Що потрібно | Метод | |---|---| | Організація | [`organization/api-readList`](/help/developers/api-reference/organization/#api-read-list) | | [Склад](https://bimpsoft.com/help/inventory/warehouses/) | [`warehouse/api-readList`](/help/developers/api-reference/warehouse/#api-read-list) | | Прайс-лист | [`priceList/api-readList`](/help/developers/api-reference/price-list/#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) | | Договір покупця | [`contract/api-readList`](/help/developers/api-reference/contract/#api-read-list) | | Статуси замовлення | `invoiceForCustomerPayment/api-readStatuses` | ## Як створити замовлення в Bimp Замовлення створюється одним запитом `invoiceForCustomerPayment/api-create`: обов'язковий покупець `buyer`, а позиції передаються масивом `products`, де для кожного рядка обов'язкові `nomenclature` і `count`. ```bash curl -X POST https://app.bimpsoft.com/org2/invoiceForCustomerPayment/api-create \ -H "access-token: $COMPANY_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "buyer": "", "organization": "", "contract": "", "warehouse": "", "priceList": "", "status": "", "date": "2026-11-06T10:15:00", "comment": "Замовлення myshop №10452", "deliveryMethod": "Нова Пошта", "deliveryAddress": "м. Київ, відділення №12", "recipient": "Іваненко Олена", "recipientPhone": "+380501112233", "products": [ { "nomenclature": "", "count": 2, "reserve": 2, "cost": 3100 }, { "nomenclature": "", "count": 1, "reserve": 1, "cost": 6200 } ] }' ``` Відповідь містить `uuid` нового документа: ```json { "success": true, "data": { "uuid": "" } } ``` Одразу збережіть зіставлення: ```bash curl -X POST https://app.bimpsoft.com/org2/invoiceForCustomerPayment/api-saveExternalId \ -H "access-token: $COMPANY_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "orderUuid": "", "source": "myshop", "externalId": "10452" }' ``` Правила для полів: - `date` — у форматі `YYYY-MM-DDTHH:MM:SS`. Замовлення покупця не оформлюється майбутньою датою (див. Замовлення покупця), тому передавайте поточний або минулий момент. - `reserve` — кількість до резервування. Резерв створюється в межах доступного залишку, як і в інтерфейсі: [Резервування товарів](https://bimpsoft.com/help/sales/reserves/). - `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](https://bimpsoft.com/help/developers/api-external-ids/). Окремого ключа ідемпотентності для `api-create` у специфікації немає, тому порядок «прочитати, створити, записати» обов'язковий. ## Як отримувати зміни статусів Найнадійніший спосіб — вебхук, а опитування лишається запасним. **Вебхук `order_status`.** Створіть вебхук методом [`webhook/api-upsert`](/help/developers/api-reference/webhook/#api-upsert) з `eventKind: "order_status"`, адресою `url` і списком `statusIds` — статусів, зміна яких вас цікавить. Те саме можна зробити в інтерфейсі: **Налаштування компанії → Webhooks → Додати**. Bimp надсилає на ваш URL JSON із замовленням: `order_id`, `status` (`uuid` і `name`), `sumPayed`, `sumShipped`, `TTN`, `buyer`, `warehouse` та масив `products`. Формат подій і вимоги до приймача — у статті [Вебхуки](https://bimpsoft.com/help/developers/webhooks/). ```bash 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": "" } ] }' ``` Вебхук містить `order_id` — uuid замовлення в Bimp. Щоб знайти замовлення у вашій системі, викличте `api-readExternalIdsList` з `orderUuid` або ведіть зворотну таблицю в себе. **Запасне опитування.** Якщо вебхук недоступний або подію втрачено, раз на 5–10 хвилин викликайте `invoiceForCustomerPayment/api-readList` з періодом у `changeStatusTime`: ```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 }, "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`: ```bash curl -X POST https://app.bimpsoft.com/org2/invoiceForCustomerPayment/api-updateStatus \ -H "access-token: $COMPANY_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "invoiceUuid": "", "statusUuid": "" }' ``` Перелік доступних статусів повертає `api-readStatuses` (`uuid`, `name`, `color`). Зміна статусу може зняти резерв або закрити замовлення — залежно від налаштувань статусу, див. [Статуси замовлення](https://bimpsoft.com/help/sales/order-statuses/). Не відправляйте статус у відповідь на вебхук про той самий статус: так утворюється цикл. ## Як змінити або скасувати замовлення Для зміни використовуйте `invoiceForCustomerPayment/api-update`: обов'язкове поле `uuid`, решту передавайте за потреби (`comment`, `TTN`, `deliveryAddress`, `status`, позиції). Для скасування — `api-cancel` з `uuid`. Оплату, [відвантаження](https://bimpsoft.com/help/sales/shipment/) і повернення створюють окремими документами: оплату — див. Оплати через API, відвантаження — [`salesInvoice/api-create`](/help/developers/api-reference/sales-invoice/#api-create) з посиланням `invoiceForCustomerPayment` на замовлення. ## Типові помилки **Створилося два замовлення на одне замовлення магазину.** Причина: `api-create` повторили без перевірки зіставлення. Рішення: додайте крок `api-readByExternalId` перед створенням і скасуйте зайвий документ методом `api-cancel`. **Помилка 429.** Причина: з однієї IP-адреси надійшло понад 15 запитів на секунду, а черга з 30 запитів заповнена. Рішення: обмежте швидкість і повторюйте запит із затримкою. Подробиці — у статті [Ліміти](https://bimpsoft.com/help/developers/api-limits/). **Токен більше не діє.** Токен доступу живе 1 годину, токен оновлення — 1 тиждень. Оновіть пару методом `auth/api-refresh`, а після закінчення тижня увійдіть знову через `auth/api-login`. Для API використовуйте окремого користувача, а не основний обліковий запис: інакше сесія користувача в системі завершується автоматично. **Замовлення створилося без резерву.** Причина: бракує доступного залишку або `reserve` не передано. Рішення: перевірте залишок ([`inventory/api-readList`](/help/developers/api-reference/inventory/)) і передайте `reserve` у рядку; причини — у статті [Товар не резервується](https://bimpsoft.com/help/sales/reserve-troubleshooting/). **Товар за зовнішнім ID не знайдено.** `nomenclature/api-readByExternalId` повертає `null`. Спершу синхронізуйте каталог — див. Синхронізація каталогу — або знайдіть товар за артикулом через `nomenclature/api-readList` (фільтр `article`) і запишіть зіставлення. ## FAQ **Як не створити дубль замовлення, якщо запит повторили?** Перед створенням викличте invoiceForCustomerPayment/api-readByExternalId з вашим source і externalId. Якщо повернулося замовлення — створювати нове не потрібно. Після успішного api-create одразу викличте api-saveExternalId. **Як дізнатися в магазині, що статус замовлення в Bimp змінився?** Налаштуйте вебхук типу order_status на потрібні статуси. Як запасний варіант раз на кілька хвилин викликайте invoiceForCustomerPayment/api-readList з фільтром changeStatusTime. **Чи можна зарезервувати товар під час створення замовлення через API?** Так, у рядках products є поле reserve. Резерв створюється в межах доступного залишку, як і в інтерфейсі. **Як передати замовлення з Bimp в магазин або CRM?** Викликайте invoiceForCustomerPayment/api-readWithoutExternalId зі своїм source — метод поверне замовлення, для яких у вашій системі ще немає зіставлення.