Instrukcja użytkownika REST API

systemu śledzenia USS 2.0. by Poczta Polska S.A.

1. Wprowadzenie

Poczta Polska S.A udostępnia usługę sieciową (ang. web service) typu REST API, która może być wykorzystana do tworzenia aplikacji umożliwiających śledzenie przesyłek pocztowych.

usługa dostępna jest pod adresem:

Usługa systemu śledzenia umożliwia kreowanie jednorazowych zarówno o jeden numer przesyłki jak i o wiele przesyłek, zgodnie z uprawnieniami.
Dla jednorazowego odpytania systemu można użyć konta domyśłnego, którego parametry są następujące:
  • login: sledzeniepp
  • hasło: PPSA (dla SOAP/WSDL jako passwordText)
  • hash hasła: 5EF1C8ABD8BA2186F781B715CAFFF3C8D08567D78F7C5B6138F4013652E3DBB9 (dla USS)
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.

2. Metody webserwisu

I Metody informacyjne
version
zwraca aktualny numer wersji serwisu, czas lokalny w Polsce oraz listę obsługiwanych języków
checkmailcount
zwraca maksymalną liczbę przesyłek (1 – 999), o które użytkownik może zapytać się metodą checkmailcollectionex
II Obsługa konta
login
Autentykacja użytkownika. Wymaga podania nazwy użytkownika oraz hasła w postaci sumy SHA256 z sumy hasła (dla użytkowników już posiadających indywidualne konta systemu śledzenia w WSDL jest to SHA1, dla klientów nowych usług systemu śledzenia SHA256).
Czyli:
  • dla już istniejących użytkowników, którym konto było zakładane przed 10.07.2024r. hasło wygląda: sha256(sha1('Twoje hasło').upperCase()).upperCase()
  • dla nowych kont zakładanych po 10.07.2024r. lub zmieniających hasło metodą changepassword hasło wygląda: sha256(sha256('Twoje hasło').upperCase()).upperCase()
