Metody i struktury usługi sieciowej śledzenia przesyłek Poczty Polskiej S.A.

Transkrypt

1 Metody i struktury usługi sieciowej śledzenia przesyłek Poczty Polskiej S.A. Ostatnia aktualizacja: Pobierz najnowszą wersję dokumentu Informacje ogólne Poczta Polska S.A. udostępnia usługę sieciową (tzw. web service), która może być wykorzystana do tworzenia aplikacji (telefony komórkowe, sklepy internetowe) umożliwiających śledzenie przesyłek pocztowych. Opis usługi jest dostępny pod adresem: zaś jej dokładna specyfikacja (WSDL) pod Usługa udostępnia obecnie informacje o następujących rodzajach przesyłek: 1. w obrocie krajowym: a. e - przesyłki, b. paczki pocztowe, c. POCZTEX, d. przesyłki pobraniowe, e. z zadeklarowaną wartością, f. przesyłki biznesowe, g. przesyłki gabarytowe, 2. w obrocie zagranicznym: a. EMS, b. paczki pocztowe. W wersji dla indywidualnych użytkowników usługa pozwala jednorazowo zapytać tylko o jeden numer przesyłki. Usługa wykorzystuje prostą autentykację (tzw. UsernameToken Authentication). Jako nazwę użytkownika należy podać,,sledzeniepp i hasło,,ppsa oraz ustawić passwordtype na PasswordText. Klientów masowych, którzy planują formułować jednorazowo zapytania o większe ilości przesyłek, prosimy o kontakt z Pocztą Polską S.A. (e mail: sledzenie@poczta-polska.pl) oraz podanie: 1. nazwy (firmy), 2. przewidywanej ilości zapytań w ciągu godziny, 3. przewidywanego zakresu ilościowego numerów przesyłek w jednym zapytaniu, 4. danych kontaktowych (adres korespondencyjny, adres poczty elektronicznej, telefon, nazwisko osoby do kontaktów), 5. adresu IP, z którego wykonywane będą zapytania. 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. Copyright by Poczta Polska S.A. Wszelkie prawa zastrzeżone. 1/8

2 Web service dla klientów indywidualnych/firmowych Usługa sieciowa śledzenia przesyłek Poczty Polskiej S.A. została przygotowana w dwóch wersjach: dla klientów indywidualnych (anonimowych) oraz klientów firmowych (masowych). Web service dla klientów indywidualnych jest dostępny z dowolnych adresów IP i umożliwia sprawdzenie pojedynczych przesyłek (w jednym zapytaniu). Podczas logowania należy użyć nazwy użytkownika sledzeniepp, hasło PPSA. Web service dla klientów firmowych jest dostępny jedynie z określonych adresów IP i umożliwia sprawdzenie danych wielu przesyłek (do 500) w jednym zapytaniu. Podczas logowania należy użyć indywidualnie przyznanej nazwy użytkownika i hasła. Informacje udostępniane przez web service 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, 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., lista zdarzeń związanych z przesyłką (statusów). Dla każdego ze zdarzeń udostępniana jest: o data i czas zdarzenia, o nazwa zdarzenia (wraz z kodem zdarzenia) np. doręczenie (P_D), o przyczyna zdarzenia (wraz z kodem przyczyny) np. nie zastano adresata (P_A_AANZ), o nazwa placówki, w której miało miejsce zdarzenie. 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: o nazwę miejscowości, o PNA, o nazwę ulicy, o numer domu, o numer lokalu, godziny pracy placówki: o 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, o w soboty, o w niedziele i święta, o uwagi dot. godzin pracy. Copyright by Poczta Polska S.A. Wszelkie prawa zastrzeżone. 2/8

