Як передавати замовлення свого магазину в Elbuz через API

Що вміє синхронізація замовлень

• Приймає пакет до 100 замовлень — нові стають документами, вже завантажені оновлюються; у відповіді по кожному document_id і результат.
• Бере статуси за id довідників Elbuz — статус замовлення, оплати й доставки без таблиць зіставлення.
• Оберігає роботу менеджера — статус, який він поставив, лишається, поки магазин не пришле інший.
• Повідомляє про зміни — змінене замовлення отримує нову дату зміни, тригери й вебхук documents.updated.
• Продовжує історію тунелю — замовлення, завантажені тунелем, оновлюються через API.

Навіщо це бізнесу, розказано окремо: що це дає вашому магазину.

Де це і хто має доступ

Адреса

POST https://<ваш-домен>/api/v2/orders/sync; список — GET /api/v2/orders

Ключ

Кабінет → Налаштування системи → «Інші налаштування» → плитка «API та токени доступу»

Право доступу

власнику ключа — вікно замовлень і кнопка «Додати» в ньому

Де видно замовлення

вікно «Замовлення», джерело «API: назва ключа»

Підготувати

id статусів із довідників /document_statuses, /payment_statuses, /delivery_statuses

Загальні правила API — ключ Authorization: Bearer, ліміт 120 запитів за хвилину, формат помилок — у статті API v2. Тут — лише те, що стосується замовлень.

Готовий модуль для OpenCart 3

Для сайту на OpenCart 3.0.x писати модуль не потрібно: готовий модуль Elbuz API Sync шле orders/sync сам — після оформлення й після кожної зміни статусу, тримає таблицю «статус сайту → статус Elbuz», чергу повторів і журнал відправок. Скачати: elbuz_api_sync.ocmod.zip. Встановлення й налаштування — замовлення з OpenCart 3 готовим модулем.

Як підготувати ключ магазину

1. У вікні «API та токени доступу» натисніть «+» і в полі «Користувач» дайте ключу назву магазину, наприклад site_opencart. Ця назва стане джерелом замовлень: «API: site_opencart».
2. У полі «Від імені співробітника» оберіть співробітника, якому відкрите вікно замовлень і дозволена кнопка «Додати».
3. Зніміть «Тільки для читання».
4. Перемкніть «Зміни даних» на «Робити самому» — це може лише «Управління». Інакше кожен пакет замовлень чекатиме підтвердження в «Пульсі».
5. У «Запобіжник: змін на годину» поставте число з запасом: один запит orders/sync — одна зміна, хоч у ньому й 100 замовлень. Перевищення на годину повертає ключ у «Питати».

1

Користувач

2

Зміни даних: Робити самому

3

Запобіжник: змін на годину

4

Тільки для читання

1. Користувач — назва ключа site_opencart; вона ж стає джерелом замовлень («API: site_opencart»).
2. Зміни даних — режим «Робити самому»: зміни через ключ виконуються одразу, без підтвердження в «Пульсі».
3. Запобіжник — ліміт 1000 змін на годину; після перевищення ключ сам повертається в режим «Питати».
4. Тільки для читання — позначка знята, тож ключ може створювати й змінювати замовлення.

Один ключ — один магазин. За ключем Elbuz шукає вже завантажені замовлення: те саме order_id, надіслане іншим ключем, стане новим документом. Кілька сайтів — кілька ключів.

Як надіслати замовлення: запит і відповідь

curl -s -X POST "https://<ваш-домен>/api/v2/orders/sync" \
  -H "Authorization: Bearer elbz_xxxxxxxx_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-10481-1729700000" \
  -d '{
  "orders": [{
    "order_id": "10481",
    "firstname": "Олена", "lastname": "Коваль",
    "email": "olena.koval@example.com", "phone": "+380671234501",
    "shipping_city": "Львів", "shipping_method": "Нова пошта",
    "payment_method": "Оплата карткою на сайті",
    "currency_code": "UAH", "document_sum": "825",
    "date_added_ext": "2026-10-23 21:12:40",
    "status_id": 1, "payment_status_id": 1,
    "item_list": [
      {"product_id_ext": "5", "sku": "99180", "name": "Blackview R3 Black", "quantity": "1", "price": "825"}
    ]
  }]
}'