W rezultacie metoda zwraca token autoryzacyjny, który powinien zostać umieszczony w nagłówku http w elemencie API_KEY każdej autoryzowanej metody.
changepassword
Zmiana hasła dla użytkownika usług systemu śledzenia. Wymaga podania nowego hasła oraz numeru PIN uzyskanego podczas rejestracji konta systemu śledzenia (dla indywidualnych przypadków PIN nie jest wymagany). Metoda zwraca sumę SHA256 z sumy SHA256 z podanego hasła, oraz tymczasowy token autoryzacyjny (po prawidłowej zmianie hasła wymagana jest ponowna autentykacja metodą login).
III Sprawdzanie danych przesyłek
checkmailex
Podstawowe sprawdzanie danych jednej przesyłki. Wymaga podania numeru nadania przesyłki. Zwraca informacje o przesyłce w strukturze mailInfo. Umożliwia pozyskanie rozszerzonej informacji o placówkach pocztowych, pod warunkiem posiadania specjalnego uprawnienia.
checkmailcollectionex
Sprawdzanie danych dla wielu przesyłek. Wymaga podania listy numer nadań przesyłek (min.1, maksimum wynika z przyznanych uprawnień). Umożliwia podanie opcjonalnie zakresu dat (from – to) mogących zawęzić interwał poszukiwania zdarzeń przesyłek. Zwraca informacje o przesyłkach w postaci listy obiektów mailItems. Umożliwia pozyskanie rozszerzonej informacji o placówkach pocztowych.
confirmationofreceipt
Pobranie elektronicznego potwierdzenia odbioru. Wymaga dodatkowych zapisów w umowie z PPSA, dodatkowych uprawnień oraz podania numeru nadania przesyłki. Zwraca strumień danych, zawierający elektroniczne potwierdzenia odbioru w formacie XML skompresowanego algorytmem GZIP.
checkmailcomponents
Zwraca uproszczone informacje o zdarzeniach przesyłek powiązanych z listem przewozowym. Wymaga wskazanie numeru listu przewozowego. Zwraca informacje w strukturze MailComponent.
checkmailsubscription
Zwraca dane przesyłek nadanych przez lub kierowanych do użytkownika posiadającego aktywną sybskrypcję usługi PUSH aplikacji mobilnej Poczty Polskiej SA. Wymaga dodatkowych zapisów w umowie z PPSA, posiadanie aktywnej subskrypcji swojej aplikacji oraz integracji z metodami subskrypcyjnymi.
Wszystkie metody umożliwiają fakultatywne wskazanie obsługiwanego języka, dla którego wykonana zostanie translacja nazw. Usługi systemu śledzenia domyślnie zwracają informację w języku polskim.
Użycie metod checkmailcollectionex, changepassword, checkmailcomponents oraz checkmailsubscription wymagają dedykowanych uprawnień i nie każdy użytkownik posiadający konto systemu śledzenia ma do nich dostęp domyślnie. Metody powyższe wymagają podania api_key.
IV Metody diagnostyczne
hello
Sprawdza odpowiedź usługi – służy diagnostyce odpowiedzi serwera aplikacji na pytanie kierowane do usługi bez dostępu do danych systemu. Wymaga wskazania nazwy/imienia. Rezultatem jest odpowiedź w formacie „Witaj <nazwa>”.
Słowo „Witaj” może różnić się dla odpowiedzi kierowanych w językach innych niż polski.
V Opis statusów rezultatu wyszukiwania danych przesyłki (mailStatus)
0
Znaleziono dane wyszukiwanej przesyłki
1
Znaleziono kilka przesyłek o wskazanym numerze nadania, w odpowiedzi znajdują się dane przesyłki, która została nadana jako ostatnia. Status ten może oznaczać równiez przypisanie nowej etykiety dla przesyłki, jeżeli poprzednia etykieta uległa uszkodzeniu/zniszczeniu.
-1
Przesyłka o wskazanym numerze nadania nie została znaleziona
-2
Nie wskazano numeru nadania przesyłki
VI Autoryzacja usługi
Usługi systemu śledzenia wykorzystują mechanizm autoryzacji typu API KEY Security, który wymaga aby token autoryzacyjny został umieszczony w nagłówku http w elemencie o nazwie api_key.

UWAGA! Dla anonimowego wykonania metod hello oraz version nie należy umieszczać w nagłówku elementu api_key (nawet pustego).

3. Praca z endpointami

Wygenerowanie poprawnego zakodowanego hasła
Po otrzymaniu maila z hasłem dla Twojego konta należy go odpowiednio zakodować:
  1. metodą kryptograficzną SHA256()
  2. wynik zamienić na wielkie litery UPPERCASE
  3. ponownie metodą kryptograficzną SHA256() zakodować wynik z drugiej iteracji
  4. ponownie wynik zamienić na wielkie litery UPPERCASE

Przykład:

//moża wykorzystać bibliotekę sha256.js <script src="sha256.min.js"></script> const password = sha256( sha256('p@ssw0rd').toUpperCase() ).toUpperCase();
$password = strtoupper( hash("sha256", strtoupper( hash("sha256", "p@ssword") )) );

Wypróbuj hashowanie swojego hasła:

Jak już posiadasz zakodowane hasło, należy zalogować się do USS (używając metody login) w celu pozyskania tymczasowego tokenu, który posłuzy do zmiany hasła – otrzymanego mailem przy założeniu konta lub resetu hasła – na własne. Po zmianie hasła metodą changepassword uzyskasz już produkcyjny token, który możesz od razu wykorzystać do pobierania danych o przesyłkach.