3 Metody web service u Web service oferuje następujące metody: 1. Metody informacyjne 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, 2. Sprawdzanie jednej lub wielu przesyłek sprawdzprzesylke(string numer) 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, sprawdzprzesylkepl(string numer) 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, sprawdzprzesylki(string[] numer) wymaga podania jednego lub kilku numerów przesyłek, a zwraca informacje o podanych przesyłkach w strukturze Komunikat szczegółowe informacje o placówkach w atrybutach typu Jednostka nie są generowane, sprawdzprzesylkipl(string[] numer) wymaga podania jednego lub kilku numerów przesyłek, a zwraca informacje o podanych przesyłkach w strukturze Komunikat - szczegółowe informacje o placówkach w atrybutach typu Jednostka są generowane, 3. Sprawdzanie przesyłek posiadających zdarzenia w podanym okresie (metody OdDo) sprawdzprzesylkioddo(string[] numer, String oddnia, String dodnia) 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(string[] numer, String oddnia, String dodnia) jak metoda powyżej jednak generowane są szczegółowe informacje o placówkach w atrybutach typu Jednostka, 4. Metody testowe witaj metoda do testów poprawności przekazywania parametrów. Wymaga podania parametru imie (string), a zwraca tekst Witaj <imie>. Copyright by Poczta Polska S.A. Wszelkie prawa zastrzeżone. 3/8

4 Struktury danych Komunikat: o status (int): 0 ok -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 Uwaga! Pole status występuje również w strukturze Przesylka wartości pola mają tam jednak inne znaczenie. o przesylki (ListaPrzesylek) wypełniona dla statusu równego 0 ListaPrzesylek: o przesylka (Przesylka[]) Rys. 1 - Diagram struktur danych zwracanych przez web service Przesylka: o status (integer) 0 ok, 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 Copyright by Poczta Polska S.A. Wszelkie prawa zastrzeżone. 4/8

5 o o Uwaga! Pole status występuje również w strukturze Komunikat wartości pola mają tam jednak inne znaczenie. numer (string[20]) numer przesyłki (zgodny z podanym w parametrze metody) dane (DanePrzesylki) DanePrzesylki: o numer (string[20]) ponownie numer przesyłki o kodrodzprzes (string[5]) kod rodzaju przesyłki o rodzprzes (string[64]) rodzaj przesyłki o datanadania (string[10]) data nadania przesyłki w postaci yyyy-mm-dd o kodkrajunadania (string[5]) kod kraju nadania przesyłki (np. PL) o krajnadania (string[64]) nazwa kraju nadania (np. POLSKA) o kodkrajuprzezn (string[5]) kod kraju przeznaczenia przesyłki (np. PL) o krajprzezn (string[64]) nazwa kraju przeznaczenia (np. POLSKA) o urzadnadania (Jednostka) informacje o placówce nadania o urzadprzezn (Jednostka) informacje o placówce przeznaczenia o masa (float) waga przesyłki w kg o zakonczonoobsluge (boolean) czy miało miejsce tzw. zdarzenie kończące (np. doręczenie, odebranie przesyłki w urzędzie, zwrot przesyłki itp.) o zdarzenia (ListaZdarzen) ListaZdarzen: o zdarzenie (Zdarzenie[]) Zdarzenie: o czas (string[16]) czas zdarzenia w postaci yyyy-mm-dd hh-nn o nazwa (string[64]) nazwa zdarzenia (np. Wysłanie z ładunkiem) o jednostka (Jednostka) jednostka (placówka PP), w której miało miejsce zdarzenie o kod (string[10]) kod zdarzenia o przyczyna (Przyczyna) przyczyna zdarzenia atrybut jest wypełniany jedynie dla pewnych użytkowników web service u Występujące w systemie zdarzenia to: Kod Nazwa P_A Awizo przesyłki P_AK Awizo przesyłki - korekta rezultatu P_D Doręczenie P_NAD Nadanie P_ND Nieudane doręczenie P_NDPD Nieudane doręczenie - kolejna próba dziś P_NDPJ Nieudane doręczenie - kolejna próba jutro P_NDK Nieudane doręczenie - korekta rezultatu P_NDZAP Nieudane doręczenie - zatrzymana - adresat powiadomiony P_OWU Odebranie przesyłki w urzędzie P_OWUWPP Odebranie przesyłki w urzędzie wymiany (poczta przychodząca) P_OWUWPW Odebranie przesyłki w urzędzie wymiany (poczta wychodząca) P_OWUK odebranie w urzędzie (korekta rezultatu) P_PA Ponowne awizo P_WVOICE Powiadomienie głosowe dla przesyłki P_S Pozostawienie przesyłki w skrytce P_PCWY Przekazanie przesyłki do cła - wywóz G Przesyłka zatrzymana do kontroli E Przesyłka zwrócona do nadawcy P_WEOC Przyjęcie przesyłki w kraju przeznaczenia P_WEPL Przyjęcie przesyłki w Polsce P_PZL Przyjęcie przesyłki z ładunkiem P_REJ Rejestracja przesyłki P_RUD Rejestracja przesyłki w urzędzie doręczenia P_SDUNPK skierowanie do urzędu niedoręczalnych przesyłek (korekta rez.) P_KWD Wpis przesyłki do księgi wydanych P_KOD Wprowadzenie przesyłki do księgi oddawczej Copyright by Poczta Polska S.A. Wszelkie prawa zastrzeżone. 5/8

