Download the PHP package t3ko/dpd-pl-api-php without Composer
On this page you can find all versions of the php package t3ko/dpd-pl-api-php. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Informations about the package dpd-pl-api-php
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:
-
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.
-
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.
-
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.
-
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.
-
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 T3ko\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
All versions of dpd-pl-api-php with dependencies
sabre/xml Version ^2.1
psr/http-client Version ^1.0
psr/http-client-implementation Version ^1.0
php-http/message-factory Version ^1.0
psr/http-message Version ^1.0
php-http/httplug Version ^2.1
php-http/discovery Version ^1.7
php-http/message Version ^1.8
php-http/client-common Version ^2.1