Przejdź do głównej zawartości

Przesyłki i etykiety

Przesyłka (Shipment) w Sellrocket jest zawsze przypięta do zamówienia albo zwrotu. Możesz ją nadać u przewoźnika przez połączenie kurierskie — automatyzacja Sellrocket zarejestruje paczkę u kuriera i pobierze etykietę — albo dopisać numer nadania wygenerowany poza Sellrocket, np. w zewnętrznym WMS. W obu przypadkach przesyłka jest widoczna w zamówieniu, a jej status jest ujednolicony niezależnie od przewoźnika.

  • Połączenie kurierskie — konto u przewoźnika (InPost, DPD, DHL, GLS, UPS, Poczta Polska, Orlen Paczka, Wysyłam z Allegro i inne) skonfigurowane w panelu przez administratora instancji. W danych przesyłki i filtrach API wskazujesz je przez connectionId. Dane dostępowe do konta kuriera nie przechodzą przez Twoją integrację.
  • Szablony przesyłek — predefiniowane rozmiary paczek i ustawienia nadania dla danego połączenia, przygotowane w panelu. Ułatwiają powtarzalne nadawanie z panelu i z automatyzacji.
  • Przesyłka — numer nadania (trackingNumber), przewoźnik (courierCode), usługa (courierService), link śledzenia (trackingUrl) i status. Jedno zamówienie może mieć wiele przesyłek (wiele paczek).
  • Nadanie wykonuje automatyzacja — akcja „Utwórz przesyłkę” w automatyzacjach rejestruje paczkę u przewoźnika i zapisuje ją w zamówieniu. Zapis przesyłki przez API OMS jest asynchroniczny (dostajesz JobDTO), z wariantem synchronicznym dla pojedynczych zamówień — zobacz Operacje asynchroniczne.
  • Śledzenie jest automatyczne — Sellrocket sam odświeża statusy przesyłek. Nie musisz odpytywać API przewoźników; wystarczy, że czytasz zmiany z Sellrocket.

Status (status) ma te same wartości dla wszystkich przewoźników:

Status Znaczenie
unknown Brak informacji od przewoźnika
registered Przesyłka zarejestrowana u przewoźnika
courierAssigned Przekazana kurierowi
inTransit W drodze
outForDelivery Wydana do doręczenia
noticeLeft Pozostawiono awizo
waitingAtPoint Czeka w punkcie odbioru / automacie
delivered Doręczona
notDelivered Nieudana próba doręczenia
return Zwracana do nadawcy
lost Zagubiona
cancelled Anulowana
problem Problem zgłoszony przez przewoźnika
international W transporcie międzynarodowym

Rejestrację paczki u przewoźnika i pobranie etykiety wykonuje w Sellrocket automatyzacja z akcją „Utwórz przesyłkę”, skonfigurowana w panelu dla wybranego połączenia kurierskiego (z ustawieniami paczki, np. z szablonu). Z API uruchamiasz ją dla zamówienia, a wynik — przesyłkę z numerem nadania i etykietę — odczytujesz z OMS.

  1. Sprawdź, którymi kurierami możesz nadać zamówienie

    GET /api/v3/Orders/{orderId}/shipment-connections zwraca połączenia kurierskie, których można użyć dla tego zamówienia. Pełną listę połączeń instancji pobierzesz przez GET /api/v3/Connections.

  2. Uruchom nadanie

    Najprościej przez zdarzenie użytkownika (przycisk w panelu), które uruchamia automatyzację z akcją „Utwórz przesyłkę”:

    Okno terminala
    curl -X POST "https://$SR_INSTANCE-smerp-api.enterprise.sellrocket.pl/api/v3/UserEvents/12/Call" \
    -H "Authorization: Bearer $SR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{ "order": { "id": 204295 } }'

    Listę zdarzeń zwraca GET /api/v3/UserEvents/GetAll, a wywołanie opisuje POST /api/v3/UserEvents/{userEventId}/Call. Skrypt możesz też uruchomić bezpośrednio w serwisie Automatyzacje i śledzić jego wynik i logi — zobacz Automatyzacje. Nadanie może też wykonać automatyzacja z wyzwalaczem (np. zmiana statusu na „Do wysłania”) — wtedy wystarczy, że zmienisz status.

  3. Sprawdź przesyłkę

    Po zakończeniu automatyzacji przesyłka z numerem nadania jest w zamówieniu: GET /api/v3/Orders/{orderId}/Shipments. Jeśli przesyłki nie ma, sprawdź logi uruchomienia skryptu — znajdziesz tam m.in. błąd zwrócony przez przewoźnika.

  4. Pobierz etykietę

    Odpowiedzią jest plik (binarnie), a nie JSON.

Jeśli przenosisz integrację z BaseLinkera, nadanie z pełną kontrolą nad parametrami paczki (createPackage) jest dostępne także w Beel API — dla obsługiwanych przewoźników.

Jeśli etykiety generuje Twój WMS lub system magazynowy operatora logistycznego, dopisz gotowy numer nadania do zamówienia przez POST /api/v3/Orders/{orderId}/Shipments — bez nadawania u kuriera:

