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.

FAQ

After the download, you have to make one include require_once('vendor/autoload.php');. After that you have to import the classes with use statements.

Example:
If you use only one package a project is not needed. But if you use more then one package, without a project it is not possible to import the classes with use statements.

In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
Some PHP packages are not free to download and because of that hosted in private repositories. In this case some credentials are needed to access such packages. Please use the auth.json textarea to insert credentials, if a package is coming from a private repository. You can look here for more information.

  • Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
  • To use Composer is sometimes complicated. Especially for beginners.
  • Composer needs much resources. Sometimes they are not available on a simple webspace.
  • If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
  • Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Please rate this library. Is it a good library?

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:

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:

0. Połączenie z API

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

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:

(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

PHP Build Version
Package Version
Requires phpro/soap-client Version ^1.0
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
Composer command for our command line client (download client) This client runs in each environment. You don't need a specific PHP version etc. The first 20 API calls are free. Standard composer command

The package t3ko/dpd-pl-api-php contains the following files

Loading the files please wait ....