Instrukcja użytkownika

systemu śledzenia z wykorzystaniem metody webserwisu WSDL/SOAP

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:

Usługa systemu śledzenia umożliwia kreowanie jednorazowych zapytań zarówno o jeden numer przesyłki, jak i o wiele przesyłek.
Do jednorazowego odpytania systemu można użyć konta domyślnego, którego parametry są następujące:
  • login: sledzeniepp
  • hasło: PPSA
Klientów, którzy planują formułować jednorazowo zapytania o większe ilości przesyłek lub pozyskiwać rozszerzone informacje o przesyłkach, zachęcamy do założenia dedykowanego konta. W tym celu prosimy o kontakt z Pocztą Polską S.A za pośrednictwem dedykowanego formularza.

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

I Metody informacyjne
witaj
metoda do testów poprawności przekazywania parametrów. Wymaga podania parametru imie (string), a zwraca tekst Witaj .
wersja
zwraca numer wersji web service’u (string)
maksymalnaLiczbaPrzesylek
zwraca maksymalną liczbę o przesyłek (int), o które można zapytać się metodami sprawdzPrzesylki, sprawdzPrzesylkiPl
II Sprawdzanie jednej lub wielu przesyłek
sprawdzPrzesylke
wymaga podania numeru przesyłki, zwraca informacje o danej przesyłce w strukturze Przesylka – szczegółowe informacje o placówkach w atrybutach typu Jednostka nie są generowane.
sprawdzPrzesylki
wymaga podania numeru przesyłki lub kilku numerów przesyłek, zwraca informacje o podanych przesyłkach w strukturze Komunikat – szczegółowe informacje o placówkach w atrybutach typu Jednostka nie są generowane.
sprawdzPrzesylkePl
wymaga podania numeru przesyłki, zwraca informacje o danej przesyłce w strukturze Przesylka – szczegółowe informacje o placówkach w atrybutach typu Jednostka są generowane.
sprawdzPrzesylkiPl
wymaga podania numeru przesyłki lub kilku numerów przesyłek, zwraca informacje o podanych przesyłkach w strukturze Komunikat – szczegółowe informacje o placówkach w atrybutach typu Jednostka są generowane.
III Sprawdzanie przesyłek posiadających zdarzenia w podanym okresie …OdDo
sprawdzPrzesylkiOdDo
wymaga podania jednego lub kilku numerów przesyłek oraz przedziału czasu w postaci dnia początkowego i końcowego (yyyy-mm-dd). Zwraca strukturę 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,
sprawdzPrzesylkiOdDoPl
wymaga podania jednego lub kilku numerów przesyłek oraz przedziału czasu w postaci dnia początkowego i końcowego (yyyy-mm-dd). Zwraca strukturę 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,
IV Autoryzacja
Web service wykorzystuje mechanizm prostej autentykacji opartej o tzw. Username Token Element. Standard ten został zdefiniowany w Web Services Security (WSS): http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0.pdf. W nagłówku koperty SOAP powinien zostać umieszczony tzw. Security Element zawierający nazwę użytkownika i hasło. Przykładowe wywołanie metody witaj zawierającej pełen Security Element został przedstawiony poniżej.
V REQUEST
Do prawidłowego działania webserwisu SOAP/WSDL niezbędne jest przesłanie poprawnego request’a. Poniżej przykładowy z wykorzystaniem ogólnych danych autoryzacyjnych:
<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>
Metody diagnostyczne (poza witaj) nie powinny mieć w body żadnej zawartości. Pozostałe metody powinny mieć w body następującą strukturę:
dla metod odpytujących o pojedynczą przesyłkę:
<soapenv:Body> <sled:metoda> <sled:numer>123456</sled:numer> </sled:metoda> </soapenv:Body>
dla metod odpytujących o więcej przesyłek:
<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"
Bez odpowiedniego nagłówka będą zwracane błędy. Lista błędów pod instrukcją.

3. Informacje udostępniane przez web service

Struktura danych:
struktura danych WSDL
Web service udostępnia następujące informacje:
  • 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.
