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_idzamó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ń
- Przyjmuje paczkę do 100 zamówień — nowe stają się dokumentami, już zaimportowane są aktualizowane; w odpowiedzi dla każdego
document_idi wynik. - Przyjmuje statusy po id słowników Elbuz — status zamówienia, płatności i dostawy bez tabel dopasowania.
- Chroni pracę menedżera — ustawiony przez niego status zostaje, dopóki sklep nie przyśle innego.
- Powiadamia o zmianach — zmienione zamówienie dostaje nową datę zmiany, wyzwalacze i webhook
documents.updated. - Kontynuuje historię tunelu — zamówienia zaimportowane tunelem są aktualizowane przez API.
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
- 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”. - W polu „W imieniu pracownika” wybierz pracownika, który ma otwarte okno zamówień i uprawnienie do przycisku „Dodaj”.
- Odznacz „Tylko do odczytu”.
- 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”.
- W „Bezpiecznik: zmian na godzinę” wpisz liczbę z zapasem: jedno zapytanie
orders/syncto jedna zmiana, choćby było w nim 100 zamówień. Przekroczenie w ciągu godziny przełącza klucz z powrotem na „Pytaj”.
1
Użytkownik = nazwa klucza2
Zmiany danych: Wykonuj samodzielnie3
Bezpiecznik: zmian na godzinę4
Tylko do odczytu (wyłączone)- Użytkownik — nazwa klucza, która staje się też źródłem zamówień przez niego przesłanych.
- Zmiany danych — ustawione na „Wykonuj samodzielnie”, więc klucz sam zapisuje zmiany.
- Bezpiecznik — ten klucz może wykonać najwyżej 1000 zmian na godzinę.
- 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.
| Pole | Co zawiera |
|---|---|
orders | od 1 do 100 zamówień; innych pól na najwyższym poziomie, poza template_id, być nie może |
order_id | obowią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_id | id statusów Elbuz — jak przekazać statusy |
firstname, lastname, email, phone | klient; 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_ext | waluta kodem (PLN), kwota i data zamówienia na stronie |
item_list | pozycje: 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ówienia | Słownik | Przykład na koncie demo |
|---|---|---|
status_id | GET /api/v2/document_statuses | 1 — „Nowy”, 11 — „Opłacono”, 10 — „Anulowano” |
payment_status_id | GET /api/v2/payment_statuses | 1 — „Oczekiwanie”, 5 — „Opłacono” |
delivery_status_id | GET /api/v2/delivery_statuses | 1 — „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_idniż ostatnio albo menedżer jeszcze tego statusu nie zmieniał. Ten samstatus_idwysłany ponownie nie nadpisuje statusu menedżera. - Pozycje się nie zmieniają: przy aktualizacji
item_listmoż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 zdarzeniedocuments.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”:
1
Zamówienie opłacone na stronie2
Status dostawy „W drodze”3
Nowe zamówienie, jeszcze nieopłacone- Zamówienie opłacone na stronie trafia do Elbuz ze statusem płatności „Opłacono” i statusem zamówienia „Opłacono”.
- Status dostawy ze strony, „W drodze”, przechodzi do zamówienia.
- 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_idtaki 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).
| Kod | Co jest w detail / errors | Przyczyna |
|---|---|---|
| 400 | orders is required | pusta lub brakująca tablica orders |
| 400 | Idempotency-Key header is required for POST | brak nagłówka Idempotency-Key |
| 403 | read-only key | klucz ma zaznaczone „Tylko do odczytu” |
| 403 | no right for sync | właściciel klucza nie ma uprawnienia do przycisku „Dodaj” w oknie zamówień |
| 404 | POST /orders/sync has no id | w ś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 |
| 422 | at most 100 orders per request | ponad 100 zamówień w paczce |
| 422 | unknown fields in action body | na najwyższym poziomie jest coś poza orders i template_id |
| 429 | another order import is running, retry later | przez 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ą
| Co widzisz | Dlaczego tak jest | Co zrobić |
|---|---|---|
| Odpowiedź 202, zamówień na liście nie ma | klucz jest w trybie „Pytaj” — albo sam do niego wrócił po przekroczeniu bezpiecznika | zaakceptuj propozycję w „Pulsie”, przełącz klucz na „Wykonuj samodzielnie” i podnieś bezpiecznik (klucz) |
| To samo zamówienie pojawiło się dwa razy | wysłane innym kluczem albo bez template_id, choć najpierw zaimportował je tunel | wysyłaj jednym kluczem; dla zamówień z tunelu — z template_id (przejście) |
| Strona przysłała status, a w Elbuz został stary | menedżer zmienił status, a strona powtórzyła ten sam status_id, albo dokument jest zatwierdzony | to 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łki | do każdej nowej wysyłki — nowy Idempotency-Key |
| Pozycje trafiły do kategorii technicznej | produktu nie znaleziono w katalogu po sku i nazwie | przekazuj 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
- Jeśli strona działa na OpenCart 3 — gotowy moduł zamiast własnego kodu.
- Jeśli nie masz jeszcze klucza — API v2: klucz, uprawnienia, błędy.
- Jeśli inny system ma wiedzieć o zmianie zamówienia — webhooki API v2.
- Jeśli strona działa na OpenCart, a nie chcesz instalować modułu — zamówienia przez tunel.
- Jeśli chcesz zrozumieć, czyj status zostanie — kto kogo nadpisuje.
- Jeśli wybierasz program do obsługi zamówień — co to daje Twojemu sklepowi.
