↑↓ wybierzEnter otwórzEsc zamknij

    1. Elbuz
    2. API v2: jak podłączyć własny program do danych Elbuz

    Jak przekazywać zamówienia swojego sklepu do Elbuz przez API

    6 min czytaniaZaktualizowano

    Strona, CMS lub system księgowy sam wysyła do Elbuz nowe zamówienia i ich zmiany zapytaniem POST /api/v2/orders/sync. Nowe stają się dokumentami „Zamówienie klienta”, już zaimportowane są aktualizowane.

    Kiedy to się przyda:

    • Twojego CMS nie ma wśród tuneli i platform — moduł strony wysyła zamówienia do API.
    • Płatność przychodzi na stronie — moduł ponownie wysyła zamówienie, a w Elbuz dostaje ono status „Opłacono” bez udziału menedżera.
    • Menedżer już prowadzi zamówienie — ponowna wysyłka nie nadpisuje ustawionego przez niego statusu.
    • Przechodzisz z tunelu na API — z template_id zamówienia trafiają do tych samych dokumentów, duplikatów nie będzie.

    Od czego zacząć: wydaj sklepowi osobny klucz w trybie „Wykonuj samodzielnie”.

    Co potrafi synchronizacja zamówień

    Po co to firmie, opisano osobno: co to daje Twojemu sklepowi.

    Gotowy moduł dla OpenCart 3

    Dla strony na OpenCart 3.0.x nie trzeba pisać modułu: gotowy moduł Elbuz API Sync sam wysyła orders/sync — po złożeniu zamówienia i po każdej zmianie statusu, prowadzi tabelę „status strony → status Elbuz”, kolejkę ponowień i dziennik wysyłek. Pobierz: elbuz_api_sync.ocmod.zip. Instalacja i konfiguracja — zamówienia z OpenCart 3 gotowym modułem.

    Jak przygotować klucz sklepu

    1. W oknie „API i tokeny dostępu” kliknij „+” i w polu „Użytkownik” nadaj kluczowi nazwę sklepu, np. site_opencart. Ta nazwa stanie się źródłem zamówień: „API: site_opencart”.
    2. W polu „W imieniu pracownika” wybierz pracownika, który ma otwarte okno zamówień i uprawnienie do przycisku „Dodaj”.
    3. Odznacz „Tylko do odczytu”.
    4. Przełącz „Zmiany danych” na „Wykonuj samodzielnie” — może to zrobić tylko „Zarząd”. Inaczej każda paczka zamówień będzie czekać na zatwierdzenie w „Pulsie”.
    5. W „Bezpiecznik: zmian na godzinę” wpisz liczbę z zapasem: jedno zapytanie orders/sync to jedna zmiana, choćby było w nim 100 zamówień. Przekroczenie w ciągu godziny przełącza klucz z powrotem na „Pytaj”.
    Karta klucza API: nazwa użytkownika, tryb zmian danych, bezpiecznik godzinowy i przełącznik „Tylko do odczytu”
    1Użytkownik = nazwa klucza
    2Zmiany danych: Wykonuj samodzielnie
    3Bezpiecznik: zmian na godzinę
    4Tylko do odczytu (wyłączone)
    1. Użytkownik — nazwa klucza, która staje się też źródłem zamówień przez niego przesłanych.
    2. Zmiany danych — ustawione na „Wykonuj samodzielnie”, więc klucz sam zapisuje zmiany.
    3. Bezpiecznik — ten klucz może wykonać najwyżej 1000 zmian na godzinę.
    4. Tylko do odczytu — wyłączone, więc klucz może tworzyć i aktualizować zamówienia.

    Jeden klucz — jeden sklep. Elbuz szuka już zaimportowanych zamówień w obrębie klucza: to samo order_id wysłane innym kluczem stanie się nowym dokumentem. Kilka stron — kilka kluczy.

    Jak wysłać zamówienia: zapytanie i odpowiedź

    Konto na app.elbuz.com wysyła na https://app.elbuz.com/api/v2/orders/sync?user_domain=<numer konta> — tak samo jak wszystkie zapytania API.

    curl -s -X POST "https://<twoja-domena>/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": "Anna", "lastname": "Kowalska",
        "email": "anna.kowalska@example.com", "phone": "+48601234501",
        "shipping_city": "Kraków", "shipping_method": "InPost Paczkomat",
        "payment_method": "Płatność kartą na stronie",
        "currency_code": "PLN", "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"}
        ]
      }]
    }'

    Odpowiedź (konto demo, 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 to numer wpisu w „Pulsie”: każda paczka zostawia tam ślad, w trybie „Wykonuj samodzielnie” — już jako wykonana.

    PoleCo zawiera
    ordersod 1 do 100 zamówień; innych pól na najwyższym poziomie, poza template_id, być nie może
    order_idobowiązkowy numer zamówienia na stronie, do 64 znaków, w paczce się nie powtarza. Po nim Elbuz rozpozna zamówienie następnym razem
    status_id, payment_status_id, delivery_status_idid statusów Elbuz — jak przekazać statusy
    firstname, lastname, email, phoneklient; po e-mailu i telefonie Elbuz szuka istniejącego kontrahenta
    shipping_*, payment_*adres dostawy, przewoźnik, sposób płatności — tekstem, jak na stronie
    currency_code, document_sum, date_added_extwaluta kodem (PLN), kwota i data zamówienia na stronie
    item_listpozycje: product_id_ext (id produktu na stronie), sku, name, quantity, price; produkt jest wyszukiwany tymi samymi krokami co w imporcie

    Pełna lista pól — w GET /api/v2/openapi.json, ścieżka /orders/sync. Pól z wewnętrznymi id Elbuz (product_id, category_id, currency_id, payment_type_id, *_jumper) przekazywać nie wolno — odpowiedź 422.

    Jeśli katalog strony wyeksportowano z Elbuz i strona zna nasze id produktu, przekaż je w product_id_2: po uuid produktu Elbuz pozycja znajdzie się od razu, po liczbowym id — w ostatnim kroku, jeśli nie pomogły kod i nazwa.

    Nagłówek Idempotency-Key jest obowiązkowy, jak dla każdego POST w API v2. Ponowienie z tym samym kluczem i tą samą treścią w ciągu 24 godzin dostanie zapisaną odpowiedź, niczego nie wykonując drugi raz: jeśli połączenie zerwało się już po zapisie, zamówienie się nie zdubluje.

    Po 429 ponowienie z tym samym kluczem zostanie wykonane. Ten sam klucz z inną treścią — 422. Do każdej nowej wysyłki zamówienia bierz nowy klucz.

    W odpowiedzi result: created — utworzono nowy dokument, updated — zamówienie już było, failed — po zapisie dokumentu nie ma. Numer dokumentu w Elbuz — GET /api/v2/orders/{document_id}.

    Jak przekazać statusy

    Strona przekazuje id statusów Elbuz, a nie własne nazwy: klucz nie ma tabeli dopasowania, odpowiedniość „status strony → status Elbuz” prowadzi moduł strony. Id pobiera się ze słowników:

    Pole zamówieniaSłownikPrzykład na koncie demo
    status_idGET /api/v2/document_statuses1 — „Nowy”, 11 — „Opłacono”, 10 — „Anulowano”
    payment_status_idGET /api/v2/payment_statuses1 — „Oczekiwanie”, 5 — „Opłacono”
    delivery_status_idGET /api/v2/delivery_statuses1 — „Oczekiwanie od nadawcy”, 2 — „W drodze”

    Id na każdym koncie są inne — odczytaj słownik raz przy konfiguracji modułu. Nieistniejące id — 422 z "orders[0].status_id": "not found", zamówienia z paczki nie są zapisywane. Pola można nie przekazywać: nowemu zamówieniu bez delivery_status_id Elbuz ustawi domyślny status dostawy („Oczekiwanie od nadawcy”), a już zaimportowanemu zostawi obecny.

    Co się dzieje z już zaimportowanym zamówieniem

    To samo order_id od tego samego klucza to aktualizacja. Zasady są takie same jak w imporcie z marketplace’ów; w całości — kto kogo nadpisuje. W skrócie:

    • Płatność i dostawa są brane z zapytania, jeśli pole przekazano.
    • Status zamówienia zmienia się, jeśli sklep przysłał inny status_id niż ostatnio albo menedżer jeszcze tego statusu nie zmieniał. Ten sam status_id wysłany ponownie nie nadpisuje statusu menedżera.
    • Pozycje się nie zmieniają: przy aktualizacji item_list można pominąć.
    • Zatwierdzony dokument nie zmienia się wcale.
    • Zmienione zamówienie dostaje nową datę zmiany i zdarzenie zmiany: wyzwalacze, procesy (Flows) i webhook documents.updated. Kilka zmienionych w jednej paczce — jedno zdarzenie documents.bulk_updated. Zamówienie bez zmian — ani daty, ani zdarzeń.

    Do aktualizacji wystarczy order_id i pola, które się zmieniły:

    {"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}]}

    Odpowiedź — "result":"updated" dla obu. Na liście zamówień mają źródło „API: site_opencart”, status i płatność „Opłacono”:

    Okno „Zamówienia” przefiltrowane do trzech zamówień, które przyszły przez klucz API: statusy płatności, dostawy i zamówienia
    1Zamówienie opłacone na stronie
    2Status dostawy „W drodze”
    3Nowe zamówienie, jeszcze nieopłacone
    1. Zamówienie opłacone na stronie trafia do Elbuz ze statusem płatności „Opłacono” i statusem zamówienia „Opłacono”.
    2. Status dostawy ze strony, „W drodze”, przechodzi do zamówienia.
    3. Nowe zamówienie, jeszcze nieopłacone, zostaje „Nowy” ze statusem płatności „Oczekiwanie”.

    Jak przejść z tunelu bez duplikatów

    Zamówienia, które już zaimportował tunel lub inny szablon importu, są zapisane ze źródłem szablonu. Aby API je kontynuowało, a nie zakładało nowych, dodaj do treści template_id tego szablonu:

    {"template_id": 2, "orders": [{"order_id": "11912",
      "order_status_code": "2", "order_status_name": "Zapłacono",
      "payment_service_status_name": "Zapłacono"}]}
    • zamówienia są wyszukiwane wśród zaimportowanych tunelem — order_id taki sam jak w tunelu (numer zamówienia na stronie). Wszystkie szablony tunelu mają wspólne źródło, więc dwóch stron z takimi samymi numerami zamówień w ten sposób się nie rozdzieli;
    • order_status_code — ten sam kod, który zapisywał tunel: dla OpenCart to numer statusu zamówienia na stronie. Inny kod Elbuz potraktuje jako zmianę statusu na stronie i nadpisze status menedżera;
    • działa dopasowanie z szablonu, więc statusy można wysyłać nazwami ze strony: order_status_code, order_status_name, payment_service_status_name;
    • miejsce, od którego tunel kontynuuje import („Import zamówień począwszy od ID”), się nie przesuwa: paczka może zawierać stare zamówienia;
    • szablon musi być widoczny dla właściciela klucza; nieistniejący lub cudzy — 422 "template_id": "not found".

    Gdy moduł zacznie działać, odznacz pole „Zamówienia” w szablonie tunelu, żeby zamówienia nie przychodziły dwiema drogami.

    Błędy

    Błąd w dowolnym zamówieniu odrzuca całą paczkę: w errors wymienione są pola z numerem zamówienia w paczce (do 50 wierszy).

    KodCo jest w detail / errorsPrzyczyna
    400orders is requiredpusta lub brakująca tablica orders
    400Idempotency-Key header is required for POSTbrak nagłówka Idempotency-Key
    403read-only keyklucz ma zaznaczone „Tylko do odczytu”
    403no right for syncwłaściciel klucza nie ma uprawnienia do przycisku „Dodaj” w oknie zamówień
    404POST /orders/sync has no idw ścieżce jest id: /orders/123/sync
    422"orders[0].nope": "unknown field"nieznane pole lub wewnętrzne pole Elbuz (order_status_id_jumper, w pozycji — product_id)
    422"orders[1].order_id": "duplicate in request"to samo order_id dwa razy w jednej paczce
    422"orders[0].status_id": "not found"nie ma takiego statusu w słowniku
    422at most 100 orders per requestponad 100 zamówień w paczce
    422unknown fields in action bodyna najwyższym poziomie jest coś poza orders i template_id
    429another order import is running, retry laterprzez 30 sekund trwała inna paczka tego konta
    202{"status":"pending","approval_id":…}klucz w trybie „Pytaj”: paczka czeka w „Pulsie”

    Scenariusze

    Moduł OpenCart wysyła zamówienia przy zmianie statusu

    Zadanie: każde nowe zamówienie i każda zmiana statusu na stronie mają pojawiać się w Elbuz bez harmonogramu.

    Co zrobić: w module strony przechowuj odpowiedniość „status OpenCart → status_id i payment_status_id Elbuz”, odczytaną ze słowników. Przy utworzeniu zamówienia i zmianie statusu wysyłaj to zamówienie do POST /orders/sync z nowym Idempotency-Key; pozycje — tylko przy utworzeniu. Odpowiedź 429 lub zerwane połączenie — powtórz to samo zapytanie z tym samym kluczem.

    Efekt: zamówienie pojawia się w Elbuz zaraz po wysłaniu, płatność na stronie zmienia jego status na „Opłacono”, a status ustawiony przez menedżera zostaje, dopóki strona nie zmieni swojego.

    Przeprowadzka z tunelu na API bez duplikatów

    Zadanie: zamówienia latami przychodziły tunelem, teraz wysyła je moduł strony.

    Co zrobić: w module przekazuj template_id szablonu tunelu i statusy nazwami ze strony, jak w jego „Statusy zamówienia” i „Statusy płatności”. Sprawdź na jednym starym zamówieniu: w odpowiedzi ma być "result":"updated", a nie created. Potem odznacz w szablonie tunelu pole „Zamówienia”.

    Efekt: stare zamówienia aktualizują się w tych samych dokumentach, nowe trafiają tam samo, dopasowania statusów nie trzeba przenosić.

    Co zrobić, gdy zamówienia nie docierają

    Najczęstsze problemy
    Co widziszDlaczego tak jestCo zrobić
    Odpowiedź 202, zamówień na liście nie maklucz jest w trybie „Pytaj” — albo sam do niego wrócił po przekroczeniu bezpiecznikazaakceptuj propozycję w „Pulsie”, przełącz klucz na „Wykonuj samodzielnie” i podnieś bezpiecznik (klucz)
    To samo zamówienie pojawiło się dwa razywysłane innym kluczem albo bez template_id, choć najpierw zaimportował je tunelwysyłaj jednym kluczem; dla zamówień z tunelu — z template_id (przejście)
    Strona przysłała status, a w Elbuz został starymenedżer zmienił status, a strona powtórzyła ten sam status_id, albo dokument jest zatwierdzonyto ochrona pracy menedżera; nowy status_id ze strony zmieni status (aktualizacja)
    422 „Idempotency-Key was used with another request”moduł wysłał zmienione zamówienie z kluczem poprzedniej wysyłkido każdej nowej wysyłki — nowy Idempotency-Key
    Pozycje trafiły do kategorii technicznejproduktu nie znaleziono w katalogu po sku i nazwieprzekazuj product_id_2 z id produktu Elbuz albo przenieś karty (wyszukiwanie produktu)

    Najczęstsze pytania

    Czy ponowna wysyłka zaktualizuje skład zamówienia?

    Nie. Pozycje zapisują się tylko przy tworzeniu dokumentu; zmieniony na stronie skład przenosi się do dokumentu ręcznie.

    Co się stanie, jeśli zamówienie usunięto na stronie?

    Nic: orders/sync nie usuwa dokumentów. Zmień status zamówienia na „Anulowano”, wysyłając odpowiedni status_id, albo usuń dokument w Elbuz.

    Czy kilka stron może wysyłać zamówienia jednym kluczem?

    Lepiej nie: zamówienia są rozpoznawane po order_id w obrębie klucza, więc takie same numery z dwóch stron złączą się w jeden dokument. Każdej stronie — osobny klucz.

    Czy zamówienie z API zdejmie stan magazynowy?

    Nie. Dokument powstaje niezatwierdzony; zatwierdzić go można w oknie lub zapytaniem POST /api/v2/documents/{id}/sign.

    W jakim języku zapisują się nazwy statusów?

    W języku pracownika, w imieniu którego wydano klucz, albo w języku z nagłówka Accept-Language. Tak też pokazuje je lista zamówień.

    Gdzie to jest i kto ma dostęp

    Adres
    POST https://<twoja-domena>/api/v2/orders/sync (app.elbuz.com — z ?user_domain=<numer konta>); lista — GET /api/v2/orders
    Klucz
    „Panel klienta” → „Ustawienia systemu” → „Inne ustawienia” → kafelek „API i tokeny dostępu”
    Uprawnienia
    właściciel klucza — okno zamówień i przycisk „Dodaj” w nim
    Gdzie widać zamówienia
    okno „Zamówienia”, źródło „API: nazwa klucza”
    Przygotuj
    id statusów ze słowników /document_statuses, /payment_statuses, /delivery_statuses

    Ogólne zasady API — klucz Authorization: Bearer, limit 120 zapytań na minutę, format błędów — w artykule API v2. Tutaj — tylko to, co dotyczy zamówień.

    Powiązane tematy

    Czy ten artykuł był pomocny?

    Brakuje funkcji? Napisz do nas.

    Dodamy ją za darmo, jeśli przyda się też innym.

    Jeśli potrzebujesz jej tylko ty — umówimy się osobno.

    Spis treści

    Zaproponuj usprawnienie

    Wypróbuj Elbuz za darmo