Model danych:
Komunikat
status (int):
0
Znaleziono dane wyszukiwanej przesyłki
-1
zapytanie o zbyt dużą liczbę przesyłek
-2
brak uprawnień do sprawdzania wielu przesyłek
-3
daty podane w wywołaniu metod sprawdzPrzesylkiOdDo lub sprawdzPrzesylkiOdDoPl są błędne – sprawdzanie dat obejmuje format daty (yyyy-mm-dd), poprawność numeru miesiąca i dnia w miesiącu. Nie jest zaś sprawdzane czy data końcowa jest większa lub równa dacie początkowej. W takim przypadku sprawdzane przesyłki, o ile istnieją, będą miały status (w strukturze Przesylka!) równy 2 – opis poniżej.
-99
Inny błąd
przesylki (ListaPrzesylek): wypełniona dla statusu równego 0
ListaPrzesylek
przesylka (Przesylka[])
Przesyłka
status(int):
0
znaleziono dane wyszukiwanej przesyłki
1
są inne przesyłki o takim numerze
2
przesyłka o podanym numerze jest w systemie, ale nie ma zdarzeń w podanym okresie (dotyczy metod OdDo)
-1
w systemie nie ma przesyłki o takim numerze. Uwaga! Web service uwzględnia jedynie przesyłki posiadające choć jedno zdarzenie w przeciągu ostatnich 30 dni.
-2
podany numer przesyłki jest błędny
-99
Inny błąd
numer (string[20]): numer przesyłki (zgodny z podanym w parametrze metody)
dane (DanePrzesylki)
DanePrzesylki
numer (string[20]) – ponownie numer przesyłki
format (string[3]) – format przesyłki
kodRodzPrzes (string[5]) – kod rodzaju przesyłki
rodzPrzes (string[64]) – rodzaj przesyłki
dataNadania (string[10]) – data nadania przesyłki w postaci yyyy-mm-dd
kodKrajuNadania (string[5]) – kod kraju nadania przesyłki (np. PL)
krajNadania (string[64]) – nazwa kraju nadania (np. POLSKA)
kodKrajuPrzezn (string[5]) – kod kraju przeznaczenia przesyłki (np. PL)
krajPrzezn (string[64]) – nazwa kraju przeznaczenia (np. POLSKA)
urzadNadania (Jednostka) – informacje o placówce nadania
urzadPrzezn (Jednostka) – informacje o placówce przeznaczenia
masa (float) – waga przesyłki w kg
zakonczonoObsluge (boolean) – czy miało miejsce tzw. zdarzenie kończące (np. doręczenie, odebranie przesyłki w urzędzie, zwrot przesyłki itp.)
proceduraSerwis (Procedura)
zdarzenia (ListaZdarzen)
Procedura
kod (string[3]) – kod procedury serwis
kopertaFirmowa (string[1]) – typ opakowania (czy koperta firmowa) [T – tak ,N – nie]
nazwa (string[64]) – nazwa procedury serwis
przesylkiPowiazane (ListaPrzesylekPowiazanych[])
ListaPrzesylekPowiazanych
przesylkaPowiazana (PrzesylkaPowiazana[])
PrzesylkaPowiazana
nrPrzesylkiPowiazanej (string[20]) – numer przesyłki
ListaZdarzen
zdarzenie (Zdarzenie[])
Zdarzenie
czas (string[16]) – czas zdarzenia w postaci yyyy-mm-dd hh-nn
jednostka (Jednostka) – jednostka (placówka PP), w której miało miejsce zdarzenie
kod (string[10]) – kod zdarzenia
konczace (boolean) – czy to zdarzenie jest kończące obsługę przesyłki
nazwa (string[64]) – nazwa zdarzenia (np. Wysłanie z ładunkiem)
przyczyna (Przyczyna) – przyczyna zdarzenia – atrybut jest wypełniany jedynie dla pewnych użytkowników web service’u
Jednostka
nazwa (string[64])
daneSzczegolowe (SzczDaneJednostki) – puste dla metod SprawdzPrzesylke i SprawdzPrzesylki, wypełnione dla SprawdzPrzesylkePl i SprawdzPrzesylkiPl
Przyczyna
nazwa (string[64]) – przyczyna zdarzenia
kod (string[10]) – kod przyczyny zdarzenia
SzczDaneJednostki
szerGeogr (float z N(8,6)) – szerokość geograficzna placówki
dlGeogr (float z N(9,6)) – długość geograficzna placówki
miejscowość (string[64]) – miejscowość, w której znajduje się placówka
pna (string[6]) – PNA (kod pocztowy) placówki
ulica (string[169]) – ulica
nrDomu (string[11]) – numer domu
nrLokalu (string[7]) – numer lokalu
godzinyPracy (GodzinyPracy) – godziny pracy placówki
GodzinyPracy
dniRobocze (GodzinyZUwagami) – informacja o godzinach pracy placówki w dni robocze
soboty (GodzinyZUwagami) – informacja o godzinach pracy placówki w soboty
niedzISw (GodzinyZUwagami) – informacja o godzinach pracy placówki w niedziele i święta
GodzinyZUwagami
godziny (string[4000]) – godziny pracy np. 08:00-24:00
uwagi (string[4000]) – uwagi do godzin pracy

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

