Jak nawiązać połączenie z API firmy kurierskiej DHL

 In Technicznie

W tym artykule chciałbym przedstawić przykładowy projekt służący do komunikacji z API DHL. Nawiążę połączenie oraz przebrnę przez proces zamawiania kuriera.

 

Jednym z naszych klientów, któremu oferujemy wsparcie i rozwój systemu jest BrokerSystem, aplikacja ta skierowana jest do brokerów kurierskich obsługujących dużą liczbę przesyłek.

Jednym z głównych naszych zadań i wyzwań są integracje z API (Application Programming Interface) firm kurierskich (DHL, DPD, Geis, FedEx itp.).  W tym wpisie chciałbym zaprezentować sposób obsługi procesu zamawiania kuriera DHL. Zadanie to wymaga wykonania kolejnych kroków:

  • dodanie przesyłki do systemu DHL
  • wygenerowanie listu przewozowego lub etykiet termalnych
  • zamówienie kuriera po odbiór przesyłki

Dokumentacja WebAPI DHL dostępna jest pod adresem https://dhl24.com.pl/webapi2/doc/index.html. Aby nawiązać połączenie wymagane też są dane dostępowe, które można uzyskać kontaktując się z obsługą klienta tejże firmy.

Usługa została stworzona w technologii SOAP, w której do opisu struktury wykorzystywany jest plik WSDL, a zapytania wysyłane są w formie języka znaczników XML. Posiada ona wiele metod ale ja opiszę tylko te, które umożliwią wygenerowanie listu przewozowego, etykiet oraz zamówienie kuriera. Integrację utworzę w języku PHP.

Nawiązanie połączenia

W celu nawiązania połączenia należy skorzystać z wbudowanego klienta SOAP. DHL umożliwia połączenie w trybie produkcyjnym oraz testowym. Aby zmienić tryb połączenia należy wskazać odpowiedni adres pliku WSDL:

Dodatkowo tworzę nową klasę, która będzie zawierała zdefiniowane metody służące do przesyłania danych do serwera DHL.
Aby zobrazować poprawność połączenia oraz format zwracanych danych wykorzystam metodę getVersion(), która nie przyjmuje parametrów i do wykonania której nie są wymagane dane dostępowe.
W odpowiedzi otrzymujemy:

W ten sposób uzyskaliśmy połączenie z API firmy kurierskiej DHL i pobraliśmy informacje o jego aktualnej wersji.

Utworzenie pliku konfiguracyjnego

Dla metod, które zostaną opisane od tej części wpisu wymagane będą dane uwierzytelniające.

Klasa Config zawiera definicję pięciu stałych, które odpowiadają kolejno za nazwę użytkownika, hasło, numer klienta SAP, numer przesyłki, datę nadanie. Dwa ostatnie parametry ułatwią pracę z plikami zaprezentowanymi w tym wpisie.

Dodanie przesyłki do systemu – definicje struktur

W pierwszej kolejności postanowiłem utworzyć definicje struktur opisanych w dokumentacji. Są to najmniejsze części, które będą kolejno dołączane do zapytania. Dodatkowo sensowne jest dodanie pliku konfiguracyjnego aby później w łatwy sposób można było zmienić dane dostępowe.

W tej klasie tworzymy tablicę zawierającą dane uwierzytelniające oraz metodę, która pozwoli nam dodać je w wymaganych miejscach.

W kolejnej metodzie tworzymy dane nadawcy oraz odbiorcy przesyłki.

Klasa Piece zajmuje się definicją każdej z paczek w przesyłce. W tym przykładzie tylko dla jednej paczki.

PaymentData definiuje sposób płatności za zamówienie. Warto zwrócić uwagę na to, że to tutaj pojawia się zainicjowana w pliku konfiguracyjnym stała AD_SAP.

W tej klasie ustaliliśmy usługi jakie będzie zawierała przesyłka. Jedynym wymaganym parametrem w tej metodzie jest product (o ile nie ustalimy na wartość true parametrów insurance lub collectOnDelivery). Służy on do wyboru usługi kurierskiej. W tym przykładzie jest to AH, czyli przesyłka krajowa.

Tworzenie struktury danych, które mają być przesłane do API

Teraz można zgrupować dane, które są zawarte w wyżej przedstawionych metodach. Do tego celu utworzę kolejną klasę, która stworzy większą część zapytania wykorzystując mniejsze części zawarte w klasach omówionych wcześniej.

Zapytanie do API w celu utworzenia przesyłki w systemie DHL

