Download the PHP package g-tools/dpd-pl-api without Composer

dpd-pl-api-php

Klient API w języku PHP do komunikacji z następującymi web-serwisami firmy kurierskiej DPD:

• PackageService (rejestrowanie przesyłek, drukowanie etykiet i protokołów przekazania przesyłek kurierowi, zamawianie kuriera po odbiór przesyłki)
• AppService (obsługa zleceń odbioru przesyłek od osób trzecich)
• InfoService (tracking przesyłek)

Instalacja

Najprostszy sposób to instalacja za pomocą Composer-a (http://getcomposer.org).

Poprzez plik composer.json:

lub z linii poleceń:

Biblioteka korzysta z httplug jako abstrakcji klienta HTTP i nie zawiera żadnej domyślnej implementacji. Po stronie projektu, w którym jest umieszczona - leży obowiązek dostarczenia klienta HTTP zgodnego z PSR-18. Więcej informacji tutaj: http://docs.php-http.org/en/latest/httplug/users.html

Jeśli Twój projekt zawiera już jakiegoś klienta HTTP wspieranego przez httplug (http://docs.php-http.org/en/latest/clients.html) wystarczy razem z biblioteką doinstalować odpowiedni adapter.

Np. dla curl:

Jeśli natomiast nie używasz jeszcze żadnego kompatybilnego klienta HTTP w swoim kodzie, będzie konieczne zainstalowanie go razem z adapterem.

Np. guzzle:

Użycie

Sposób korzystania

Aby poprawnie wysłać przesyłkę korzystając z API DPD należy przejść następujące, omówione szerzej w dalszej części, kroki:

1. Zarejestrować przesyłkę/przesyłki (metoda generatePackageNumbers())

   Do tej metody wysyłamy fizyczne dane paczek składajacych się na przesyłkę, dane nadawcy i odbiorcy, dodatkowych zamówionych usług (np. pobranie, gwarancja dostarczenia, itd.). W odpowiedzi otrzymujemy numery listów przewozowych przypisanych do każdej paczki.

2. Wygenerować etykiety dla paczek (metoda generateLabels())

   Uzyskane w poprzednim kroku numery listów przewozowych przesłane do tej metody pozwolą w odpowiedzi uzyskać w odpowiedzi plik PDF z etykietami do umieszczenia na paczkach.

3. Wygenerować protokół przekazania paczek kurierowi (metoda generateProtocol())

   Tak jak wyżej, do metody przekazujemy numery listów przewozowych paczek, które mają być wysłane wspólnie. W odpowiedzi API zwraca plik PDF z przygotowanym protokołem przekazania przesyłek kurierowi.

4. Sprawdzić dostępność godzinową kuriera w pożądanym dniu nadania (metoda getCourierAvailability())

   Ta metoda po przesłaniu kodu pocztowego miejsca z którego nadane zostaną przesyłki, zwróci przedziały czasowe dostępności kuriera odbierającego przesyłki na najbliższe kilka dni.

5. Zamówić odbiór przesyłek przez kuriera (TODO)

   Do tej metody przekazujemy dzień i przedział godzinowy wybrany z tych które zwróciła metoda wyżej, a także miejsce odbioru. W odpowiedzi uzyskujemy potwiedzenie przyjęcia zlecenia odbioru. Kurier odbiera paczki oznaczone etykietami wygenerowanymi w kroku 2., pokwitowując protokół przekazania wygenerowany w kroku 3.

Poza powyższymi podstawowymi metodami obsługi paczek, poniższa biblioteka umożliwia także:

• Zlecanie odbioru od osoby trzeciej
• Pobieranie listy puntów doręczenia (TODO)
• Śledzenie przesyłek

0. Połączenie z API

Aby rozpocząć korzystanie z API wymagane są dane autentykacyjne składające się z trzech parametrów:

• nazwa użytkownika
• hasło
• numer FID

Dane te uzyskuje się od swojego opiekuna klienta po podpisaniu umowy i zadeklarowaniu chęci korzystania z API. Te same dane służą do autoryzacji we wszystkich trzech webserwisach wymienionych na początku tego dokumentu.

Korzystanie z API odbywa się poprzez obiekt klasy GTools\Dpd\Api budowany jak poniżej:

Domyślnie biblioteka łączy się do endpointów produkcyjnych, ale dla większości usług API DPD udostępnia także endpointy testowe pozwalające na bezpieczne przetestowanie integracji własnego kodu z webserwisem. Aby włączyć ich użycie należy wywołać na obiekcie Api metodę setSandboxMode:

Od tego momentu wszystkie żądania będą kierowane do endpointów testowych. Dla usług które nie udostępniają wersji testowej próba użycia w trybie sandbox zakończy się wyjątkiem SandboxNotAvailableException.

Testowe API wymaga osobnych danych logowania (dane te są przekazywane przez IT DPD razem z pakietem dokumentacji, po zgłoszeniu przez klienta chęci integracji API). Próba zalogowania się produkcyjnymi danymi dostępowymi na endpoint testowy spowoduje błąd autentykacji.

Aby wyłączyć tryb testowy można oczywiście użyć:

1. Rejestracja przesyłki

GeneratePackageNumbersRequest

Nadawanie paczkom numerów listów przewozowych odbywa się za pomocą metody generatePackageNumbers przyjmującej jako parametr obiekt typu GeneratePackageNumbersRequest:

Obiekt żądania jest budowany na podstawie danych przesyłki/przesyłek przekazywanych do metody fabrykujacej fromPackage lub fromPackages (dla żądania złożonego z wielu przesyłek jednocześnie):

Package

Encja używana do budowania powyższego requestu to obiekt typu Package, zawierający konfigurację przesyłki. Do jego budowy potrzeba co najmniej trzech danych - obiektu nadawcy Sender, obiektu odbiorcy Receiver i jednej lub więcej instancji klasy Parcel wyrażających fizyczne paczki, które składają sie na przesyłkę. Przykładkowy kod tworzący obiekt Package może wyglądać jak niżej:

Obiekty Sender i Receiver inicjalizuje się podobobnie, używając danych adresowych i obowiązkowo numeru telefonu. Poza tym do obiektu Sender przekazywany jest także numer FID używany do zalogownia (to API zakłada, że nadawcą paczki jest klient API):

Obiekt Parcel jest natomiast budowany następująco:

GeneratePackageNumbersResponse

Metoda generatePackageNumbers zwraca w odpowiedzi obiekt typu GeneratePackageNumbersResponse:

Wewnątrz mamy dostęp do listy zarejestrowanych przesyłek - tablicy obiektów typu RegisteredPackage:

A w każdej z przesyłek - listy zarejestrowanych paczek, z nadanymi numerami listów przewozowych:

2. Pobranie etykiet

"Wydruk" etykiet odbywa się przy użyciu metody generateLabels do której przekazujemy obiekt typu GenerateLabelsRequest:

GenerateLabelsRequest

Obiekt żądania można skonstruować na trzy sposoby:

• przy użyciu numerów listów przewozowych wygenerowanych w kroku 1.:

• przy użyciu numerów identyfikatorów paczek nadanych przez DPD w kroku 1.:

• lub, korzystając z pola reference paczek

(oczywiście tutaj trzeba pamiętać że pole reference to dowolny string który chcemy powiązać z paczką - np. numer zamówienia do wysyłki itp. - wobec czego jeśli nie przekażemy żadnej wartości tego pola w kroku 1. gdy rejestrujemy paczki - nie będzie można z niego skorzystać)

GenerateLabelsResponse

Po skonstruowaniu żadania i wysłaniu go do API metodą generateLabels uzyskamy w odpowiedzi obiekt typu GenerateLabelsResponse:

Wewnątrz mamy dostęp do pola fileContent zawierającego dane binarne pliku PDF z etykietą/etykietami. W przykładzie poniżej przedstawiono zapis etykiety do pliku etykieta.pdf:

3. Generowanie protokołu przekazania

Aby wygenerować protokół przekazania paczek kurierowi, używamy metody generateProtocol:

GenerateProtocolRequest

Tworzenie obiektu żądania jest bliźniaczo podobne do przypadku generowania etykiet. Tutaj też możemy stworzyć obiekt na trzy sposoby, korzystając z numerów listów przewozowych, identyfikatorów paczek lub referencji paczek:

GenerateProtocolResponse

Wysłanie tak skonstruowanego żądania do API da nam w odpowiedzi obiekt typu GenerateProtocolResponse, w którym do dyspozycji - znów - jest pole fileContent zawierające treść pliku PDF:

4. Sprawdzenie godzin dostępności kuriera

DOC TODO

5. Zamówienie kuriera po odbiór przesyłek

DOC TODO

Zlecanie odbioru od osoby trzeciej

Korzystając z API AppService można wystawić żądanie odebrania przesyłki od osoby trzeciej. W tym celu należy utworzyć obiekt (lub obiekty) typu Package opisujące konfigurację przesyłki jak przy zwykłym nadawaniu, pamiętając, że w polu $sender powinny znajdować się dane podmiotu faktycznie wydającego paczkę kurierowi, a nie zlecającego odbiór!

Poza tym, endpoint do zlecania odbioru akceptuje jedynie obiekty Package, w których zadeklarowano płatność przez stronę trzecią (rozumianą jako stronę zlecającą odbiór):

oraz podano numer FID tego płatnika (czyli w praktyce ten sam, którego używamy do łączenia się z API):

CollectionOrderRequest

Tak skonstruowany Package służy jako parametr do generowania obiektu CollectionOrderRequest:

dzięki któremu możemy wywołać metodę API zlecającą odbiór - collectionOrder():

CollectionOrderResponse

W odpowiedzi uzyskujemy obiekt typu CollectionOrdersResponse:

zawierający listę informację o przesyłkach, które udało się zlecić, w postaci tablicy obiektów typu CollectionOrderedPackage:

Natomiast w obiektach CollectionOrderedParcel pobranych z $package->getParcels() zapisany jest identyfikator paczki nadawany przez DPD oraz numer listu przewozowego dla tej paczki:

Składanie zlecenia odbioru przesyłki od osoby trzeciej w tym miejscu się kończy. Nie ma potrzeby drukowania etykiet i przekazywania ich nadającemu lub zamawiania kuriera - to zadzieje się automatycznie po stronie DPD.

Śledzenie przesyłek

Aby uzyskać informacje na temat konkretnej przesyłki możemy wykorzystać API InfoService poprzez metodę getParcelTracking:

GetParcelTrackingRequest

Obiekt żądania przekazywany do tej metody tworzymy przekazując numer listu przewozowego:

Opcjonalnie możemy wskazać czy chodzi nam o podgląd pełnej historii paczki czy tylko ostatnie zarejestrowane zdarzenie jej dotyczące:

przy czym domyślną wartością jest TrackingEventsCount::ALL() czyli pobieranie wszystkich zdarzeń w historii paczki.

GetParcelTrackingResponse

W odpowiedzi uzyskujemy obiekt typu GetParcelTrackingResponse

dający poprzez metodę getEvents() do tablicy obiektów typu ParcelEvent wyrażających pojedyncze zdarzenie w historii przesyłki:

Przykładowy efekt powyższego wywołania możemy zobaczyć poniżej