Відповідь (демо-акаунт, 23.10.2026):

{"data":{"source":"api_key_509","template_id":null,"orders":[
  {"order_id":"10481","document_id":1000403,"result":"created"},
  {"order_id":"10482","document_id":1000404,"result":"created"},
  {"order_id":"10483","document_id":1000405,"result":"created"}]},
 "approval_id":11765}

approval_id — номер запису в «Пульсі»: кожен пакет лишає там слід, у режимі «Робити самому» — уже виконаним.

Повний перелік полів — у GET /api/v2/openapi.json, шлях /orders/sync. Поля з внутрішніми id Elbuz (product_id, category_id, currency_id, payment_type_id, *_jumper) передавати не можна — відповідь 422.

Якщо каталог сайту вивантажено з Elbuz і сайт знає наш id товару, передайте його в product_id_2: за uuid товару Elbuz позиція знайдеться одразу, за числовим id — останнім кроком, якщо не допомогли артикул і назва.

Заголовок Idempotency-Key обов'язковий, як для кожного POST в API v2. Повтор з тим самим ключем і тим самим тілом протягом 24 годин отримає збережену відповідь, нічого не виконавши вдруге: якщо зв'язок обірвався вже після запису, замовлення не задвоїться.

Після 429 повтор з тим самим ключем виконається. Той самий ключ з іншим тілом — 422. Для кожної нової відправки замовлення беріть новий ключ.

У відповіді result: created — створено новий документ, updated — замовлення вже було, failed — документа після запису немає. Номер документа в Elbuz — GET /api/v2/orders/{document_id}.

Як передати статуси

Сайт передає id статусів Elbuz, а не свої назви: таблиці зіставлення в ключа немає, відповідність «статус сайту → статус Elbuz» тримає модуль сайту. Id беруться з довідників:

Id у кожному акаунті свої — зчитайте довідник один раз при налаштуванні модуля. Неіснуючий id — 422 з "orders[0].status_id": "not found", замовлення пакета не записуються. Поле можна не передавати: новому замовленню без delivery_status_id Elbuz поставить статус доставки за замовчуванням («Чекання від відправника»), а вже завантаженому залишить той, що є.

Що стається з уже завантаженим замовленням

Те саме order_id від того самого ключа — це оновлення. Правила ті самі, що в імпорті з маркетплейсів; повністю — хто кого перезаписує. Коротко:

• Оплата й доставка беруться з запиту, якщо поле передано.
• Статус замовлення змінюється, якщо магазин прислав інший status_id, ніж минулого разу, або менеджер цей статус ще не змінював. Той самий status_id повторно статус менеджера не затирає.
• Позиції не змінюються: item_list при оновленні можна не передавати.
• Проведений документ не змінюється взагалі.
• Змінене замовлення отримує нову дату зміни й подію зміни: тригери, процеси (Flows) і вебхук documents.updated. Кілька змінених в одному пакеті — одна подія documents.bulk_updated. Замовлення без змін — ні дати, ні подій.

Для оновлення достатньо order_id і полів, що змінилися:

{"orders":[
  {"order_id":"10481","status_id":11,"payment_status_id":5},
  {"order_id":"10482","status_id":11,"payment_status_id":5,"delivery_status_id":2}]}

Відповідь — "result":"updated" по обох. У списку замовлень вони стоять з джерелом «API: site_opencart», статусом і оплатою «Оплачено»:

1

35971: оплачено на сайті

2

Статус доставки «У дорозі»

3

35973: нове, не оплачене

1. 35971 — замовлення оплачене на сайті, в Elbuz воно має статус «Оплачено» і оплату «Оплачено».
2. У замовлення 35972 статус доставки «У дорозі» — він прийшов із сайту разом з оплатою «Оплачено».
3. 35973 — нове замовлення зі статусом «Новий» і оплатою «Чекання»: ще не оплачене.

Як перейти з тунелю без дублів