6 P_WD Wydanie przesyłki doręczycielowi P_WUPD Wydanie przesyłki uprawnionemu do odbioru P_W Wysłanie dla przesyłki P_WFAX Wysłanie faksu dla przesyłki P_WYOC Wysłanie przesyłki z kraju nadania P_WZL Wysłanie przesyłki z ładunkiem P_WYPL Wysłanie przesyłki z Polski P_WSMS Wysłanie SMS dla przesyłki P_ZPUCPP Zatrzymanie przesyłki przez urząd celny (poczta przychodząca) P_ZPUCWKP Zatrzymanie przesyłki przez urząd celny w kraju przeznaczenia P_ZWC Zatrzymanie przesyłki w cle P_WPUCPP Zwolnienie przesyłki przez urząd celny (poczta przychodząca) P_WPUCWKP Zwolnienie przesyłki przez urząd celny w kraju przeznaczenia P_CZDKN Zwrot przesyłki do kraju nadania P_A Awizo przesyłki P_AK Awizo przesyłki - korekta rezultatu P_D Doręczenie P_NAD Nadanie P_ND Nieudane doręczenie P_NDPD Nieudane doręczenie - kolejna próba dziś P_NDPJ Nieudane doręczenie - kolejna próba jutro P_NDK Nieudane doręczenie - korekta rezultatu P_NDZAP Nieudane doręczenie - zatrzymana - adresat powiadomiony P_OWU Odebranie przesyłki w urzędzie P_OWUWPP Odebranie przesyłki w urzędzie wymiany (poczta przychodząca) P_OWUWPW Odebranie przesyłki w urzędzie wymiany (poczta wychodząca) P_OWUK odebranie w urzędzie (korekta rezultatu) P_PA Ponowne awizo P_WVOICE Powiadomienie głosowe dla przesyłki P_S Pozostawienie przesyłki w skrytce P_ZDUN Zwrot przesyłki do urzędu nadania Jednostka: o nazwa (string[64]) o daneszczegolowe (SzczDaneJednostki) puste dla metod SprawdzPrzesylke i SprawdzPrzesylki, wypełnione dla SprawdzPrzesylkePl i SprawdzPrzesylkiPl Przyczyna: o nazwa (string[64]) przyczyna zdarzenia o kod (string[10]) kod przyczyny zdarzenia SzczDaneJednostki: o szergeogr (float z N(8,6)) szerokość geograficzna placówki o dlgeogr (float z N(9,6)) długość geograficzna placówki o miejscowość (string[64]) miejscowość, w której znajduje się placówka o pna (string[6]) PNA (kod pocztowy) placówki o ulica (string[169]) - ulica o nrdomu (string[11]) numer domu o nrlokalu (string[7]) numer lokalu o godzinypracy (GodzinyPracy) godziny pracy placówki GodzinyPracy: o dnirobocze (GodzinyZUwagami) informacja o godzinach pracy placówki w dni robocze o soboty (GodzinyZUwagami) informacja o godzinach pracy placówki w soboty o niedzisw (GodzinyZUwagami) informacja o godzinach pracy placówki w niedziele i święta GodzinyZUwagami: o godziny (string[4000]) godziny pracy np. 08:00-24:00 o uwagi (string[4000]) uwagi do godzin pracy Copyright by Poczta Polska S.A. Wszelkie prawa zastrzeżone. 6/8

