Konwencje API
- Żądania i odpowiedzi w JSON (
Content-Type: application/json), kodowanie UTF-8. - Nazwy pól w camelCase, wartości wyliczeniowe zwykle jako tekst (np.
"status": "Completed"). Wyjątki, np.fulfillmentStatuszwrotu (liczba), są opisane w referencji. - Daty w formacie ISO 8601, w UTC (np.
2026-10-05T08:30:00Z). - Kwoty jako liczby dziesiętne, waluta w osobnym polu (kod ISO 4217, np.
PLN).
Wersjonowanie
Dział zatytułowany „Wersjonowanie”Wersja jest częścią ścieżki: /api/v3/Statuses, /api/v5/Orders. W serwisie PIM wersja stoi po nazwie obszaru: /api/products/v3/products.
Wersje są nadawane per endpoint, nie dla całego API — nowa wersja powstaje tylko tam, gdzie zmienił się kontrakt. Dlatego jednocześnie używasz np. v3 dla statusów i v5 dla zamówień.
Paginacja
Dział zatytułowany „Paginacja”Listy zwracają jedną stronę wyników. Parametry zależą od serwisu:
| Serwis | Parametry | Odpowiedź |
|---|---|---|
| OMS | limit (1–1000), offset |
{ "list": [...], "pageNumber": 0, "total": 1234 } |
| Automatyzacje, Pola elastyczne | zwykle limit, offset |
zwykle jak w OMS; część list (np. skrypty, grupy) zwraca zwykłą tablicę, a historia pól elastycznych — { "results": [...], "totalRecords", "pageNumber", "pageSize" } |
| PIM | pageSize (maks. 1000), pageNumber (od 0) |
{ "data": [...], "totalRecords": 1234, "totalPages": 13 } |
Przykład — kolejne strony zamówień po 100:
GET /api/v5/Orders?Limit=100&Offset=0GET /api/v5/Orders?Limit=100&Offset=100GET /api/v5/Orders?Limit=100&Offset=200W OMS wartość limit spoza zakresu 1–1000 kończy się błędem 400. Dokładny format stronicowania każdego endpointu znajdziesz w Referencji API.
Operacje asynchroniczne
Dział zatytułowany „Operacje asynchroniczne”Wiele operacji zapisu w OMS (zmiana statusu, edycja zamówienia, dodanie płatności, przesyłki, tagów…) nie wykonuje się od razu. Zamiast wyniku dostajesz zadanie (JobDTO):
{ "id": 987654, "status": "New", "createdAt": "2026-10-05T08:30:00Z", "scopeValue": "204295", "result": null}Pole scopeValue wskazuje obiekt (np. ID zamówienia), którego dotyczy zadanie; scope to wewnętrzny identyfikator rodzaju obiektu — nie opieraj na nim logiki.
Status sprawdzisz przez GET /api/v3/jobs/get/{id}:
status |
Znaczenie |
|---|---|
New |
Zadanie przyjęte, czeka w kolejce |
InProgress |
W trakcie wykonywania |
Completed |
Zakończone — wynik w polu result |
Failed |
Błąd — result zawiera { "code": ..., "message": "..." } (kod 409 = konflikt współbieżności, ponów operację; 403 = brak uprawnień do obiektu, np. zamówienia w statusie niedostępnym dla użytkownika) |
Zadania dotyczące tego samego obiektu (np. jednego zamówienia) wykonują się po kolei, w kolejności zlecenia. Historia zadań jest przechowywana (domyślnie) przez 5 dni.
Zmiany bez wyzwalania automatyzacji
Dział zatytułowany „Zmiany bez wyzwalania automatyzacji”Każda zmiana zamówienia generuje zdarzenia, na które reagują automatyzacje (np. wysłanie e-maila po zmianie statusu). Przy migracji danych lub korektach możesz to wyłączyć nagłówkiem:
X-SR-ForceSilentChanges: trueZmiany są zapisywane, ale automatyzacje się nie uruchamiają. Nagłówek działa w serwisie OMS i liczy się sama jego obecność — wartość nie ma znaczenia (także false włącza tryb cichy), więc nie wysyłaj go „na stałe”. Używaj świadomie — np. przy imporcie historycznych zamówień.
| Kod | Znaczenie | Co zrobić |
|---|---|---|
400 |
Niepoprawne dane wejściowe | Popraw żądanie — szczegóły w treści odpowiedzi |
401 |
Brak/nieprawidłowy/wygasły token lub IP spoza listy | Zobacz Uwierzytelnianie |
403 |
Brak uprawnień użytkownika do operacji lub do zamówienia w danym statusie | Nadaj rolę lub dostęp do statusu użytkownikowi integracyjnemu |
404 |
Obiekt nie istnieje | — |
429 |
Przekroczony limit zapytań | Odczekaj i ponów (patrz niżej) |
500 |
Błąd po stronie serwera | Ponów z opóźnieniem; jeśli się powtarza — zgłoś |
Błędy walidacji i błędy aplikacji zwracane są zwykle w formacie Problem Details (RFC 7807):
{ "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "One or more validation errors occurred.", "status": 400, "errors": { "statusId": ["The statusId field is required."] }}Limity zapytań
Dział zatytułowany „Limity zapytań”API OMS ogranicza liczbę zapytań na użytkownika na minutę (licznik odnawia się co 60 sekund). Limit ustala administrator instancji dla każdego użytkownika — możesz też wystawić token z niższym limitem (zobacz Uwierzytelnianie).
Po przekroczeniu limitu dostaniesz 429 (bez nagłówka Retry-After). Zalecenia:
- przy
429odczekaj do pełnej minuty i ponów, - zamiast wielu pojedynczych wywołań używaj endpointów masowych (
batch,bulk,byIds), - pobieraj przyrostowo (po dacie zmiany) zamiast cyklicznie całych list — zobacz Pobieranie zamówień.
Opcje włączane na żądanie
Dział zatytułowany „Opcje włączane na żądanie”Część funkcji działa dopiero po włączeniu opcji dla instancji. Opcji nie włączysz przez API ani w panelu — włącza je wsparcie Sellrocket na zgłoszenie klienta (właściciela instancji). Jako integrator przekaż klientowi nazwę opcji z dokumentacji.
W dokumentacji takie miejsca są oznaczone ramką „Opcja włączana na żądanie” z nazwą opcji.
W zgłoszeniu klient podaje nazwę instancji, nazwę opcji i — jeśli opcja zmienia działanie istniejących integracji — termin włączenia uzgodniony z integratorami.
| Opcja | Co zmienia | Opis |
|---|---|---|
| ID pól elastycznych w Beel API | extra_field_id w Beel API to ID definicji pola elastycznego — pozwala zachować ID pól z BaseLinkera |
Beel API → Pola dodatkowe |

