1. Wprowadzenie
Poczta Polska S.A udostępnia usługę sieciową (ang. web service) typu WSDL, która udostępnia śledzenie przesyłek pocztowych.
Usługa dostępna jest pod adresem:
- definicja: https://tt.poczta-polska.pl/Sledzenie/services/Sledzenie?wsdl
- endpoint: https://tt.poczta-polska.pl/Sledzenie/services/Sledzenie/SledzenieHttpSoap11Endpoint
- login:
sledzeniepp
- hasło:
PPSA
UWAGA! Danych udostępnianych przez usługę sieciową (web service) Poczty Polskiej S.A. nie wolno modyfikować w zakresie merytorycznym. Wszelkie zmiany w zakresie informacyjnym, zmiany zawartości komunikatów np. rodzaju i numerów przesyłek, czasu wystąpienia zdarzeń, zmiany ich kolejności są niedopuszczalne. Dopuszcza się jedynie modyfikacje w zakresie sposobu wizualizacji danych: dopasowanie kroju i wielkości czcionek, rozmieszczenia elementów, itp. Danych pozyskanych przy pomocy tego narzędzia nie wolno wykorzystywać do celów innych niż rzetelne informowanie Klientów o zdarzeniach dotyczących ich przesyłek dostarczanych poprzez Pocztę Polską S.A.
2. Metody webserwisu WSDL
Witaj
.sprawdzPrzesylki
, sprawdzPrzesylkiPl
Przesylka
– szczegółowe informacje o placówkach w atrybutach typu Jednostka
nie są generowane.Komunikat
– szczegółowe informacje o placówkach w atrybutach typu Jednostka
nie są generowane.Przesylka
– szczegółowe informacje o placówkach w atrybutach typu Jednostka
są generowane.Komunikat
– szczegółowe informacje o placówkach w atrybutach typu Jednostka
są generowane.Komunikat
, a szczegółowe informacje o placówkach w atrybutach typu Jednostka
nie są generowane. W tej metodzie struktury Przesylka
w liście przesyłek są wypełniane danymi jedynie dla przesyłek posiadających zdarzenia w podanym okresie. Jeśli przesyłka nie miała zdarzeń w podanym okresie zwracana jest pusta struktura Przesylka
(wypełnione jedynie pola status i numer) ze statusem równym 2,Komunikat
, a szczegółowe informacje o placówkach w atrybutach typu Jednostka
są generowane. W tej metodzie struktury Przesylka
w liście przesyłek są wypełniane danymi jedynie dla przesyłek posiadających zdarzenia w podanym okresie. Jeśli przesyłka nie miała zdarzeń w podanym okresie zwracana jest pusta struktura Przesylka
(wypełnione jedynie pola status i numer) ze statusem równym 2,witaj
zawierającej pełen Security Element został przedstawiony poniżej. <soapenv:Envelope xmlns:sled="http://sledzenie.pocztapolska.pl" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Header>
<wsse:Security soapenv:mustUnderstand="1" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
<wsse:UsernameToken wsu:Id="UsernameToken-2" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
<wsse:Username>sledzeniepp
</wsse:Username>
<wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">PPSA
</wsse:Password>
<wsu:Created>YYYY-MM-DDT00:00:00.000Z</wsu:Created>
</wsse:UsernameToken>
</wsse:Security>
</soapenv:Header>
<soapenv:Body>
<sled:witaj>
<sled:imie>Jan
</sled:imie>
</sled:witaj>
</soapenv:Body>
</soapenv:Envelope>
witaj
) nie powinny mieć w body żadnej zawartości. Pozostałe metody powinny mieć w body następującą strukturę:<soapenv:Body>
<sled:metoda
>
<sled:numer>123456
</sled:numer>
</sled:metoda
>
</soapenv:Body>
<soapenv:Body>
<sled:metoda
>
<sled:numer>123456
</sled:numer>
<sled:numer>123456789
</sled:numer>
</sled:metoda
>
</soapenv:Body>
UWAGA! Należy pamiętać, że do każdego request’a musi być dodany nagłówek:
"SOAPAction": "urn: <metoda>
",
"Content-Type": "text/xml; charset=utf-8"
3. Informacje udostępniane przez web service
- rodzaj przesyłki (wraz z kodem rodzaju przesyłki) np. paczka priorytetowa (PRP),
- data nadania przesyłki,
- format przesyłki (S, M, L)
- nazwa placówki, w której miało miejsce nadanie przesyłki np. UP Augustów 1,
- nazwa placówki, do której przesyłka zostanie skierowana,
- kraj nadania (wraz z kodem kraju nadania) np. Polska (PL),
- kraj przeznaczenia (wraz z kodem kraju przeznaczenia),
- masa przesyłki (w kg),
- informacja o zakończeniu obsługi przesyłki przez Pocztę Polską S.A.,
- informacje o przesyłce powiązanej (Przesyłka Proceduralna)
- kod procedury
- nazwa procedury
- typ opakowania (czy koperta firmowa [T – tak, N – nie])
- lista numerów przesyłek powiązanych
- lista zdarzeń związanych z przesyłką (statusów). Dla każdego ze zdarzeń udostępniana jest:
- data i czas zdarzenia,
- nazwa zdarzenia (wraz z kodem zdarzenia) np. doręczenie (P_D),
- przyczyna zdarzenia (wraz z kodem przyczyny) np. nie zastano adresata (P_A_AANZ),
- nazwa placówki, w której miało miejsce zdarzenie.
- informacja czy zdarzenie jest ostatnim zdarzeniem kończącym obsługę przesyłki przez Pocztę Polską S.A. Metody rozszerzone (*Pl) zwracają dodatkowe informacje o placówce nadania i przeznaczenia oraz placówkach, w których miały miejsce zdarzenia:
- współrzędne geograficzne placówki,
- dane adresowe placówki:
- nazwę miejscowości,
- PNA,
- nazwę ulicy,
- numer domu,
- numer lokalu,
- godziny pracy placówki:
- w dni robocze np. 08:00-20:00 lub Pon.: 08:00-20:00, wt.: 08:00-20:00, śr.: 09:00-16:00, czw.: 08:00-20:00, pt.: 08:00-20:00,
- w soboty,
- w niedziele i święta,
- uwagi dot. godzin pracy.
0
-1
-2
-3
-99
0
1
2
-1
-2
-99
UWAGA! Znaki [] za nazwą typu oznaczają listę (np. Przesylka[] ⬌ lista elementów typu Przesylka), zapis [<liczba>] przy typie string oznacza maksymalną długość tekstu (np. string[64] ⬌ tekst o maksymalnej długości 64 znaków)
4. Kody błędów
faultcode
400 Bad Request Nieprawidłowy numer nadania przesyłki
401 Unauthorized Login: <login>
sledzenie@poczta-polska.pl
dodając zwracany komunikat oraz request.403 Forbidden Login: <login> Konto zablokwane
405 Method Not Allowed: <login>
sledzenie@poczta-polska.pl
dodając swój login oraz zwracany komunikat.404 Resources for the endpoint URI not found.
503 Przerwa
5. FAQ
API Gateway encountered an error. Error Message: The endpoint reference (EPR) for the Operation not found is xx.xx.xxx.xx/ws/ppApiTrackingWsTt/1.0 and the WSA Action = null. If this EPR was previously reachable, please contact the server administrator.. Request Details: Service - ppApiTrackingWsTt, Operation - null, Invocation Time:11:09:39 AM, Date:Jul 8, 2024, Client IP - XX.XXX.XX.XXX, User - Default and Application:null
...WSA Action = null...
oznacza, że podczas wykonywania zapytania do WSDL/SOAP nie został dodany nagłówek Object Not Found (non-existing-endpointws/ppApiTrackingWsTt.SledzenieHttpSoap11Endpoint/1.0)
API Gateway encountered an error. Error Message: API Gateway outbound client encountered Internal Server Error. Request Details: Service - ppApiTrackingWsTt, Operation - sprawdzPrzesylkiPl, Invocation Time:hh:ii:ss PM, Date:M dd, RRRR, Client IP - xxx.xxx.xx.xxx, User - Default and Application:null
PasswordText
. Należy porównać swój request z zamieszczonym przykładowym requestem.API Gateway encountered an error. Error Message: API Gateway outbound client encountered WSDoAllReceiver: security processing failed. Request Details: Service - ppApiTrackingWsTt, Operation - sprawdzPrzesylkiPl, Invocation Time:hh:ii:ss PM, Date:M dd, rrrr, Client IP - xx.xx.xxx.xx, User - Default and Application:null
...security processing failed...
oznacza, że w definicji UsernameToken
nie został prawidłowo wskazany (lub w ogóle brakuje) schemat. Należy porównać swój request z zamieszczonym przykładowym requestem.Fatal error: Uncaught SoapFault exception: [VersionMismatch] Wrong Version
namespace
:
Failed to connect to tt.poczta-polska.pl port 80 after xx ms: Connection refused
sledzenie@poczta-polska.pl
dodając swój login oraz zwracany komunikat.API Gateway encountered an error. Error Message: API Gateway outbound client encountered decoding error; illegal input parameter value(s). Request Details: Service - ppApiTrackingWsTt, Operation - maksymalnaLiczbaPrzesylek, Invocation Time:hh:ii:ss PM, Date:M dd, rrrr, Client IP - xx.xxx.xx.xxx, User - Default and Application:null
...illegal input parameter value(s).
informauje, że metody informacyjne (poza witaj
) w swoim body nie mogą nic zawierać. Jeśli dla wspomnianej metody maksymalnaLiczbaPrzesylek
dodamy w body <sled:MaksymalnaLiczbaPrzesylek/>
, taki komunikat błędu otrzymamy. Należy wyczyścić sekcję body.Error while applying xPath. Error:Exception occurred evaluting XPath: /soapenv:Envelope/soapenv:Body/ns:sprawdzPrzesylkiResponse/ ns:return/ax21:przesylki/ax21:przesylka/ax21:danePrzesylki/ax21:zdarzenia/ax21:zdarzenie. Exception: XPath expression uses unbound namespace prefix ns
ns
. Niektóre biblioteki wymagają, aby zadeklarować używane przestrzenie nazw. Można jednak użyć konstrukcji XPath bez przestrzeni nazw. Można wtedy użyć przykładowego wyrażenia:
6. Pliki POSTMAN
Dla Państwa wygody przygotowaliśmy gotowy plik konfiguracyjny, który po zaimportowaniu do aplikacji POSTMAN umożliwi szybkie przetestowanie metod odpytujących o statusy przesyłek.
Aplikacja ta posiada zmienne {username}, {password}, które w przypadku posiadania dedykowanych danych logowania odpowiednio wpisać w sekcji Variables
.
Oto plik konfiguracyjny: Pobierz plik