7 Informacja 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) Testowe numery przesyłek Web service zwraca pewne ustalone komunikaty dla wybranych, testowych numerów przesyłek. Metody SprawdzPrzesylki i SprawdzPrzesylkiPl oraz SprawdzPrzesylkiOdDo i SprawdzPrzesylkiOdDoPl (pytania o wiele przesyłek) Jeśli pierwszym numerem w zapytaniu jest testk-1, testk-2, testk-3 lub testk-99 metody zwracają strukturę Komunikat ze statusem: o -1(zapytanie o zbyt dużą liczbę przesyłek) dla numeru przesyłki testk-1 o -2(brak uprawnień do sprawdzania wielu przesyłek) dla numeru testk-2 o -3(błędne daty w zapytaniu SprawdzPrzesylkiOdDo lub SprawdzPrzesylkiOdDoPl) dla numeru testk-3 o -99(inny, nieokreślony błąd) dla numeru testk-99 Numery testk-1, testk-2, testk-3, testk-99 nie działają w metodach pytających o jedną przesyłkę. W tych metodach dla numerów testk-1, testk-2, testk-3, testk-99 zawsze zwracany będzie status -2 (numer niepoprawny). Metody SprawdzPrzesylke i SprawdzPrzesylkePl (pytanie o jedną przesyłkę) Testowe numery przesyłek to: testp0, testp1, testp-1, testp-2, testp-99. Dla tych numerów pole status w zwracanej strukturze Przesylka ma wartość: o 0 (ok) dla numeru przesyłki testp0 o 1 (są inne przesyłki o podanym numerze) dla testp1 o -1(brak przesyłki o podanym numerze) dla testp-1 o -2(niepoprawny numer przesyłki) dla testp-2 o -99(inny, nieokreślony błąd) dla numeru testk-99 Dodatkowo dla numerów testp0 i testp1 zwracane są testowe dane przesyłki i jej zdarzeń. Numerów przesyłek testp0, testp1, testp-1, testp-2, testp-99 można również użyć w pytaniu o wiele przesyłek. W zwróconej odpowiedzi struktury Przesylka odpowiadające tym numerom będą miały ustalony, testowy status, struktury odpowiadające innym numerom będą miały status rzeczywisty. Copyright by Poczta Polska S.A. Wszelkie prawa zastrzeżone. 7/8

8 Autentykacja Web service wykorzystuje mechanizm prostej autentykacji opartej o tzw. Username Token Element. Standard ten został zdefiniowany w Web Services Security (WSS): 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 może wyglądać tak: <soapenv:envelope xmlns:sled=" xmlns:soapenv=" <soapenv:header> <wsse:security soapenv:mustunderstand="1" xmlns:wsse=" 1.0.xsd"> <wsse:usernametoken wsu:id="usernametoken-2" xmlns:wsu=" 1.0.xsd"> <wsse:username>sledzeniepp</wsse:username> <wsse:password Type=" <wsse:nonce EncodingType=" <wsu:created> t07:59:28.656z</wsu:created> </wsse:usernametoken> </wsse:security> </soapenv:header> <soapenv:body> <sled:witaj> <sled:imie>jan</sled:imie> </sled:witaj> </soapenv:body> </soapenv:envelope> Akceptowana, minimalna wersja Security Element może nie zawierać elementów Nonce i Created oraz identyfikatora (id) UserNameToken: <wsse:security soapenv:mustunderstand="1" xmlns:wsse=" <wsse:usernametoken xmlns:wsu=" 1.0.xsd"> <wsse:username>sledzeniepp</wsse:username> <wsse:password Type=" </wsse:usernametoken> </wsse:security> Copyright by Poczta Polska S.A. Wszelkie prawa zastrzeżone. 8/8