W tej sekcji dodam do systemu DHL informacje o przesyłce przy pomocy metody createShipments(). Umożliwia ona dodanie wielu przesyłek do systemu ale aby uprościć proces dodam tylko jedną paczkę i ustawię wszystkie parametry “na sztywno”. To zapytanie jest największym pod względem przyjmowania liczby parametrów w systemie DHL24.

Pozostało już tylko dodać dane uwierzytelniające i odpytać API. W tym celu dodać należy kolejną metodę w klasie DHL24.

Pojawiła się tu nowa metoda saveFiles(). Zajmuje się ona zapisywaniem do plików w formacie .xml wysyłanych i odbieranych danych.

Jeżeli wysłane dane nie zawierają błędów w odpowiedzi zostanie zwrócony obiekt XML. Zawiera on informacje o nadawcy i odbiorcy ale przede wszystkim jest tu zwracany numer przesyłki (shipmentId), który będzie wymagany do dalszych działań na przesyłce.

W tej sekcji został utworzony szkic przesyłki w systemie DHL. Nie wiąże się to jeszcze z nadaniem przesyłki, które następuje po zamówieniu kuriera.

Pobieranie listu przewozowego i etykiet

Kolejnym etapem będzie pobranie wymaganych do nadania przesyłki dokumentów. W tym celu będzie potrzebny nam numer przesyłki uzyskany w poprzedniej sekcji wpisu. Wystarczy go (w tym przypadku) dodać ręcznie w pliku konfiguracyjnym.

Do wykonania tego zapytania będzie potrzebna kolejna ze struktur.

Tutaj generowane są dane do zapytania pobierającego list przewozowy i etykiety. W metodzie getItemToPrint()  dla parametru $type o wartości protocol zwracamy dane tylko dla listu przewozowego, a dla wartości labels w pętli dodajemy kolejne typy etykiet do zapytania. Zwrócić należy uwagę na to, że nie ma możliwości jednoczesnego pobrania listu przewozowego i etykiet dla przesyłki. Jest to zmiana, która została wprowadzona w nowej wersji API DHL (v2).

Pozostaje już tylko dodać dane uwierzytelniające i odebrać list przewozowy lub etykiety z API. W tym celu należy dodać kolejną metodę w klasie DHL24.

Dane zostaną zwrócone jako struktura (lub tablica struktur) zawierająca numer przesyłki, typ etykiety, etykietę zakodowaną w metodą base64 oraz typ mime.

Zapis etykiety do pliku

Ostatnim krokiem będzie zapis etykiet do pliku co pozwoli na ich przechowanie i wydruk. Tutaj zajmuje się tym metoda saveLabels().

Znów należy rozróżnić typ etykiety, gdyż dla typu labels struktura będzie zawierała tablicę po której trzeba iterować. List przewozowy dla danych z wpisu będzie wyglądał następująco:

List przewozowy DHLZawiera on podstawowe informacje o przesyłce, które służą do jej identyfikacji i skierowania w odpowiednie miejsce.

Zamawianie kuriera

Ostatnim etapem będzie zamówienie kuriera po odbiór przesyłki. Do tego zapytania będą potrzebne już tylko dane uwierzytelniające, numer przesyłki, data nadania (taka sama jak na liście przewozowym) oraz preferowany przedział godzinowy przyjazdu kuriera.

W odpowiedzi zostaną zwrócone następujące dane zawierające numer zamówienia kuriera. Może on służyć do anulowania zamówienia kuriera.

Obsługa błędów

Łącząc się z API zawsze należy oczekiwać jako odpowiedzi błędu lub brak odpowiedzi gdy serwer nie jest osiągalny. Warto więc każde wywołanie połączenie opatrzyć w bloki try-catch, które umożliwią zabezpieczenie aplikacji przed niespodziewanym zachowaniem po otrzymaniu błędu. Błąd w połączeniu za pomocą SOAP wygląda tak jak poniżej.

Podsumowanie

WebAPI DHL posiada dobrą dokumentację dostępną publicznie. Komunikaty o błędach są czytelne i często zawierają sposób rozwiązania problemu, np. podając datę nadania, w której kurier nie może odebrać przesyłki otrzymamy komunikat o błędzie z proponowanymi terminami kiedy jest to możliwe. Zdarzają się jednak błędy, które dotyczą części biznesowej.

Kod wykorzystywany w tym wpisie jest dostępny pod adresem https://github.com/Ermlab/establishing-connection-with-dhl-api.

Nazwy struktur oraz metod wykorzystanych we wpisie pokrywają się z ich opisem w dokumentacji API DHL.

Zdjęcie użyte w nagłówku pochodzi z: https://www.flickr.com/photos/viewpix69/15331721455/

Recommended Posts

Leave a Comment