bitbag / dpd-pl-api-php
PHP DPD API client
Requires
- php-http/client-common: ^2.1
- php-http/discovery: ^1.7
- php-http/httplug: ^2.1
- php-http/message: ^1.8
- php-http/message-factory: ^1.0
- phpro/soap-client: ^1.0
- psr/http-client: ^1.0
- psr/http-client-implementation: ^1.0
- psr/http-message: ^1.0
- sabre/xml: ^2.1
Requires (Dev)
This package is auto-updated.
Last update: 2024-10-14 12:30:18 UTC
README
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
:
{ "require": { "t3ko/dpd-pl-api-php": "^0" } }
lub z linii poleceń:
composer require t3ko/dpd-pl-api-php
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
:
composer require php-http/curl-client:^1 t3ko/dpd-pl-api-php
Jeśli natomiast nie używasz jeszcze żadnego kompatybilnego klienta HTTP w swoim kodzie, będzie konieczne zainstalowanie go razem z adapterem.
Np. guzzle
:
composer require php-http/guzzle6-adapter:^1 guzzlehttp/guzzle:~6.0 t3ko/dpd-pl-api-php
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:
require_once __DIR__.'/vendor/autoload.php'; $login = 'testlogin'; $password = 'testpassword'; $fid = 12345; $api = new \T3ko\Dpd\Api($login, $password, $fid);
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
:
$api->setSandboxMode(true);
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ć:
$api->setSandboxMode(false);
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
:
use \T3ko\Dpd\Request\GeneratePackageNumbersRequest; /** @var GeneratePackageNumbersRequest $request */ $response = $api->generatePackageNumbers($request);
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):
$singlePackageRequest = GeneratePackageNumbersRequest::fromPackage($package); $multiplePackagesRequest = GeneratePackageNumbersRequest::fromPackages([$package1, $package2]);
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:
use T3ko\Dpd\Objects\Sender; use T3ko\Dpd\Objects\Receiver; use T3ko\Dpd\Objects\Parcel; use T3ko\Dpd\Objects\Package; $sender = new Sender(12345, 501100100, 'Jan Kowalski', 'Puławska 1', '02566', 'Warszawa', 'PL'); $receiver = new Receiver(605600600, 'Piotr Nowak', 'Kwiatowa 2', '60814', 'Poznań', 'PL'); $parcel = new Parcel(30, 30, 15, 1.5); $package = new Package($sender, $receiver, [$parcel]);
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):
$sender = new Sender( $fid, //numer FID $phone, //telefon $name, //imię i nazwisko $address, //adres $postalCode, //kod pocztowy $city, //miasto $countryCode, //kod kraju $company, //nazwa firmy (opcjonalnie) $email //email (opcjonalnie) ); $receiver = new Receiver( $phone, //telefon $name, //imię i nazwisko $address, //adres $postalCode, //kod pocztowy $city, //miasto $countryCode, //kod kraju $company, //nazwa firmy (opcjonalnie) $email //email (opcjonalnie) );
Obiekt Parcel
jest natomiast budowany następująco:
$parcel = new Parcel( $sizeX, //szerokość w cm $sizeY, //wysokość w cm $sizeZ, //głębokość w cm $weight, //masa w kg $reference, //unikalna referencja paczki $contents, //opis zawartości $customerNotes //notatka dla kuriera );
GeneratePackageNumbersResponse
Metoda generatePackageNumbers
zwraca w odpowiedzi obiekt typu GeneratePackageNumbersResponse
:
/** @var GeneratePackageNumbersResponse $response */ $response = $api->generatePackageNumbers($request);
Wewnątrz mamy dostęp do listy zarejestrowanych przesyłek - tablicy obiektów typu RegisteredPackage
:
/** @var RegisteredPackage[] $packages */ $packages = $response->getPackages()
A w każdej z przesyłek - listy zarejestrowanych paczek, z nadanymi numerami listów przewozowych:
list($package) = $packages; /** @var RegisteredParcel[] $parcels */ $parcels = $package->getParcels(); list($parcel) = $parcels; $parcel->getWaybill(); //numer listu przewozowego, np. 0000092494467Q
2. Pobranie etykiet
"Wydruk" etykiet odbywa się przy użyciu metody generateLabels
do której przekazujemy obiekt typu GenerateLabelsRequest
:
use \T3ko\Dpd\Request\GenerateLabelsRequest; /** @var GenerateLabelsRequest $request */ $response = $api->generateLabels($request);
GenerateLabelsRequest
Obiekt żądania można skonstruować na trzy sposoby:
- przy użyciu numerów listów przewozowych wygenerowanych w kroku 1.:
use \T3ko\Dpd\Request\GenerateLabelsRequest; $request = GenerateLabelsRequest::fromWaybills(['0000092494467Q']);
- przy użyciu numerów identyfikatorów paczek nadanych przez DPD w kroku 1.:
use \T3ko\Dpd\Request\GenerateLabelsRequest; $parcelId = $parcel->getId(); $request = GenerateLabelsRequest::fromParcelIds([$parcelId]);
- lub, korzystając z pola
reference
paczek
use \T3ko\Dpd\Request\GenerateLabelsRequest; $parcelRef = $parcel->getReference(); $request = GenerateLabelsRequest::fromReferences([$parcelRef]);
(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
:
/** @var GenerateLabelsResponse $response */ $response = $api->generateLabels($request);
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
:
$response = $api->generateLabels($request); $fp = fopen('etykieta.pdf', 'wb'); fwrite($fp, $response->getFileContent()); fclose($fp)
3. Generowanie protokołu przekazania
Aby wygenerować protokół przekazania paczek kurierowi, używamy metody generateProtocol
:
use \T3ko\Dpd\Request\GenerateProtocolRequest; /** @var GenerateProtocolRequest $request */ $response = $api->generateProtocol($request);
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:
use \T3ko\Dpd\Request\GenerateProtocolRequest; $request = GenerateProtocolRequest::fromWaybils([...]); $request = GenerateProtocolRequest::fromParcelIds([...]); $request = GenerateProtocolRequest::fromReferences([...]);
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:
/** @var GenerateLabelsResponse $response */ $response = $api->generateProtocol($request); $response->getFileContent()); //treść pliku PDF z protokołem przekazania
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):
$package->setPayerType(\T3ko\Dpd\Objects\Enum\PayerType::THIRD_PARTY());
oraz podano numer FID tego płatnika (czyli w praktyce ten sam, którego używamy do łączenia się z API):
$package->setThirdPartyFid(123);
CollectionOrderRequest
Tak skonstruowany Package
służy jako parametr do generowania obiektu CollectionOrderRequest
:
use \T3ko\Dpd\Request\CollectionOrderRequest; $singlePackageRequest = CollectionOrderRequest::fromPackage($package); $multiplePackagesRequest = CollectionOrderRequest::fromPackages([$package1, $package2]);
dzięki któremu możemy wywołać metodę API zlecającą odbiór - collectionOrder()
:
use \T3ko\Dpd\Request\CollectionOrderRequest; /** @var CollectionOrderRequest $request */ $response = $api->collectionOrder($request);
CollectionOrderResponse
W odpowiedzi uzyskujemy obiekt typu CollectionOrdersResponse
:
/** @var CollectionOrderResponse $response */ $response = $api->collectionOrder($request);
zawierający listę informację o przesyłkach, które udało się zlecić, w postaci tablicy obiektów typu CollectionOrderedPackage
:
/** @var CollectionOrderedPackage[] $packages */ $packages = $response->getCollectionOrderedPackages(); list($package) = $packages; $package->getPackageId(); //identyfikator przesyłki nadany przez DPD $package->getReference(); //ewentualna referencja klienta nadana wiążąca paczkę z obiektem Package przesłanym w requeście $package->getParcels(); //tablica obiektów typu CollectionOrderedParcel opisujących zlecona paczki tej przeysyłki $package->getStatusInfo(); //status tego requestu $package->getOrderNumber(); //numer zlecenia w systemie DPD
Natomiast w obiektach CollectionOrderedParcel
pobranych z $package->getParcels()
zapisany jest identyfikator paczki
nadawany przez DPD oraz numer listu przewozowego dla tej paczki:
list($parcel) = $package->getParcels(); $parcel->getParcelId(); //identyfikator paczki nadany przez DPD $parcel->getWaybill(); //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
:
use \T3ko\Dpd\Request\GetParcelTrackingRequest; /** @var GetParcelTrackingRequest $request */ $response = $api->getParcelTracking($request);
GetParcelTrackingRequest
Obiekt żądania przekazywany do tej metody tworzymy przekazując numer listu przewozowego:
use \T3ko\Dpd\Request\GetParcelTrackingRequest; $request = GetParcelTrackingRequest::fromWaybill(...);
Opcjonalnie możemy wskazać czy chodzi nam o podgląd pełnej historii paczki czy tylko ostatnie zarejestrowane zdarzenie jej dotyczące:
use \T3ko\Dpd\Request\GetParcelTrackingRequest; use T3ko\Dpd\Objects\Enum\TrackingEventsCount; $request = GetParcelTrackingRequest::fromWaybill('01234567890U', TrackingEventsCount::ALL()); $request = GetParcelTrackingRequest::fromWaybill('01234567890U', TrackingEventsCount::ONLY_LAST());
przy czym domyślną wartością jest TrackingEventsCount::ALL()
czyli pobieranie wszystkich zdarzeń w historii paczki.
GetParcelTrackingResponse
W odpowiedzi uzyskujemy obiekt typu GetParcelTrackingResponse
use \T3ko\Dpd\Response\GetParcelTrackingResponse; /** @var GetParcelTrackingResponse $response */ $response = $api->getParcelTracking($request);
dający poprzez metodę getEvents()
do tablicy obiektów typu ParcelEvent
wyrażających pojedyncze zdarzenie w historii przesyłki:
/** @var GetParcelTrackingResponse $response */ $response = $api->getParcelTracking($request); foreach ($response->getEvents() as $event) { printf("%s - %s - %s - %s - %s (%s %s) (%s) %s", $event->getEventTime()->format(DATE_ATOM), //data zdarzenia $event->getWaybill(), //numer listu przewozowego $event->getPackageReference(), //dowolne dane powiązane z przesyłką podane przez wysyłającego $event->getParcelReference(), //j.w. związane z pojedynczą paczką $event->getCountry(), //kod kraju operacji $event->getDepot(), //numer oddziału DPD $event->getDepotName(), //nazwa oddziału DPD $event->getBusinessCode(), //kod zdarzenia $event->getDescription() //opis słowny zdarzenia ); $eventAdditionalData = []; if (!empty($event->getAdditionalData())) { //dodatkowe dane zdarzenia foreach ($event->getAdditionalData() as $additionalData) { $eventAdditionalData[] = $additionalData->getValue(); } } if (!empty($eventAdditionalData)) { printf(' [%s]', implode(', ', $eventAdditionalData)); } echo "\n"; }
Przykładowy efekt powyższego wywołania możemy zobaczyć poniżej
2020-08-26T09:05:18+00:00 - 0123456789012A - - - PL (1349 Warszawa3) (190101) Przesyłka doręczona [Kowalski]
2020-08-26T07:02:15+00:00 - 0123456789012A - - - PL (1349 Warszawa3) (170304) Wysłano powiadomienie
2020-08-26T07:01:46+00:00 - 0123456789012A - - - PL (1305 Warszawa) (170309) Powiadomienie SMS [+48000000000, DELIVERED]
2020-08-26T06:38:21+00:00 - 0123456789012A - - - PL (1305 Warszawa) (170310) Powiadomienie mail [xxx@xxx.pl, SENT]
2020-08-26T06:19:49+00:00 - 0123456789012A - - - PL (1349 Warszawa3) (170102) Wydanie przesyłki do doręczenia [LOK9999WAC]
2020-08-26T00:44:23+00:00 - 0123456789012A - - - PL (1349 Warszawa3) (330137) Przyjęcie przesyłki w oddziale DPD [LOK0002WAC]
2020-08-25T16:16:14+00:00 - 0123456789012A - - - PL (1320 Piotrków Tryb.) (330135) Przyjęcie przesyłki w oddziale DPD [LOK0033PTR]
2020-08-25T14:46:29+00:00 - 0123456789012A - - - PL (1320 Piotrków Tryb.) (040101) Przesyłka odebrana przez Kuriera
2020-08-24T15:05:48+00:00 - 0123456789012A - - - ( ) (030103) Zarejestrowano dane przesyłki, przesyłka jeszcze nie nadana