//wykorzystujemy metodę $.ajax const config = { "prod" : { "url" : "https://uss.poczta-polska.pl", "version" : "2.0" "token" : "gNDMstgP3Yr81...0jA42DTc4MrHQ=.ODU1OT...4NjQ5MjE1RQ==.ad5bf522c...197a3944" }, "params" : { "login" : "TestTest", "language": "EN", "password" : "11C39BE1821EFA02383550CAB1D57E243066959B0CDAAF1F052373651AE67DCA" //przykładowe hasło "p@ssw0rd" zakodowane w sha265 } } jQuery.ajax({ url: config['prod'].url+"/uss/v"+config['prod'].version+"/tracking/login", data: config['params'], type: "POST", contentType: "application/json", success: callback, error: callback });
$curl = curl_init(); $login = "Twój login"; $password = strtoupper( hash("sha256", strtoupper( hash("sha256", "Twoje hasło") )) ); $apiKey = "gNDMstgP3Yr81...0jA42DTc4MrHQ=.ODU1OT...4NjQ5MjE1RQ==.ad5bf522c...197a3944"; curl_setopt_array($curl, array( CURLOPT_URL => 'https://uss.poczta-polska.pl/uss/v2.0/tracking/login', CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => '', CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_POSTFIELDS =>'{ "login": $login, "password": $password, "language": "PL" }', CURLOPT_HTTPHEADER => array( 'Content-Type: application/json', 'Accept: text/plain' ), )); $response = curl_exec($curl); curl_close($curl); echo $response;

Jeśli podano prawidłowo wszystkie dane – w tym prawidłowo zakodowane hasło – otrzymamy status 200 wraz z tymczasowym tokenem niezbędnym do zmiany hasła. Odpowiedź przyjmuje postać:

{ "newToken": "gNDMstgP3Yr81...0jA42DTc4MrHQ=.ODU1OT...4NjQ5MjE1RQ==.ad5bf522c...197a3944" }

Wygenerowanie nowego hasła w celu pozyskania właściwego tokenu

W tym celu należy za pomoca metody changepassword zmienić pierwsze hasło na własne.

Przykład:

//wykorzystujemy metodę $.ajax const config = { "prod" : { "url" : "https://uss.poczta-polska.pl", "version" : "2.0" "token" : "gNDMstgP3Yr81...0jA42DTc4MrHQ=.ODU1OT...4NjQ5MjE1RQ==.ad5bf522c...197a3944" } } jQuery.ajax({ url: config['prod'].url+"/uss/v"+config['prod'].version+"/tracking/changepassword", beforeSend: function(xhrObj){ xhrObj.setRequestHeader("api_key",config['prod'].token); }, data: { "pin" : "0000", //dotyczy kont z aktywnym kodem PIN "password" : "nowe haslo alfanumeryczne", "language": "PL" }, type: "POST", contentType: "application/json", success: callback, error: callback })
$curl = curl_init(); $password = "twoje wlasne haslo"; $pin = "1234"; //opcjonalne $apiKey = "gNDMstgP3Yr81...0jA42DTc4MrHQ=.ODU1OT...4NjQ5MjE1RQ==.ad5bf522c...197a3944"; curl_setopt_array($curl, array( CURLOPT_URL => 'https://uss.poczta-polska.pl/uss/v2.0/tracking/changepassword', CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => '', CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_POSTFIELDS =>'{ "pin" : $pin, "password" : $password, "language": "PL" }', CURLOPT_HTTPHEADER => array( 'Content-Type: application/json', 'Accept: application/json', 'api_key: '.$apikey, ), )); $response = curl_exec($curl); curl_close($curl); echo $response;

Jeśli podano prawidłowo wszystkie dane (PIN jest opcjonalny, jego włączenie wymaga kontaktu z PPSA) otrzymamy status 200 wraz z produkcyjnym tokenem oraz zakodowanym już własnym hasłem (nie musisz już dokonywać ponownego kodowania). Odpowiedź przyjmuje postać:

{ "password" : "9489750A8F6F2CF3F9AD1773AD527D0AE8646C6B53399B89B1B6984397F76E6F" "newToken": "HasuKq!w=P3Yr81...0jA42DTc4MrHQ=.ODU1OT...4NjQ5MjE1RQ==.ad5bf522c...197a3944" }