Замовлення, які вже завантажив тунель чи інший шаблон імпорту, записані з джерелом шаблону. Щоб API продовжив їх, а не завів нові, додайте в тіло template_id цього шаблону:

{"template_id": 2, "orders": [{"order_id": "11912",
  "order_status_code": "2", "order_status_name": "Zapłacono",
  "payment_service_status_name": "Zapłacono"}]}

• замовлення шукаються серед завантажених тунелем — order_id той самий, що в тунелі (номер замовлення на сайті). У всіх шаблонів тунелю спільне джерело, тож два сайти з однаковими номерами замовлень так розділити не вийде;
• order_status_code — той самий код, який писав тунель: для OpenCart це номер статусу замовлення на сайті. Інший код Elbuz сприйме як зміну статусу на сайті й перепише статус менеджера;
• працює зіставлення шаблону, тож статуси можна слати назвами сайту: order_status_code, order_status_name, payment_service_status_name;
• місце, з якого тунель продовжить завантаження («Завантаження замовлень починаючи з ID»), не зсувається: пакет може нести старі замовлення;
• шаблон має бути видимий власнику ключа; неіснуючий чи чужий — 422 "template_id": "not found".

Коли модуль запрацював, вимкніть галочку «Замовлення» в шаблоні тунелю, щоб замовлення не приходили двома шляхами.

Помилки

Помилка в будь-якому замовленні відхиляє весь пакет: у errors перелічено поля з номером замовлення в пакеті (до 50 рядків).

Сценарії

Модуль OpenCart шле замовлення при зміні статусу

Задача: кожне нове замовлення й кожна зміна статусу на сайті мають з'являтися в Elbuz без розкладу.

Що зробити: у модулі сайту зберігайте відповідність «статус OpenCart → status_id і payment_status_id Elbuz», зчитану з довідників. На створення замовлення й на зміну статусу шліть це замовлення в POST /orders/sync з новим Idempotency-Key; позиції — лише при створенні. Відповідь 429 чи обрив зв'язку — повторіть той самий запит із тим самим ключем.

Що вийде: замовлення з'являється в Elbuz одразу після відправки, оплата на сайті переводить його в «Оплачено», а статус, який поставив менеджер, лишається, поки сайт не змінить свій.

Переїзд з тунелю на API без дублів

Задача: замовлення роками приходили тунелем, тепер їх шле модуль сайту.

Що зробити: у модулі передавайте template_id шаблону тунелю і статуси назвами сайту, як у його «Статуси замовлення» й «Статуси оплати». Перевірте на одному старому замовленні: у відповіді має бути "result":"updated", а не created. Потім зніміть у шаблоні тунелю галочку «Замовлення».

Що вийде: старі замовлення оновлюються в тих самих документах, нові додаються туди ж, зіставлення статусів не доводиться переносити.

Що робити, коли замовлення не доходять

Часті запитання

Чи оновить повторна відправка склад замовлення?

Ні. Позиції записуються лише при створенні документа; змінений на сайті склад переносять у документ вручну.

Що буде, якщо замовлення видалили на сайті?

Нічого: orders/sync документи не видаляє. Переведіть замовлення в «Скасовано», надіславши відповідний status_id, або видаліть документ в Elbuz.

Кілька сайтів можуть слати замовлення одним ключем?

Краще ні: замовлення впізнаються за order_id у межах ключа, і однакові номери двох сайтів зіллються в один документ. Кожному сайту — свій ключ.

Чи спише замовлення з API залишок?

Ні. Документ створюється непроведеним; провести — у вікні або запитом POST /api/v2/documents/{id}/sign.

Якою мовою записуються назви статусів?

Мовою співробітника, від імені якого видано ключ, або мовою із заголовка Accept-Language. Так їх і показує список замовлень.

Суміжні теми

• Якщо сайт на OpenCart 3 — готовий модуль замість власного коду.
• Якщо ще не видали ключ — API v2: ключ, права, помилки.
• Якщо інша система має знати про зміну замовлення — вебхуки API v2.
• Якщо сайт на OpenCart і модуль ставити не хочете — замовлення через тунель.
• Якщо треба зрозуміти, чий статус лишиться, — хто кого перезаписує.