Tworzenie listu przewozowego i pobieranie etykiety

Do czego służy ta instrukcja

Ten artykuł pokazuje, jak z poziomu REST API xSale utworzyć list przewozowy oraz pobrać etykietę dla przesyłki. To rozwiązanie jest szczególnie przydatne, gdy integrujesz xSale z własnym systemem (np. ERP lub aplikacją magazynową) i chcesz automatycznie obsługiwać wysyłki.

Poniżej znajdziesz opis kroków i wymagań, a następnie część techniczną z endpointami i przykładami (pozostawioną bez zmian).

W tym artykule znajdziesz

• kiedy warto tworzyć list przewozowy przez API
• wymagania i dane potrzebne do utworzenia przesyłki
• szybki przepis krok po kroku
• typowe problemy i sposób weryfikacji

Kiedy stosować

To podejście sprawdza się, gdy chcesz zautomatyzować proces nadawania przesyłek: na podstawie zamówienia w xSale tworzysz przesyłkę u kuriera, a następnie pobierasz etykietę do wydruku lub zapisania w systemie zewnętrznym. Dzięki temu operator nie musi wykonywać tych czynności ręcznie w panelu.

Wymagania

• dostęp do REST API xSale (autoryzacja) dla właściwej organizacji
• wartość organizationName
• identyfikator zamówienia w xSale oraz dane potrzebne do utworzenia przesyłki (zgodnie z przykładem w części technicznej)
• skonfigurowana integracja z kurierem / metoda wysyłki, z której korzysta zamówienie

Szybki przepis (krok po kroku)

1. Ustal, dla którego zamówienia chcesz utworzyć przesyłkę (ID zamówienia w xSale).
2. Przygotuj dane przesyłki wymagane przez endpoint (np. dane odbiorcy, parametry przesyłki, wybrany kurier).
3. Wyślij zapytanie API tworzące przesyłkę / list przewozowy (przykład poniżej).
4. Po poprawnym utworzeniu przesyłki pobierz etykietę, aby ją wydrukować lub zapisać w systemie.
5. Zweryfikuj w xSale, czy do zamówienia został przypisany numer listu przewozowego.

Typowe problemy i jak je sprawdzić

• Błąd autoryzacji — sprawdź dane logowania/token oraz uprawnienia do REST API.
• Brak wymaganych danych przesyłki — porównaj pola w wysyłanym body z przykładem w części technicznej.
• Etykieta nie pobiera się — upewnij się, że przesyłka została utworzona poprawnie i masz identyfikator/numer listu przewozowego.
• Nieprawidłowy kurier lub usługa — zweryfikuj konfigurację integracji kurierskiej i ustawienia dostawy dla zamówienia.

Szczegóły techniczne

Obsługa dokumentów przewozowych dla kurierów to jeden z podstawowych mechanizmów w procesie realizacji zamówienia. Zarówno utworzenie przesyłki z listem przewozowym, jak i wydruk etykiety kurierskiej, są możliwe do wykonania z poziomu aplikacji xSale (instrukcja krok po kroku dostępna jest tutaj).

REST API xSale daje możliwość obsłużenia tych procesów z poziomu aplikacji back-endowej.

Tworzenie listu przewozowego

Aby utworzyć list przewozowy, wykorzystaj poniższy endpoint (z tego samego zasobu korzysta proces tworzenia listu inicjowany przez system Futuriti WMS):

POST /{organizationName}/notify/wm-realized

Do utworzenia listu konieczne będzie podanie wartości FGUID zamówienia oraz szczegółów dotyczących przesyłki i jej obsługi.
Aby uzyskać FGUID, odpytaj o szczegóły zamówienia zasób:

GET /{organizationName}/orders/{id} 

Endpoint umożliwia i wymaga podania parametrów związanych z wymiarami i wagą przesyłki. Należy także przesłać id dokumentu (w polu DocumentId). Dla przesyłek realizowanych za pośrednictwem InPost można ustawić gabaryt.

Pobranie i wydruk etykiety

Wydruk etykiety można zrealizować z poziomu interfejsu xSale. Do pobrania etykiety można również wykorzystać poniższą metodę w REST API. W odpowiedzi na żądanie zwrócony zostanie plik etykiety w formacie pdf.

GET /{organizationName}/shipments/{id}/label

Numer przesyłki potrzebny do pobrania etykiety należy uzyskać z danych zamówienia:

GET /{organizationName}/orders/{id}