↑↓ вибірEnter відкритиEsc закрити

    1. Elbuz
    2. Керівництво користувача Elbuz
    3. AI-агенти, MCP і API
    4. API v2

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

    8 хв читанняОновлено

    Сайт, CMS чи облікова система сама надсилає в Elbuz нові замовлення та їхні зміни запитом POST /api/v2/orders/sync. Нові стають документами «Замовлення покупця», вже завантажені оновлюються.

    Коли це знадобиться:

    • Вашої CMS немає серед тунелів і площадок — модуль сайту шле замовлення в API.
    • Оплата приходить на сайті — модуль повторно надсилає замовлення, і в Elbuz воно стає «Оплачено» без участі менеджера.
    • Менеджер уже веде замовлення — повторна відправка не затирає статус, який він поставив.
    • Переходите з тунелю на API — з template_id замовлення лягають у ті самі документи, дублів не буде.

    З чого почати: видайте магазину окремий ключ у режимі «Робити самому».

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

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

    Готовий модуль для 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 замовлень. Перевищення на годину повертає ключ у «Питати».
    Картка ключа доступу site_opencart у вікні «Доступ до API Elbuz»
    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 — номер запису в «Пульсі»: кожен пакет лишає там слід, у режимі «Робити самому» — уже виконаним.

    ПолеЩо в ньому
    ordersвід 1 до 100 замовлень; інших полів на верхньому рівні, крім template_id, бути не може
    order_idобов'язковий номер замовлення на сайті, до 64 символів, у пакеті не повторюється. За ним Elbuz упізнає замовлення наступного разу
    status_id, payment_status_id, delivery_status_idid статусів Elbuz — як передати статуси
    firstname, lastname, email, phoneпокупець; за поштою й телефоном Elbuz шукає наявного контрагента
    shipping_*, payment_*адреса доставки, служба, спосіб оплати — текстом, як на сайті
    currency_code, document_sum, date_added_extвалюта кодом (UAH), сума й дата замовлення на сайті
    item_listпозиції: product_id_ext (id товару на сайті), sku, name, quantity, price; товар шукається за тими самими кроками, що й в імпорті

    Повний перелік полів — у 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 беруться з довідників:

    Поле замовленняДовідникПриклад у демо-акаунті
    status_idGET /api/v2/document_statuses1 — «Новий», 11 — «Оплачено», 10 — «Скасовано»
    payment_status_idGET /api/v2/payment_statuses1 — «Чекання», 5 — «Оплачено»
    delivery_status_idGET /api/v2/delivery_statuses1 — «Чекання від відправника», 2 — «У дорозі»

    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», статусом і оплатою «Оплачено»:

    Список замовлень із джерелом «API: site_opencart»: три замовлення з сайту в Elbuz
    135971: оплачено на сайті
    2Статус доставки «У дорозі»
    335973: нове, не оплачене
    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 рядків).

    КодЩо в detail / errorsПричина
    400orders is requiredпорожній або відсутній масив orders
    400Idempotency-Key header is required for POSTнемає заголовка Idempotency-Key
    403read-only keyу ключа ввімкнено «Тільки для читання»
    403no right for syncвласнику ключа заборонена кнопка «Додати» у вікні замовлень
    404POST /orders/sync has no idу шляху стоїть id: /orders/123/sync
    422"orders[0].nope": "unknown field"невідоме поле або внутрішнє поле Elbuz (order_status_id_jumper, у позиції — product_id)
    422"orders[1].order_id": "duplicate in request"той самий order_id двічі в одному пакеті
    422"orders[0].status_id": "not found"немає такого статусу в довіднику
    422at most 100 orders per requestпонад 100 замовлень у пакеті
    422unknown fields in action bodyна верхньому рівні щось, крім orders і template_id
    429another order import is running, retry later30 секунд чекав інший пакет цього акаунта
    202{"status":"pending","approval_id":…}ключ у режимі «Питати»: пакет чекає в «Пульсі»

    Сценарії

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

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

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

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

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

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

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

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

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

    Розбір частих проблем
    Що ви бачитеЧому такЩо зробити
    Відповідь 202, замовлень у списку немаєключ у режимі «Питати» — або сам повернувся в нього, перевищивши запобіжникприйміть заявку в «Пульсі», перемкніть ключ на «Робити самому» й підніміть запобіжник (ключ)
    Те саме замовлення з'явилося двічінадіслане іншим ключем або без template_id, тоді як першим його завантажив тунельшліть одним ключем; для замовлень тунелю — з template_id (перехід)
    Сайт прислав статус, а в Elbuz лишився старийменеджер змінив статус, а сайт повторив той самий status_id, або документ проведеноце захист роботи менеджера; новий status_id з сайту статус змінить (оновлення)
    422 «Idempotency-Key was used with another request»модуль надіслав змінене замовлення з ключем попередньої відправкидля кожної нової відправки — новий Idempotency-Key
    Позиції лягли в службову категоріютовар не знайшовся в каталозі за sku і назвоюпередавайте product_id_2 з id товару Elbuz або перенесіть картки (пошук товару)

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

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

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

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

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

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

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

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

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

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

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

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

    Адреса
    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. Тут — лише те, що стосується замовлень.

    Суміжні теми

    Чи була стаття корисною?

    Не вистачає функції? Напишіть нам.

    Ми додамо її безкоштовно, якщо вона знадобиться й іншим.

    Якщо це потрібно тільки вам — домовимося окремо.

    Зміст статті

    Запропонувати доробку

    Спробувати безкоштовно