Opisy kodów błędów zwracanych przez serwis WSDL tzw. faultcode
400 Bad Request Nieprawidłowy numer nadania przesyłki
Odpowiedzi 400 przypisane są do działań/weryfikacji związanych z nieprawidłowymi danymi podawanymi przez użytkowników.
401 Unauthorized Login: <login>
Odpowiedzi 401 związane są z brakiem autoryzacji użytkownika co związane jest z błędnie podaną nazwą użytkownika lub hasłem. W przypadku, gdy dane logowania są poprawne, ale nadal pojawia się ten komunikat, należy skontaktowac się z supportem PP S.A. pod adresem: sledzenie@poczta-polska.pl dodając zwracany komunikat oraz request.
403 Forbidden Login: <login> Konto zablokwane
Odpowiedzi 403 związane są z blokadami użytkownika lub brakiem uprawnień do wybranych metod. Jeżeli błąd nie jest związany ze zbyt dużą liczbą zapytań kierowanych do usług systemu śledzenia należy skontaktować się z Pocztą Polską celem ustalenia przyczyn blokady.
405 Method Not Allowed: <login>
Komunikat ten oznacza, że dla Twojego loginu nastapiła zmiana hasła lub wymagane jest zmianie hasła. W tym celu należy skontaktowac się z supportem PP S.A. pod adresem: sledzenie@poczta-polska.pl dodając swój login oraz zwracany komunikat.
404 Resources for the endpoint URI not found.
Komunikat ten występuje w integracjach „ręcznych” i oznacza, że wywoływana metoda webserwisu została usunięta lub zmieniła swoja lokalizcję w strukturze, należy zweryfikować instrukcje WSDL i poprawić swój kod.
503 Przerwa
System niedostępny lub przerwa technologiczna. W body odpowiedzi znajduje się komunikat zwrotny ze szczegółową informacją.

5. FAQ

Wykaz możliwych pojawiających się błędów przy dokonywaniu integracji lub podczas bieżacego użytkowania integracji
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
Komunikat ...WSA Action = null... oznacza, że podczas wykonywania zapytania do WSDL/SOAP nie został dodany nagłówek
„SOAPAction”: „urn: <metoda>”
.
Object Not Found (non-existing-endpointws/ppApiTrackingWsTt.SledzenieHttpSoap11Endpoint/1.0)
Komunikat ten wskazuje, że uzywany jest błędny endpoint – należy zweryfikować instrukcje WSDL i poprawić swój kod.
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
Należy zweryfikować czy Twój request posiada wszystkie niezbędne parametry oraz schema. Bardzo często nie jest poprawnie zdefiniowany pełen Security Element lub niewskazany w haśle typ 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
Komunikat ...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
Najprawdopodobnie Twój kod korzysta z SOAP 1.2. Zaimplementowana wersja SOAP w systemie śledzenia to SOAP 1.1. Obie różnią się chociażby w definicji namespace:
SOAP 1.1 namespace : http://schemas.xmlsoap.org/soap/envelope SOAP 1.2 namespace : http://www.w3.org/2003/05/soap-envelope
Failed to connect to tt.poczta-polska.pl port 80 after xx ms: Connection refused
Komunikat ten oznacza, że nasz firewall wykrył podejrzany ruch z Twojego adresu IP i został on zablokowany. W tym celu należy należy skontaktowac się z supportem PP S.A. pod adresem: 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
Komunikat ...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
Błąd występujący po stronie aplikacji klienckiej. W zalezności od języka, w jakim napisany jest kod własnej aplikacji, niektóre mechanizmy wymagają prefixa w postaci 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:
/*[local-name()=’Envelope’]/*[local-name()=’Body’]/*[local-name()=’sprawdzPrzesylkiResponse’]/*[local-name()=’return’]/*[local-name()=’przesylki’]/*[local-name()=’przesylka’]/*[local-name()=’danePrzesylki’]/*[local-name()=’zdarzenia’]/*[local-name()=’zdarzenie’]

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

Wniosek o utworzenie konta WSDL/SOAP