Przejdź do głównej zawartości

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. fulfillmentStatus zwrotu (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).

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ń.

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:

Okno terminala
GET /api/v5/Orders?Limit=100&Offset=0
GET /api/v5/Orders?Limit=100&Offset=100
GET /api/v5/Orders?Limit=100&Offset=200

W OMS wartość limit spoza zakresu 1–1000 kończy się błędem 400. Dokładny format stronicowania każdego endpointu znajdziesz w Referencji API.

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.

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: true

Zmiany 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."] }
}

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 429 odczekaj 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ń.

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