Tak wygenerowany newToken można już używać do pozostałych metod dostępnych w API

Istnieją dwie metody służące do pobierania danych o przesyłce checkmailex oraz checkmailcollectionex. Ta pierwsza zwraca nam jedynie pojedynczą przesyłkę, a druga dla wielu przesyłek jednocześniePierwsza z nich zwraca informacje o pojedynczej przesyłce, natomiast druga umożliwia pobranie danych dla wielu przesyłek jednocześnie. Metoda checkmailcollectionex może działać automatycznie, gdy w metodzie checkmailex zostanie zwrócona tablica z przesyłkami podrzędnymi (tzw. wielopaczki lub przesyłki paletowe, dla których tworzona jest tzw. etykieta nadrzęda), wtedy USS zwróci tablicę w zbiorze "components". Na podstawie tego możńa automatycznie pobierać dane uzywając metody checkmailcollectionex.

UWAGA! Obecnie dla metody checkmailex USS jeszcze zwraca dane events oraz states dla przesyłki zbiorczej. W kolejnej wersji USS nie będą zwracane te zbiory, gdy odpytywana będzie przesyłka zbiorcza. Należy uwzględnić to w procesie projektowania i wdrażania w swoich systemach informatycznych. Dane o przesyłkach w ramach wielopaczek lub palet zwracane będą w metodzie checkmailcollectionex.

Wywołanie metody checkmailex

Przykład:

//wykorzystujemy metodę $.ajax const config = { "prod" : { "url" : "https://uss.poczta-polska.pl", "version" : "2.0" "token" : "gNDMstgP3Yr81...0jA42DTc4MrHQ=.ODU1OT...4NjQ5MjE1RQ==.ad5bf522c...197a3944" } } jQuery.ajax({ url: config['prod'].url+"/uss/v"+config['prod'].version+"/tracking/ckeckmailex", beforeSend: function(xhrObj){ xhrObj.setRequestHeader("api_key",config['prod'].token); }, data: { "states": true, "number": parcel.val(), //wstawiamy tutaj zmienną z numerem przesyłki "language": "PL" }, type: "GET", contentType: "application/json", success: callback, error: callback })
$curl = curl_init(); $apiKey = "gNDMstgP3Yr81...0jA42DTc4MrHQ=.ODU1OT...4NjQ5MjE1RQ==.ad5bf522c...197a3944"; $number = 123456; //add your parcel number $params = array( 'language' => 'PL', 'number' => $number, 'addPostOfficeInfo' => true, //tylko wtedy, kiedy użytkownik USS ma atrybut dodatkowy 'states' => true ); curl_setopt_array($curl, array( CURLOPT_URL => 'https://uss.poczta-polska.pl/uss/v2.0/tracking/checkmailex?'.http_build_query($params), CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => '', CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => 'GET', CURLOPT_HTTPHEADER => array( 'Accept: application/json', 'api_key: '.$apiKey ), )); $response = curl_exec($curl); curl_close($curl); echo $response;

Odpowiedź z USS dla metody checkmailex

{ "mailInfo": { "number": "123456789", "typeOfMailCode": "PX2", "typeOfMailName": "Pocztex", "states": [ { "code": "PRZ", "name": "PRZYGOTOWANA", "time": "2024-06-06T11:59:01" } ], "finished": false, "events": [ { "code": "P_REJ_KN1", "name": "Otrzymano dane elektroniczne przesyłki", "time": "2024-06-06T11:59:01", "postOffice": { "name": "Elektroniczny Nadawca" }, "finished": false, "canceled": false, "state": { "code": "PRZ", "name": "PRZYGOTOWANA" } } ] }, "number": "123456789", "mailStatus": 1 }

W celu wywołania metody posługujemy się aktywnym tokenem.

Wywołanie metody checkmailcollectionex

Przykład:

//wykorzystujemy metodę $.ajax const config = { "prod" : { "url" : "https://uss.poczta-polska.pl", "version" : "2.0" "token" : "gNDMstgP3Yr81...0jA42DTc4MrHQ=.ODU1OT...4NjQ5MjE1RQ==.ad5bf522c...197a3944" } } const parcels = ["123456789","PX6761595367","PX1234102917"]; jQuery.ajax({ url: config['prod'].url+"/uss/v"+config['prod'].version+"/tracking/ckeckmailcollectionex", beforeSend: function(xhrObj){ xhrObj.setRequestHeader("api_key",config['prod'].token); }, data: { "states": true, "addPostOfficeInfo": false, "number": parcels, //wstawiamy tutaj tablice przesyłek z numerami przesyłek "language": "PL" }, type: "POST", contentType: "application/json", success: callback, error: callback })
$curl = curl_init(); $apiKey = "gNDMstgP3Yr81...0jA42DTc4MrHQ=.ODU1OT...4NjQ5MjE1RQ==.ad5bf522c...197a3944"; $numbers = ["123456789","PX6761595367","PX1234102917"]; //add your parcels array $params = array( 'language' => 'PL', 'number' => $numbers, 'addPostOfficeInfo' => false, 'states' => true ); curl_setopt_array($curl, array( CURLOPT_URL => 'https://uss.poczta-polska.pl/uss/v2.0/tracking/checkmailcollectionex?'.http_build_query($params), CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => '', CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => 'GET', CURLOPT_HTTPHEADER => array( 'Accept: application/json', 'api_key: $apiKey' ), )); $response = curl_exec($curl); curl_close($curl); echo $response;

Odpowiedź z USS dla metody checkmailcollectionex