{
"courierCode": "dpd",
"trackingNumber": "0000123456789U",
"trackingUrl": "https://tracking.example.com/0000123456789U",
"shippingDate": "2026-10-05"
}

Endpoint zwraca JobDTO; gdy zadanie ma status Completed, przesyłka jest w zamówieniu. Wariant synchroniczny POST /api/v3/Orders/sync/{orderId}/Shipments przyjmuje ten sam format i od razu zwraca zapisaną przesyłkę (400 m.in. wtedy, gdy przesyłka o tym samym połączeniu, shipmentId i numerze już istnieje). Kilka paczek dla jednego zamówienia zapiszesz jednym wywołaniem POST /api/v3/Orders/{orderId}/Shipments/bulk (lub synchronicznie: POST /api/v3/Orders/sync/{orderId}/Shipments/bulk).

Kody przewoźników używane w instancji zwraca GET /api/v3/Shipments/DistinctCouriers. Istniejącą przesyłkę poprawisz przez PUT /api/v3/Orders/{orderId}/Shipments/{id}.

Przy wysyłce wielu zamówień pobierz etykiety jednym plikiem:

Okno terminala
curl -X POST "https://$SR_INSTANCE-smerp-api.enterprise.sellrocket.pl/api/v3/Shipments/CombinedLabels" \
-H "Authorization: Bearer $SR_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "connectionDefinitionId": "<id definicji>", "orderIds": [204295, 204296, 204297] }'

Drukarki dostępne dla użytkownika zwraca GET /api/v3/UserPrinters/available, a obsługę drukarek sieciowych opisuje Drukowanie API. Na magazynie drukarki przypisuje się do stanowisk pakowania (GET /api/v4/PackStations), dzięki czemu etykieta trafia na drukarkę stanowiska, przy którym pakowano zamówienie.

Do synchronizacji statusów (np. do Twojego CRM lub sklepu) używaj listy przesyłek z filtrem po dacie zmiany:

Okno terminala
GET /api/v3/Shipments?UpdatedAtFrom=2026-10-05T06:00:00Z&Limit=100&Offset=0

GET /api/v3/Shipments filtruje też po ShipmentStatus, OrderId, TrackingNumber, ConnectionIds, IsCod i dacie utworzenia. Przesyłki jednego zamówienia zwraca GET /api/v3/Orders/{orderId}/Shipments, a statusy śledzenia — GET /api/v3/Shipments/Statuses.

Zamówienie po zeskanowanym numerze paczki (np. na stanowisku zwrotów) znajdziesz przez GET /api/v3/Orders/byScannedShipmentNumber.

  • connectionId w żądaniu zapisu przesyłki jest tekstem ("42"), mimo że w innych miejscach API identyfikatory połączeń są liczbami.
  • /Shipments/bulk dotyczy jednego zamówienia — zapisuje kilka paczek dla tego samego orderId. Dla wielu zamówień wywołuj endpoint osobno dla każdego (wersję asynchroniczną) i zbieraj wyniki zadań.
  • Konfiguracja nadania jest w panelu. Konto kuriera, domyślne usługi, szablony paczek oraz automatyzację z akcją „Utwórz przesyłkę” (i przycisk, który ją uruchamia) ustawia administrator instancji. Zanim zaczniesz testy, upewnij się, że są skonfigurowane.
  • Nie każdy przewoźnik obsługuje wszystko. Definicja połączenia (GET /api/v3/ConnectionDefinitions) ma flagi m.in. protocolDisabled, requestPickupDisabled i trackingNumberTransfer — sprawdź je, zanim zaoferujesz w swojej aplikacji protokoły czy zamawianie odbioru.
  • Utworzenie przesyłki ≠ doręczenie. Zakończone zadanie czy uruchomienie automatyzacji mówi tylko, że przesyłkę utworzono. Dalszy los paczki śledź przez status.
  • Nie odpytuj przewoźników sam. Statusy są odświeżane po stronie Sellrocket — czytaj je przyrostowo (UpdatedAtFrom).
  • Przesyłki zwrotne mają własne endpointy pod /api/v1/Returns/{returnId}/Shipments — zobacz Zwroty.
BaseLinker Sellrocket
getCourierAccounts GET /api/v3/Orders/{orderId}/shipment-connections, GET /api/v3/Connections
createPackage Automatyzacja z akcją „Utwórz przesyłkę”, uruchomiona np. przez POST /api/v3/UserEvents/{userEventId}/Call
createPackageManual POST /api/v3/Orders/{orderId}/Shipments z courierCode i trackingNumber
getOrderPackages GET /api/v3/Orders/{orderId}/Shipments
getLabel GET /api/v3/Shipments/ShipmentLabel/{shipmentId}, POST /api/v3/Shipments/CombinedLabels
getProtocol POST /api/v3/Shipments/CombinedProtocols
getCourierPackagesStatusHistory GET /api/v3/Shipments/Statuses, GET /api/v3/Shipments

Metody kurierskie dostępne w trybie zgodności z BaseLinkerem: Beel API → Kurierzy i przesyłki. Jak zachować account_id kont kurierskich z BaseLinkera: Identyfikatory z BaseLinkera → Konta kurierskie.