Powyższa metoda służy do odpytania systemu śledzenia o wiele przesyłek w dwóch przypadkach:

  • gdy znamy zbiór przesyłek do odpytania (tablica przesyłek)
  • gdy w metodzie checkmailex otrzymamy klucz z tablicą obiektów components, wtedy nalezy uzyć tej metody w celu pobrania danych o przesyłkach w tej kolekcji.
{ "status": 0, "mailItems": [ { "mailInfo": { "number": "123456789", "typeOfMailCode": "PX2", "typeOfMailName": "Pocztex", "states": [ { "code": "PRZ", "name": "PRZYGOTOWANA", "time": "2024-06-06T11:59:01" } ], "finished": false, "events": [ { "code": "P_REJ_KN1", "name": "Otrzymano dane elektroniczne przesyłki", "time": "2024-06-06T11:59:01", "postOffice": { "name": "Elektroniczny Nadawca" }, "finished": false, "canceled": false, "state": { "code": "PRZ", "name": "PRZYGOTOWANA" } } ] }, "number": "123456789", "mailStatus": 1 }, { "mailInfo": { "number": "PX6761595367", "typeOfMailCode": "PX2", "typeOfMailName": "Pocztex", "states": [ { "code": "PRZ", "name": "PRZYGOTOWANA", "time": "2024-06-19T11:09:06" }, { "code": "NA", "name": "NADANA", "time": "2024-06-24T17:27:58" }, { "code": "TR", "name": "W TRANSPORCIE", "time": "2024-06-26T10:29:44" }, { "code": "DOR", "name": "W DORĘCZENIU", "time": "2024-06-26T10:55:17" }, { "code": "DO", "name": "DORĘCZONA", "time": "2024-06-26T16:07:42" } ], "finished": true, "events": [ { "code": "P_REJ_KN1", "name": "Otrzymano dane elektroniczne przesyłki", "time": "2024-06-19T11:09:06", "postOffice": { "name": "Elektroniczny Nadawca" }, "finished": false, "canceled": false, "state": { "code": "PRZ", "name": "PRZYGOTOWANA" } }, { "code": "P_NAD", "name": "Nadanie przesyłki", "time": "2024-06-24T17:27:58", "postOffice": { "code": "258468", "name": "UP Pabianice 1", "officeType": "UP" }, "finished": false, "canceled": false, "state": { "code": "NA", "name": "NADANA" } }, { "code": "P_WEMAIL", "name": "Wysłano powiadomienie e-mail", "time": "2024-06-24T17:45:35", "postOffice": { "name": "Centralna Baza Danych ZST" }, "finished": false, "canceled": false }, { "code": "P_WZL", "name": "Wysłanie przesyłki", "time": "2024-06-25T06:05:32", "postOffice": { "code": "258468", "name": "UP Pabianice 1", "officeType": "UP" }, "finished": false, "canceled": false, "state": { "code": "TR", "name": "W TRANSPORCIE" } }, { "code": "P_PZL", "name": "Nadejście", "time": "2024-06-25T09:28:49", "postOffice": { "name": "Terminal Przeładunkowy", "officeType": "CP WER" }, "finished": false, "canceled": false }, { "code": "P_WZL", "name": "Wysłanie przesyłki", "time": "2024-06-25T21:58:31", "postOffice": { "name": "Terminal Przeładunkowy", "officeType": "CP WER" }, "finished": false, "canceled": false, "state": { "code": "TR", "name": "W TRANSPORCIE" } }, { "code": "P_PZL", "name": "Nadejście", "time": "2024-06-26T02:12:20", "postOffice": { "name": "Terminal Przeładunkowy", "officeType": "CP WER" }, "finished": false, "canceled": false }, { "code": "P_Z", "name": "wyjazd z Urzędu", "time": "2024-06-26T09:00:42", "postOffice": { "code": "433373", "name": "WER Wrocław", "officeType": "CP WER" }, "finished": false, "canceled": false }, { "code": "P_WZL", "name": "Wysłanie przesyłki", "time": "2024-06-26T09:15:01", "postOffice": { "name": "Terminal Przeładunkowy", "officeType": "CP WER" }, "finished": false, "canceled": false, "state": { "code": "TR", "name": "W TRANSPORCIE" } }, { "code": "P_KOD", "name": "Przygotowano do doręczenia", "time": "2024-06-26T10:29:44", "postOffice": { "code": "269232", "name": "UP Świdnica Śląska 1", "officeType": "UP" }, "finished": false, "canceled": false, "state": { "code": "TR", "name": "W TRANSPORCIE" } }, { "code": "P_PZL", "name": "Nadejście", "time": "2024-06-26T10:45:17", "postOffice": { "code": "269232", "name": "UP Świdnica Śląska 1", "officeType": "UP" }, "finished": false, "canceled": false }, { "code": "P_WD", "name": "Przygotowano do doręczenia", "time": "2024-06-26T10:53:22", "postOffice": { "code": "269232", "name": "UP Świdnica Śląska 1", "officeType": "UP" }, "finished": false, "canceled": false, "state": { "code": "DOR", "name": "W DORĘCZENIU" } }, { "code": "P_WDML", "name": "Przekazano do doręczenia", "time": "2024-06-26T10:55:17", "postOffice": { "code": "269232", "name": "UP Świdnica Śląska 1", "officeType": "UP" }, "finished": false, "canceled": false, "state": { "code": "DOR", "name": "W DORĘCZENIU" } }, { "code": "P_WSMS", "name": "Wysłano powiadomienie sms", "time": "2024-06-26T11:05:25", "postOffice": { "name": "Centralna Baza Danych ZST" }, "finished": false, "canceled": false }, { "code": "P_WEMAIL", "name": "Wysłano powiadomienie e-mail", "time": "2024-06-26T11:06:04", "postOffice": { "name": "Centralna Baza Danych ZST" }, "finished": false, "canceled": false }, { "code": "P_D", "name": "Doręczono", "time": "2024-06-26T14:21:38", "postOffice": { "code": "269232", "name": "UP Świdnica Śląska 1", "officeType": "UP" }, "finished": true, "canceled": false, "state": { "code": "DO", "name": "DORĘCZONA" } }, { "code": "P_UKEPO", "name": "Udostępnienie podpisu odbiorcy", "time": "2024-06-26T14:21:42", "postOffice": { "code": "119479", "name": "Centralny System Sterujący dla Mobilnego Listonosza", "officeType": "CSS" }, "finished": false, "canceled": false }, { "code": "P_WEMAIL", "name": "Wysłano powiadomienie e-mail", "time": "2024-06-26T14:36:47", "postOffice": { "name": "Centralna Baza Danych ZST" }, "finished": false, "canceled": false }, { "code": "P_RDML", "name": "Rozliczenie KD przez listonosza", "time": "2024-06-26T15:57:34", "postOffice": { "code": "269232", "name": "UP Świdnica Śląska 1", "officeType": "UP" }, "finished": false, "canceled": false }, { "code": "P_KOL", "name": "Likwidacja księgi oddawczej po doręczeniu", "time": "2024-06-26T16:07:42", "postOffice": { "code": "269232", "name": "UP Świdnica Śląska 1", "officeType": "UP" }, "finished": false, "canceled": false, "state": { "code": "DO", "name": "DORĘCZONA" } } ] }, "number": "PX6761595367", "mailStatus": 0 }, { "number": "PX1234102917", "mailStatus": -1 } ] }

UWAGA 1! Nalezy zauważyć, że dla metody checkmailcollectionex zwracane są informacje o przesyłkach mailInfo w zbiorze mailItems.

UWAGA 2! dwie pozostałe przesyłki mają dwa różne mailStatus, które jednoznacznie definiują status danej przesyłki.

Dodatkowe zabezpieczenie konta PIN

W przypadku wybrania dodatkowej metody autoryzacji poprzez PIN, w tym celu należy za pomoca metody changepassword dodać do body klucz pin.

Przykład użycia:

//wykorzystujemy metodę $.ajax const config = { "prod" : { "url" : "https://uss.poczta-polska.pl", "version" : "2.0" "token" : "gNDMstgP3Yr81...0jA42DTc4MrHQ=.ODU1OT...4NjQ5MjE1RQ==.ad5bf522c...197a3944" } } jQuery.ajax({ url: config['prod'].url+"/uss/v"+config['prod'].version+"/tracking/changepassword", beforeSend: function(xhrObj){ xhrObj.setRequestHeader("api_key",config['prod'].token); }, data: { "pin" : "0000", //dotyczy kont z aktywnym kodem PIN "password" : "nowe haslo alfanumeryczne", "language": "EN" }, type: "POST", contentType: "application/json", success: callback, error: callback })
$curl = curl_init(); $login = "Twój login"; $password = strtoupper( hash("sha256", strtoupper( hash("sha256", "Twoje hasło") )) ); $pin = "0000", $apiKey = "gNDMstgP3Yr81...0jA42DTc4MrHQ=.ODU1OT...4NjQ5MjE1RQ==.ad5bf522c...197a3944"; curl_setopt_array($curl, array( CURLOPT_URL => 'https://uss.poczta-polska.pl/uss/v2.0/tracking/login', CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => '', CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_POSTFIELDS =>'{ "login": $login, "password": $password, "pin": $pin, "language": "PL" }', CURLOPT_HTTPHEADER => array( 'Content-Type: application/json', 'Accept: text/plain', 'api_key: '.$apiKey, ), )); $response = curl_exec($curl); curl_close($curl); echo $response;
Jeśli podano prawidłowo wszystkie dane (PIN w tym przypadku jest obowiązkowy) otrzymamy status 200 wraz z produkcyjnym tokenem oraz zakodowanym już własnym hasłem (nie musisz już dokonywać ponownego kodowania). Odpowiedź przyjmuje postać:
{ "password" : "9489750A8F6F2CF3F9AD1773AD527D0AE8646C6B53399B89B1B6984397F76E6F" "newToken": "HasuKq!w=P3Yr81...0jA42DTc4MrHQ=.ODU1OT...4NjQ5MjE1RQ==.ad5bf522c...197a3944" }
Tak wygenerowany newToken można już używać do pozostałych metod dostępnych w API

UWAGA! PIN wysyłany jest na jeden wskazany przez Klienta numer telefonu.

Klient posiadający aktywna usługe EPO

W przypadku posiadania specjalnego uprawnienia do pobierania kart EPO, mozna ją pobrać wykorzystując do tego celu metodę confirmationofeceipt.

Przykład:

//wykorzystujemy metodę $.ajax const config = { "prod" : { "url" : "https://uss.poczta-polska.pl", "version" : "2.0" "token" : "gNDMstgP3Yr81...0jA42DTc4MrHQ=.ODU1OT...4NjQ5MjE1RQ==.ad5bf522c...197a3944" } } jQuery.ajax({ url: config['prod'].url+"/uss/v"+config['prod'].version+"/tracking/confirmationofreceipt", beforeSend: function(xhrObj){ xhrObj.setRequestHeader("api_key",config['prod'].token); }, data: { "number" : "123456" }, type: "POST", contentType: "application/json", success: callback, error: callback })
$curl = curl_init(); $number = "123456"; $apiKey = "gNDMstgP3Yr81...0jA42DTc4MrHQ=.ODU1OT...4NjQ5MjE1RQ==.ad5bf522c...197a3944"; curl_setopt_array($curl, array( CURLOPT_URL => 'https://uss.poczta-polska.pl/uss/v2.0/tracking/confirmationofreceipt', CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => '', CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_POSTFIELDS =>'{ "number": $number }', CURLOPT_HTTPHEADER => array( 'Content-Type: application/json', 'api_key: '.$apiKey, ), )); $response = curl_exec($curl); curl_close($curl); echo $response;

4. Kody błędów

Opis kodów statusów HTTP
400
Odpowiedzi http 400 przypisane są do działań/weryfikacji związanych z nieprawidłowymi danymi podawanymi przez użytkowników. Informacje umożliwiające analizę konkretnych błędów przekazywane są w treści odpowiedzi. Należy poprawić dane przekazywane do metody.
401
Odpowiedzi http 401 związane są z brakiem autoryzacji użytkownika co związane jest z brakiem tokenu w nagłówku http (pozycja API_KEY) lub przeterminowaniem tego tokenu. Należy ponownie wykonać metodę login.
403
Odpowiedzi http 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
Wymagana zmiana hasła – jeżeli błąd nie pochodzi z funkcji login, należy wykonać funkcję login a następnie changepassword w przeciwnym razie funkcja login zwróciła dedykowany token i można od razu uruchomić metodę changepassword.
503
System niedostępny lub przerwa technologiczna. W body odpowiedzi znajduje się komunikat zwrotny ze szczegółową informacją.
204
Odpowiedź specyficzna dla metody confirmationofreceipt, odpowiedź http 204 zwracana jest w przypadku gdy dla wskazanego numeru nadania przesyłki nie znaleziono karty EPO (elektronicznego potwierdzenia odbioru).

5. Pliki POSTMAN

Dla Państwa wygody przygotowaliśmy gotowy plik konfiguracyjny, który po zaimportowaniu do aplikacji POSTMAN umożliwi szybkie przetestowanie metod REST API USS.

Aplikacja ta posiada skrypt, który zapisuje bieżące tokeny w zmiennej globalnej. Dlatego przy wybieraniu metody login, token ten jest zapisywany w zmiennej i nie trzeba go kopiować i zapisywać w nagłówkach.

Oto plik konfiguracyjny: Pobierz plik

Wniosek o utworzenie konta REST API USS

Jeżeli są Państwo zainteresowani pozyskaniem dedykowanego konta użytkownika z rozszerzonymi uprawnieniami, prosimy o wypełnienie i wysłanie poniższego formularza.