OPIS WebAPI Wersja 0.20, 29.11.2012 Opis WebAPI udostępnianego przez program Elektroniczny Nadawca 1
Spis treści Historia zmian... 5 Wprowadzenie... 7 Słownik pojęć... 7 Ogólne zasady integracji... 7 Spis Metod... 7 addshipment... 7 getenvelopebufor... 8 sendenvelope... 8 getaddresslabel... 8 getoutboxbook... 8 getfirmowapocztabook... 8 getenvelopestatus... 8 clearenvelope... 8 clearenvelopebyguids... 8 getenvelopecontentshort... 9 getenvelopecontentfull... 9 getenvelopelist... 9 getkarty... 9 setaktywnakarta... 9 geturzedynadania... 9 geturzedywydajaceeprzesylki... 9 uploadiwdcontent... 9 downloadiwdcontent... 9 changepassword... 9 2
getpasswordexpireddate... 10 hello... 10 getaddreslabelbyguid... 10 getplacowkipocztowe... 10 getguid... 10 getkierunki... 10 getkierunkiinfo... 10 setenvelopebufordatanadania... 10 Wybrane klasy... 11 adrestype... 11 errortype... 11 przesylkatype... 11 przesylkarejestrowanatype... 11 przesylkanierejestrowanatype... 12 pobranietype... 12 eprzesylkatype... 12 paczkapocztowaplustype... 13 paczkapocztowatype... 14 przesylkalistowazadeklarowanawartosctype... 14 przesylkanawarunkachszczegolnychtype... 15 przesylkapobraniowatype... 15 przesylkapoleconakrajowatype... 16 przesylkapoleconazagranicznatype... 16 przesylkazagranicznatype... 16 pocztexkrajowytype... 17 odbiorprzesylkiodnadawcytype... 18 3
doreczenietype... 18 zwrotdokumentowtype... 18 potwierdzenieodbiorutype... 19 potwierdzeniedoreczeniatype... 19 przesylkabiznesowatype... 20 subprzesylkabiznesowatype... 21 przesylkabiznesowaplustype... 21 subprzesylkabiznesowaplustype... 22 placowkapocztowatype... 23 lokalizacjageograficznatype... 23 wspolrzednageograficznatype... 23 listzwyklytype... 24 reklamowatype... 24 FAQ... 25 4
Historia zmian Wersja Data Zmienione przez Opis modyfikacji 05 24.02.2011 KŚ - Dodano stronę tytułową, spis treści, historie zmian - Dodano rozdział Ogólne zasady integracji 06 02.03.2011 KŚ - Dodano plik wsdl 06 03.03.2011 MP - poprawki nazw usług 07 22.03.2011 TG - czyszczenie, usunięcie komentarzy, zatwierdzenie propozycji zmian z wer 06 08 28.06.2011 TG - zmiany wprowadzone w wersji webapi 2.0, opis nowych funkcji, usunięcie funkcji, z których zrezygnowano 09 28.07.2011 TG - czyszczenie, ostatnie poprawki 10 07.10.2011 TG - dodanie opisu przesyłki zagranicznej zwykłej 11 22.11.2011 TG - dodanie pliku wsdl w wersji 2.2.0 12 30.12.2011 TG - dodanie opisu przesyłki biznesowej, nowa wersja pliku wsól 13 19.01.2012 TG - dodanie FAQ ( opis połączenia.net4) 14 30.03.2012 TG - dodanie opisu metody do pobieranie pojedynczego wydruku, rozszerzenie FAQ o przykłady PHP 15 11.06.2012 TG - dodanie opisu nowych metod: getenvelopebufor, clearenvelopebyguids, getaddreslabelbyguid, getplacowkipocztowe, getguid, getkierunki, getkierunkiinfo, 16 26.06.2012 TG - aktualizacja przykładów w FAQ (.NET) 17 08.09.2012 TG - zmiany typu pocztexkrajowytype 5
18 23.11.2012 TG - opis zmian dla wersji 3.3.0 (nowa metoda setenvelopebufordatanadania, rozszerzenie getplacowkipocztowe) 19 23.11.2012 KŚ - aktualizacja FAQ (akceptacja certyfikatu) 20 29.11.2012 TG - dodanie opisu nowych typów związanych z nowymi usługami (listzwyklytype, reklamowatype) 6
Wprowadzenie Słownik pojęć przesyłka obiekt zawierający komplet informacji (m.in. o adresacie czy o wybranych usługach) o pojedynczej fizycznej przesyłce, która zostanie dostarczona do urzędu pocztowego. pakiet obiekt zawierający zbiór przesyłek urząd nadania fizyczna placówka Poczty Polskiej S.A. gdzie dostarczone zostaną przesyłki Ogólne zasady integracji Zarejestruj się na stronie e-nadawca.poczta-polska.pl Podpisz z nami umowę Zaimplementuj poniższy opis Przetestuj efekty swojej pracy na stronie en-testwebapi.poczta-polska.pl Zacznij używać Spis Metod addshipment Metoda pozwalająca dodać przesyłki (max 500 za jednym wywołaniem) do pakietu. Posiada jeden parametr wejściowy, który może zawierać do 500 obiektów typu przesylkatype. przesylkatype jest typu abstrakcyjnego, dlatego należy przekazywać argumenty typów pochodnych od przesylkatype np.paczkapocztowatype czy przesylkapobraniowatype. Uwaga zaleca się aby przed dodaniem pierwszej przesyłki użyć metody clearenvelope celem usunięcia poprzednio dodanych przesyłek do nie wysłanego pakietu. Metoda ta zwraca dla każdej przesłanej przesyłki własność numernadania. W przypadku określenia numeru nadania po stronie klienta jest zwracany podany numer nadania, w przypadku nie podania jest on nadawany po stronie EN. Wyjątek stanowi usługa przesyłki poleconej krajowej (klasa przesylkapoleconakrajowatype), która dopuszcza przekazanie danych bez numerów nadania. Dodatkowo w przypadku niepowodzenia w elemencie error zwracane są szczegóły błędów, które wystąpiły. Wszystkie przesyłki dodawane są do domyślnego pakietu. Nie jest możliwe utworzenie kilku pakietów przesyłek a następnie wybiórcze ich wysłanie. Domyślny pakiet tworzy się (o ile wcześniej nie został stworzony) przy pierwszym użyciu metody addshipment lub clearenvelope. Oczywiście możliwe jest wielokrotne wywołanie metody addshipment celem dodania do jednego pakietu więcej niż 500 przesyłek. Dla każdej przesyłki wysyłanej wymagany jest parametr guid. Jest on zwracany przez tą metodę celem dopasowania listy zwracanych błędów do każdej przesłanej przesyłki. 7
getenvelopebufor ELEKTRONICZNY NADAWCA Metoda pozwala pobrać informacje o przesyłkach znajdujących się w buforze, dodanych metodą addshipment. Metoda pozwala pobrać dane o przesyłkach do momentu wykonania sendenvelope. sendenvelope Metoda pozwalająca wysłać wszystkie przesyłki dodane wcześniej metodą addshipment. Jej argumentem jest urzadnadania. Do wypełnienia pola urzadnadania można skorzystać z metody geturzedynadania która zwraca dopuszczalne dla nadającego urzędy nadania. Jej drugi argument pakiet jest opcjonalny, i służy do przekazania informacji o pakietach wstępnie posortowanych przesyłek. Zwykle należy pominąć ten atrybut (przekazać pustą tablice elementów PakietType). Uwaga data nadania jest zawsze ustawiana na datę wywołania metody sendenvelope. Należy zwrócić uwagę iż możliwe jest wywołanie sendenvelope powinno się odbyć w tym samym dniu w którym zostało wykonane pierwsze addshipment (licząc od ostatniego wywołania sendshipment lub clearenvelope). getaddresslabel Metoda pozwalająca pobrać nalepki adresowe. Wydruk jest w formacie PDF. Parametrem wejściowym jest idenvelope zwracane przez metodę sendenvelope. Wydruki SA podzielone na każda przesyłkę. Identyfikacja poprzez pole guid (przesyłane w metodzie addshipment) getoutboxbook Metoda pozwalająca pobrać wydruk Książki Nadawczej. Wydruk jest w formacie PDF. Parametrem wejściowym jest idenvelope zwracane przez metodę sendenvelope. getfirmowapocztabook Metoda pozwalająca pobrać wydruk zestawiania dla Firmowej Poczty. Wydruk jest w formacie PDF. Parametrem wejściowym jest idenvelope zwracane przez metodę sendenvelope. getenvelopestatus Metoda pozwala pobrać status przekazanego pakietu przesyłek. clearenvelope Metoda czyszcząca pakiet z przesyłek. Usuwa wszystkie informacje o przesyłkach, które zostały dodane metodą addshipment. Zaleca się jej wykorzystanie przed pierwszym użyciem metody addshipment (w przypadku awarii możliwa jest sytuacja, w której przesyłki pozostaną w pakiecie). clearenvelopebyguids Metoda pozwala na wybiórcze usunięcie przesyłek z bufora. Parametrem wejściowym jest tablica guidów przesyłek do usunięcia. Uwaga przesyłki z opcją wielopaczkowości powinny być usuwane w całości poprzez guid przesyłki głównej. 8
getenvelopecontentshort ELEKTRONICZNY NADAWCA Metoda pozwalająca pobrać informacje zwrotne o nadanych przesyłkach w wersji skróconej. Parametrem wejściowym jest idenvelope zwracane przez metodę sendenvelope. getenvelopecontentfull Metoda pozwalająca pobrać informacje zwrotne o nadanych przesyłkach w wersji pełnej. Parametrem wejściowym jest idenvelope zwracane przez metodę sendenvelope. getenvelopelist Metoda pozwalająca pobrać listę pakietów, które są dostępne do pobrania wraz ze statusami. getkarty Metoda pozwalające pobrać informacje o dostępnych kartach umowy. setaktywnakarta Metoda pozwalająca określić bieżącą kartę, na której nadawane są dane o przesyłkach. geturzedynadania Metoda pozwala pobrać wszystkie urzędy nadania, dla których nadający ma podpisaną umowę z PP. Uwaga nie jest możliwe wysłanie przesyłek na dowolny urząd. geturzedywydajaceeprzesylki Metoda specyficzna dla produktu E-PRZESYŁKA. Pozwala pobrać listę urzędów, w których odbiorca będzie mógł odebrać E-PRZESYŁKĘ. uploadiwdcontent Metoda umożliwia przesłanie zawartości pliku xml zgodnego ze standardem IWD. Nie zalecamy używanie tej metody. Przeznaczona jest dla podmiotów, które wcześniej zaimplementowały w swoich systemach tworzenie plików w standardzie IWD. downloadiwdcontent Metoda umożliwia pobranie pakietu przesyłek w formacie pliku xml zgodnego ze standardem IWD. Nie zalecamy używanie tej metody. Przeznaczona jest dla podmiotów, które wcześniej zaimplementowały w swoich systemach tworzenie plików w standardzie IWD. changepassword Metoda pozwalająca na zmianę hasła dostępu do systemu EN. Ze względu na ustawę o ochronie danych osobowych wymagamy zmiany hasła max, co 30dni ( min, co 1 dzień). Wymagania, co do hasła: Minimalna ilość znaków: 10, Hasło powinno zawierać przynajmniej 1 wielką literę, Hasło powinno zawierać przynajmniej 1 małą literę, 9
Hasło powinno zawierać przynajmniej 1 cyfrę, getpasswordexpireddate Metoda pozwalająca pobrać czas ważności hasła hello Metoda testowa getaddreslabelbyguid ELEKTRONICZNY NADAWCA metoda umożliwiająca pobranie pojedynczego wydruku nalepki adresowej z wykorzystaniem guid parametrem wejściowym jest tablica guid ów przesyłek, na wyjściu otrzymywane są obiekty addresslabelcontent z zawartością plików PDF z wydrukami nalepek. UWAGA! Metoda pozwala pobrać wydruki dla nalepek do momentu wykonania metody sendenvelope. getplacowkipocztowe Metoda pozwalająca pobrać listę placówek pocztowych. Lista jest ograniczona do wybranego w parametrze wejściowym województwa. Województwa są zdefiniowane poprzez kody GUS województw. Metoda zwraca kolekcję obiektów klasy placowkapocztowatype. getguid Metoda pozwala pobrać lista guidów (1-100), guidy są wykorzystywane podczas transmisji danych o przesyłkach, każda przesyłka powinna posiadać unikalny guid. Zalecamy wykorzystywanie tej metody do nadawania guidów przesyłkom w metodzie addshipement. getkierunki Metoda dedykowana dużym nadawcom, pozwalająca pobrać informacje o kierunkach, na które należy wstępnie posortować przesyłki. Parametrem wejściowym jest nazwa planu kierowania. Nazwa ta jest przekazywana podczas indywidualnych negocjacji. getkierunkiinfo Metoda dedykowana dużym nadawcom, pozwalająca pobrać informacje o kierunkach, na które należy wstępnie posortować przesyłki. Metoda pozwala określić czy jest potrzebna aktualizacja lokalnej kopii informacji o kierunkach. setenvelopebufordatanadania Metoda umożliwiająca zmianę daty nadania dla przesyłek znajdujących się w buforze. Dzięki niej możliwe będzie przygotowanie przesyłek do nadania na dni następne. Data ustawiona za pomocą tej metody jest drukowana na nalepkach adresowych w polu data nadania tak, więc powinna być zgodna z faktyczną datą nadania. Wywołanie jej powinno także pomóc w przypadku otrzymania błędu. 11110 Zbiór zawiera przesyłki z błędami lub data nadania jest niewłaściwa. Zamknięcie zbioru jest niemożliwe UWAGA. Metoda zawsze zwraca info. 10
errornumber = 0; errordesc = Data nadania na wydrukach musi być zgodna z faktyczną data nadania. Sprawdź wydruki. Jest to związane z tym, iż data nadania generowana na wydrukach pobierana jest właśnie z tego miejsca. W przypadku zmiany tej daty wszystkie nalepki wcześniej pobrane będą miały niewłaściwą datę nadania, co jest niezgodne z regulaminami świadczenia usług pocztowych. Wybrane klasy adrestype typ przeznaczony do przekazywania informacji o odbiorcy przesyłki. Jest elementem każdej przesyłki musi w niej wystąpić dokładnie 1 raz. nazwa nazwa2 ulica numerdomu numerlokalu miejscowosc kod kraj Nazwa odbiorcy (pole wymagane) Nazwa odbiorcy ciąg dalszy (pole opcjonalne) Nazwa ulicy odbiorcy (pole wymagane) Numer domu odbiorcy (pole wymagane) Numer lokalu/mieszkania odbiorcy (pole opcjonalne) Nazwa miasta/miejscowości (pole wymagane) Kod pocztowy tylko cyfry (bez myślnika) (pole wymagane) Nazwa kraju odbiorcy, domyślnie Polska (pole opcjonalne) errortype typ przeznaczony na komunikaty błędów. Każda klasa zwracana z web serwisu zawiera element tego typu. Element ten jest pusty w przypadku gdy wszystko przebiegło poprawnie. W przeciwnym wypadku zawiera numer błędu oraz skrócony opis problemu. Element ten może wystąpić w obiekcie odpowiedzi wiele razy w przypadku błędów złożonych. errornumber errordesc Numer błędu Skrócony opis błędu/problemu, jaki wystąpił przesylkatype klasa abstrakcyjna. Zawiera wspólne elementy dla wszystkich przesyłek przekazywanych poprzez webserwis. Po tej klasie dziedziczą wszystkie klasy obiektów przesyłek. guid Identyfikator guid, pole to jest wymagane. Możliwe jest wykorzystanie go do celów powiązania nadawanych informacji o przesyłkach z danymi w swoim systemie. Pole to służy do powiązania błędów zwracanych z nadawanymi przesyłkami. przesylkarejestrowanatype klasa abstrakcyjna, klasa dziedziczy po przesylkatype. Zawiera wspólne elementy dla wszystkich przesyłek przekazywanych poprzez webserwis. Po tej klasie dziedziczą wszystkie klasy obiektów przesyłek rejestrowanych. Klasy przesyłek różnią się od siebie w zależności od usługi z której chcemy skorzystać. numernadania Numer nadania przesyłki. Obecnie pole to jest wymagane. Należy podać tutaj właściwy numer nadania otrzymany z Poczty Polskiej S.A. Numery nadania różnią się budową w 11
adres zależności od rodzaju usługi. Pole NIE jest wymagane. Element klasy adrestype zawiera informacje o odbiorcy przesyłki. Musi wystąpić dokładnie 1 raz. przesylkanierejestrowanatype klasa abstrakcyjna, klasa dziedziczy po przesylkatype. Zawiera wspólne elementy dla wszystkich przesyłek przekazywanych poprzez webserwis. Po tej klasie dziedziczą wszystkie klasy obiektów przesyłek nierejestrowanych. Klasy przesyłek różnią się od siebie w zależności od usługi, z której chcemy skorzystać. ilosc Pole określające ilość przesyłek danego typu 1-9999999 pobranietype klasa ta odpowiada za przekazanie danych o pobraniu sposobpobrania kwotapobrania nrb tytulem Pole wskazujące, w jaki sposób zostanie dokonane rozliczenie w przypadku nadawania przesyłki pobraniowej. Możliwe są trzy wartości: null, PRZEKAZ i RACHUNEK_BANKOWY Pole określające wartość kwoty pobrania. Pole opcjonalne. W przypadku określenia należy określić również pole sposobpobrania. Pole określające numer rachunku bankowego w przypadku pobrania na rachunek bankowy Pole określające tytuł przelewu w przypadku pobrania na rachunek bankowy sprawdzeniezawartosciprzesylkiprzezodbiorce Określenie dodatkowej usługi eprzesylkatype typ przeznaczony na przekazywanie danych o usłudze E-PRZESYŁKA. Klasa ta dziedziczy po klasie przesylkarejestrowanatype. esposobpowiadomieniaadresata esposobpowiadomienianadawcy ekontaktadresata Określenia, w jaki sposób odbiorca ma zostać powiadomiony o tym, że przesyłka jest możliwa do odebrania. Dopuszczalne wartości, SMS, EMAIL Określenie, w jaki sposób nadawca ma zostać powiadomiony o tym, że przesyłka została odebrana. Możliwe wartości null, SMS, EMAIL Określa szczegóły do powiadomienia odbiorcy. Należy podać tutaj odpowiednie numer telefonu komórkowego, 12
ekontaktnadawcy ostroznie wartosc urzadwydaniaeprzesylki pobranie lub adres email, w zależności od tego, co zostało wybrane w polu esposobpowiadomieniaadresata Określa szczegóły do powiadomienia nadawcy. Należy podać tutaj odpowiednie numer telefonu komórkowego, lub adres email, w zależności od tego, co zostało wybrane w polu esposobpowiadomienianadawcy Wartość logiczna określająca korzystanie z usługi ostrożnie. Określenie wartości nadawanej przesyłki. Określenie wartości jest równoznacznie ze chęcią skorzystania z usługi przesyłka z określoną wartością. Określenie, w jakim urzędzie zostanie ma zostać odebrana przesyłka. Lista urzędów możliwa do pobrania metodą geturzedywydajaceeprzesylki Element typu pobranietype. Opisujący pobranie paczkapocztowaplustype typ przeznaczony na przekazywanie danych o usłudze paczka pocztowa PLUS. Klasa ta dziedziczy po klasie przesyłkarejestrowanatype posterestante Znacznik logiczny określający, że adres, który został podany jest adresem poste restante. Domyślnie fałsz. iloscpotwierdzenodbioru Określenie ilości potwierdzeń odbioru. Domyślnie 0. Podanie wartości 1 oznacza chęć skorzystania z usługi przesłania za potwierdzeniem odbioru. kategoria gabaryt wartosc zwrotdoslanie Określenie kategorii przesyłki. Dopuszczalne wartości: EKONOMICZNA, PRIORYTETOWA Określa gabaryt przesyłki. Dopuszczalne wartości to: GABARYT_A, GABARYT_B Określenie wartości nadawanej przesyłki. Określenie wartości jest równoznacznie ze chęcią skorzystania z usługi przesyłka z określoną wartością. Określenie usługi komplementarnej 13
paczkapocztowatype typ przeznaczony na przekazywanie danych o usłudze paczka pocztowa. Klasa ta dziedziczy po klasie przesylkarejestrowanatype. posterestante Znacznik logiczny określający, że adres który został podany jest adresem poste restante. Domyślnie fałsz. iloscpotwierdzenodbioru Określenie ilości potwierdzeń odbioru. Domyślnie 0. Podanie wartości 1 oznacza chęć skorzystania z usługi przesłania za potwierdzeniem odbioru. kategoria gabaryt wartosc zwrotdoslanie egzemplarzbiblioteczny dlaociemnialych Określenie kategorii przesyłki. Dopuszczalne wartości: EKONOMICZNA, PRIORYTETOWA Określa gabaryt przesyłki. Dopuszczalne wartości to: GABARYT_A, GABARYT_B Określenie wartości nadawanej przesyłki. Określenie wartości jest równoznaczne z chęcią skorzystania z usługi przesyłka z określoną wartością. Określenie usługi komplementarnej Określenie usługi komplementarnej. Określenie usługi komplementarnej. przesylkalistowazadeklarowanawartosctype typ przeznaczony na przekazywanie danych o usłudze przesyłka listowa z zadeklarowana wartością. Klasa ta dziedziczy po klasie przesylkarejestrowanatype. posterestante Znacznik logiczny określający, że adres, który został podany jest adresem poste restante. Domyślnie fałsz. iloscpotwierdzenodbioru Określenie ilości potwierdzeń odbioru. Domyślnie 0. Podanie wartości 1 oznacza chęć skorzystania z usługi przesłania za potwierdzeniem odbioru. kategoria gabaryt wartosc Określenie kategorii przesyłki. Dopuszczalne wartości: EKONOMICZNA, PRIORYTETOWA Określa gabaryt przesyłki. Dopuszczalne wartości to: GABARYT_A, GABARYT_B Określenie wartości nadawanej przesyłki. Określenie wartości jest równoznacznie ze chęcią skorzystania z usługi przesyłka z określoną wartością. Pole to jest wymagane. 14
przesylkanawarunkachszczegolnychtype typ przeznaczony na przekazywanie danych o usłudze przesyłka na warunkach szczególnych. Klasa ta dziedziczy po klasie przesylkarejestrowanatype. posterestante Znacznik logiczny określający, że adres, który został podany jest adresem poste restante. Domyślnie fałsz. iloscpotwierdzenodbioru Określenie ilości potwierdzeń odbioru. Domyślnie 0. Podanie wartości 1 oznacza chęć skorzystania z usługi przesłania za potwierdzeniem odbioru. kategoria Określenie kategorii przesyłki. Dopuszczalne wartości: EKONOMICZNA, PRIORYTETOWA przesylkapobraniowatype typ przeznaczony na przekazywanie danych o usłudze paczka pocztowa. Klasa ta dziedziczy po klasie przesylkarejestrowanatype. posterestante Znacznik logiczny określający, że adres, który został podany jest adresem poste restante. Domyślnie fałsz. iloscpotwierdzenodbioru Określenie ilości potwierdzeń odbioru. Domyślnie 0. Podanie wartości 1 oznacza chęć skorzystania z usługi przesłania za potwierdzeniem odbioru. kategoria gabaryt ostroznie wartosc pobranie Określenie kategorii przesyłki. Dopuszczalne wartości: EKONOMICZNA, PRIORYTETOWA Określa gabaryt przesyłki. Dopuszczalne wartości to: GABARYT_A, GABARYT_B Wartość logiczna określająca korzystanie z usługi ostrożnie. Określenie wartości nadawanej przesyłki. Określenie wartości jest równoznaczna z chęcią skorzystania z usługi przesyłka z określoną wartością. Pole to jest wymagane. Element typu pobranietype. Opisujący pobranie 15
przesylkapoleconakrajowatype typ przeznaczony na przekazywanie danych o usłudze przesyłka polecona krajowa. Klasa ta dziedziczy po klasie przesylkarejestrowanatype. posterestante Znacznik logiczny określający, że adres, który został podany jest adresem poste restante. Domyślnie fałsz. iloscpotwierdzenodbioru Określenie ilości potwierdzeń odbioru. Domyślnie 0. Podanie wartości 1 oznacza chęć skorzystania z usługi przesłania za potwierdzeniem odbioru. kategoria gabaryt Określenie kategorii przesyłki. Dopuszczalne wartości: EKONOMICZNA, PRIORYTETOWA Określa gabaryt przesyłki. Dopuszczalne wartości to: GABARYT_A, GABARYT_B przesylkapoleconazagranicznatype typ przeznaczony na przekazywanie danych o usłudze przesyłka polecona zagraniczna. Klasa ta dziedziczy po klasie przesylkarejestrowanatype. posterestante Znacznik logiczny określający, że adres, który został podany jest adresem poste restante. Domyślnie fałsz. iloscpotwierdzenodbioru Określenie ilości potwierdzeń odbioru. Domyślnie 0. Podanie wartości 1 oznacza chęć skorzystania z usługi przesłania za potwierdzeniem odbioru. kategoria Określenie kategorii przesyłki. Dopuszczalne wartości: EKONOMICZNA, PRIORYTETOWA ekspres Określenie usługi komplementarnej przesylkazagranicznatype typ przeznaczony na przekazywanie danych o usłudze przesyłka polecona zagraniczna. Klasa ta dziedziczy po klasie przesylkanierejestrowanatype. posterestante kategoria ekspres Znacznik logiczny określający, że adres, który został podany jest adresem poste restante. Domyślnie fałsz. Określenie kategorii przesyłki. Dopuszczalne wartości: EKONOMICZNA, PRIORYTETOWA Określenie usługi komplementarnej 16
pocztexkrajowytype typ przeznaczony na przekazywanie danych o usłudze POCZTEX w obrocie krajowym. Klasa ta dziedziczy po klasie przesylkarejestrowanatype. posterestante terminrodzaj kopertafirmowa wartość ostroznie ponadgabaryt uiszczaoplate odleglosc zawartosc pobranie odbiorprzesylkiodnadawcy doreczenie zwrotdokumentow potwierdzenieodbioru Znacznik logiczny określający, że adres, który został podany jest adresem poste restante. Domyślnie fałsz. Określa rodzaj usługi ze względu na termin dostarczenia. Możliwe wartości: MIEJSKI_DO_3H_DO_5KM MIEJSKI_DO_3H_DO_10KM MIEJSKI_DO_3H_DO_15KM MIEJSKI_DO_3H_POWYZEJ_15KM MIEJSKI_DO_4H_DO_10KM MIEJSKI_DO_4H_DO_15KM MIEJSKI_DO_4H_DO_20KM MIEJSKI_DO_4H_DO_30KM MIEJSKI_DO_4H_DO_40KM KRAJOWY BEZPOSREDNI_DO_30KG BEZPOSREDNI_OD_30KG_DO_100KG EKSPRES24 Określenie czy została użyta koperta firmowa Określenie wartości nadawanej przesyłki. Określenie wartości jest równoznacznie ze chęcią skorzystania z usługi przesyłka z określoną wartością. Pole to jest wymagane. Znacznik logiczny określający chęć skorzystania z usługi przesyłka chroniona Określenie czy przesyłka przekracza którykolwiek z wymiarów: 50 cm x 80 cm x 120 cm, ale o wymiarach nie większych niż: 60 cm x 90 cm x 150 cm, nadana w serwisie: Pocztex Kurier Miejski, Pocztex Ekspres 24 Określenie strony uiszczającej opłatę za przesyłkę. Możliwe wartości: NADAWCA, ADRESAT Określenie ilości kilometrów dla pocztexu bezpośredniego Określenie typu zawartości przesyłki Element typu pobranietype. Opisujący pobranie Element typu odbiorprzesylkiodnadawcytype. Opisujący usługi związane z odbiorem przesyłki od nadawcy Element typu doreczenietype. Opisujący usługi związane z doręczniem przesyłki. Element typu zwrotdokumentowtype. Opisujący usługi związane z doręczeniem dokumentów zwrotnych Element typu potwierdzenieodbiorutype. Opisujący usługi związane z potwierdzeniem odebrania przesyłki. 17
potwierdzeniedoreczenia Element typu potwierdzeniedoreczeniatype. Opisujący usługi związane z potwierzeniem doręczenia. odbiorprzesylkiodnadawcytype klasa opisuje usługi związane z odbiorem przesyłki od nadawcy. wsobote wniedzielelubswieto wgodzinachod20do7 Odbiór przesyłki od nadawcy w sobotę Odbiór przesyłki od nadawcy w niedzielę lub święto Odbiór przesyłki od nadawcy w godzinach od 20:00 do 7:00 (w nocy) doreczenietype klasa opisuje usługi związane z doręczeniem przesyłki oczekiwanytermindoreczenia oczekiwanagodzinadoreczenia wsobote w90minut wniedzielelubswieto dorakwlasnych wgodzinachod20do7 Określa, kiedy powinno nastąpić doręczenie (dzień) Określa, kiedy powinno nastąpić doręczenie (godzina) Dopuszczalne wartości: DO 08:00 DO 09:00 DO 12:00 NA 13:00 NA 14:00 NA 15:00 NA 16:00 NA 17:00 NA 18:00 NA 19:00 NA 20:00 Doręczenie w sobotę Doręczenie w czasie do 90 minut. Doręczenie w niedzielę lub święto Doręczenie do rąk własnych Doręczenie w godzinach od 20:00 7:00 (w nocy) zwrotdokumentowtype klasa określający usługi związane ze sposobem dostarczenia dokumentów zwrotnych. rodzajpocztex Element określający zwrot dokumentów przesyłką pocztex. Lista dopuszczalnych wartości. MIEJSKI_DO_3H_DO_5KM MIEJSKI_DO_3H_DO_10KM MIEJSKI_DO_3H_DO_15KM MIEJSKI_DO_3H_POWYZEJ_15KM 18
rodzajlist MIEJSKI_DO_4H_DO_10KM MIEJSKI_DO_4H_DO_15KM MIEJSKI_DO_4H_DO_20KM MIEJSKI_DO_4H_DO_30KM MIEJSKI_DO_4H_DO_40KM KRAJOWY BEZPOSREDNI_DO_30KG BEZPOSREDNI_OD_30KG_DO_100KG EKSPRES24 Element określający zwrot dokumentów przesyłką listową. Należy określić czy lista ma być polecony oraz kategorie. potwierdzenieodbiorutype klasa opisuje usługi związane z potwierdzeniem odbioru ilosc sposob Określa ilość potwierdzeń odbioru Określa sposób przekazania potwierdzenia odbioru. Lista dopuszczalnych wartości: MIEJSKI_DO_3H_DO_5KM MIEJSKI_DO_3H_DO_10KM MIEJSKI_DO_3H_DO_15KM MIEJSKI_DO_3H_POWYZEJ_15KM MIEJSKI_DO_4H_DO_10KM MIEJSKI_DO_4H_DO_15KM MIEJSKI_DO_4H_DO_20KM MIEJSKI_DO_4H_DO_30KM MIEJSKI_DO_4H_DO_40KM EKSPRES24 LIST_ZWYKLY potwierdzeniedoreczeniatype klasa opisuje usługi związane z potwierdzeniem odbioru sposob kontakt Określa sposób przekazania potwierdzenia doręczenia. Lista dopuszczalnych wartości: TELEFON TELEFAX SMS EMAIL Określenie dodatkowych informacji związanych ze sposobem przekazania potwierdzenia doręczenia, np. numer telefonu na który zostanie wysłany SMS. 19
przesylkabiznesowatype typ przeznaczony na przekazywanie danych o usłudze przesyłka biznesowa. Klasa ta dziedziczy po klasie przesylkarejestrowanatype. gabaryt wartosc ostroznie pobranie urzadwydaniaeprzesylki 1 subprzesylka 2 Określa gabaryt przesyłki. Dopuszczalne wartości to: XS, S, M, L, XL, XXL Określenie wartości nadawanej przesyłki. Określenie wartości jest równoznaczna z chęcią skorzystania z usługi przesyłka z określoną wartością. Pole to jest wymagane. Wartość logiczna określająca korzystanie z usługi ostrożnie. Element typu pobranietype. Opisujący pobranie Określenie, w jakim urzędzie zostanie ma zostać odebrana przesyłka. Lista urzędów możliwa do pobrania metodą geturzedywydajaceeprzesylki Elementy typu subprzesylkabiznesowatype (minimalna ilość wystąpień 4) 1 Element jest opcjonalny występuje zamiennie z elementem subprzesylka 2 Element jest opcjonalny występuje zamiennie z elementem urzadwydaniaeprzesylki 20
subprzesylkabiznesowatype typ przeznaczony na przekazywanie dodatkowych danych dla usługi przesyłka biznesowa. Służy do przekazania danych dla w przypadku korzystania z opcji wielopaczokowości o kolejnych paczkach do tego samego adresata. Klasa ta dziedziczy po klasie przesylkatype. numernadania gabaryt wartosc ostroznie pobranie Określa numer nadania przesyłki Określa gabaryt przesyłki. Dopuszczalne wartości to: XS, S, M, L, XL, XXL Określenie wartości nadawanej przesyłki. Określenie wartości jest równoznaczna z chęcią skorzystania z usługi przesyłka z określoną wartością. Pole to jest wymagane. Wartość logiczna określająca korzystanie z usługi ostrożnie. Element typu pobranietype. Opisujący pobranie przesylkabiznesowaplustype typ przeznaczony na przekazywanie dodatkowych danych dla usługi przesyłka biznesowa Plus. Służy do przekazania danych dla w przypadku korzystania z opcji wielopaczokowości o kolejnych paczkach do tego samego adresata. Klasa ta dziedziczy po klasie przesylkatype. posterestante gabaryt wartosc kwotatranzakcji ostroznie Znacznik logiczny określający, że adres, który został podany jest adresem poste restante. Domyślnie fałsz. Określa gabaryt przesyłki. Dopuszczalne wartości to: XS, S, M, L, XL, XXL Określenie wartości nadawanej przesyłki. Określenie wartości jest równoznaczna z chęcią skorzystania z usługi przesyłka z określoną wartością. Pole to jest wymagane. Pole służące określeniu wartości przesyłki, nie skutkuje określeniem przesyłki, jako wartościowej Wartość logiczna określająca korzystanie z usługi ostrożnie. kategoria Określenie kategorii przesyłki. Dopuszczalne wartości: EKONOMICZNA, PRIORYTETOWA iloscpotwierdzenodbioru esposobpowiadomieniaadresata numerprzesylkiklienta iloscdnioczekiwanianawydanie Określenie ilości potwierdzeń odbioru. Domyślnie 0. Podanie wartości 1 oznacza chęć skorzystania z usługi przesłania za potwierdzeniem odbioru. Określenia, w jaki sposób odbiorca ma zostać powiadomiony o tym, że przesyłka jest możliwa do odebrania. Dopuszczalne wartości, SMS, EMAIL Określenie wewnętrznego numeru przesyłki nadanego przez klienta Określa ile dni przesyłka ma oczekiwać w placówce przed podjęciem decyzji o zwrocie 21
oczekiwanytermindoreczenia terminrodzajplus pobranie urzadwydaniaprzesylki subprzesylka datadrugiejprobydoreczenia 3 drugaprobadoreczeniapoliczbiedni 4 Określenie terminu, kiedy przypada oczekiwany termin doręczenia Określenie pory dnia dla oczekiwanego terminu doręczenia Element typu pobranietype. Opisujący pobranie Określa urząd, w którym przesyłka będzie oczekiwać na odebranie Elementy typu subprzesylkabiznesowaplustype Określa, kiedy ma nastąpić druga próba doręczenia Określa interwał czasowy (ilość dni) po jakim ma nastąpić druga próba doręczenia subprzesylkabiznesowaplustype typ przeznaczony na przekazywanie dodatkowych danych dla usługi przesyłka biznesowa Plus. Służy do przekazania danych dla w przypadku korzystania z opcji wielopaczokowości o kolejnych paczkach do tego samego adresata. Klasa ta dziedziczy po klasie przesylkatype. numer nadania gabaryt wartosc ostroznie numerprzesylkiklienta kwotatranzakcji pobranie Określa numer nadania przesyłlki Określa gabaryt przesyłki. Dopuszczalne wartości to: XS, S, M, L, XL, XXL Określenie wartości nadawanej przesyłki. Określenie wartości jest równoznaczna z chęcią skorzystania z usługi przesyłka z określoną wartością. Pole to jest wymagane. Wartość logiczna określająca korzystanie z usługi ostrożnie. Określenie wewnętrznego numeru przesyłki nadanego przez klienta Pole służące określeniu wartości przesyłki, nie skutkuje określeniem przesyłki, jako wartościowej Element typu pobranietype. Opisujący pobranie 3 Występuje zamiennie z elementem drugaprobadoreczniapoliczbiedni 4 Występuje zamiennie z elementem datadrugiejprobydoreczenia 22
placowkapocztowatype typ przeznaczony do udostępniania informacji o placówce pocztowej. Zawiera informacje adresowe o placówce oraz jej atrybuty np. czy jest punktem wydania EPrzesyłki. id prefixnazwy nazwa wojewodztwo powiat miejsce kodpocztowy miejscowosc ulica numer domu numer lokalu nazwawydruk punktwydaniaeprzesylki powiadomieniesms Identyfikator placówki, tzw PNI Określa m.in. placówka jest urzędem czy filią. Określenie pełnej nazwy placówki Określenie województwa, w którym znajduje się placówka (pełna nazwa). Określenie powiatu, w którym znajduje się placówka (pełna nazwa). Określenie miejsca placówki Określa kod pocztowy placówki Określa miejscowość placówki Określa ulice, przy której znajduje się placówka Określa numer budynku, w którym znajduje się placówka Określa numer lokalu, w którym znajduje się placówka Określa nazwę, jaka powinna znaleźć się na wydruku nalepki w przypadku odbioru w punkcie Określa czy placówka jest punktem wydawania EPrzesyłki Określa czy są możliwości techniczne na wysłanie SMS a bezpośrednio z placówki z powiadomieniem dla EPrzesyłki punktwydaniaprzesylkibiznesowejplus Określa czy placówka jest punktem wydawania Przysyłki Bizesowej Plus lokalizacjageograficzna Element typu lokalizacjageograficznatype określający położenie geograficzne placówki pocztowej lokalizacjageograficznatype typ przeznaczony na przekazanie danych o współrzędnych geograficznych. dlugosc szerokosc Element typu wspolrzednageograficznatype określający długość geograficzną Element typu wspolrzednageograficznatype określający szerokość geograficzną wspolrzednageograficznatype typ przeznaczony na przekazanie danych o współrzędnej geograficznej, informacje w dwóch formatach DD i DMS. (http://pl.wikipedia.org/wiki/współrzędne_geograficzne). dec stopien minuta sekunda Współrzędna geograficzna w formacie DD, stopnie dziesiętne. Ilość stopieni współrzędnej geograficznej Ilość minut współrzędnej geograficznej Ilość sekund współrzędnej geograficznej 23
listzwyklytype typ przeznaczony na przekazywanie dodatkowych danych dla usługi listy zwykły nierejestrowany. Klasa ta dziedziczy po klasie przesylkanierejestrowanatype. posterestante gabaryt Znacznik logiczny określający, że adres, który został podany jest adresem poste restante. Domyślnie fałsz. Określa gabaryt przesyłki. Dopuszczalne wartości to: GABARYT_A, GABARYT_B kategoria Określenie kategorii przesyłki. Dopuszczalne wartości: EKONOMICZNA, PRIORYTETOWA egzemplarzbiblioteczny dlaociemnialych Określenie usługi komplementarnej. Określenie usługi komplementarnej. reklamowatype typ przeznaczony na przekazywanie dodatkowych danych dla usługi przesyłki reklamowej. Klasa ta dziedziczy po klasie przesylkanierejestrowanatype. gabaryt Określa gabaryt przesyłki. Dopuszczalne wartości to: GABARYT_A, GABARYT_B 24
FAQ Dodanie certyfikatu serwera testowego do zaufanych Przed rozpoczęciem prac developerskich należy dodać do zaufanych certyfikat dostępnego serwera testowego. Można to zrobić np. za pomocą przeglądarki stron WWW. Przykładowe rozwiązanie dla połączenia aplikacji klienckich do web serwisu z wykorzystaniem MSVS2010 Aby dodać WS należy: 1. Nacisnąć prawy przycisk na Service References i następnie Add Service References. 2. W lewym dolnym rogu nacisnąć guzik Advanced... 3. W lewym dolnym rogu nacisnąć guzik Add Web Reference... 4. W polu URL: wprowadzamy adres HTTP/HTTPS, następnie należy nacisnąć zieloną strzałkę w prawo (zaraz po prawej stronie pola URL), co załaduje nam WSDL. 5. W polu Web reference name wprowadzamy nazwę, pod jaką będzie widoczna klasa WebService. 6. Kod C# tworzenia obiektu WS oraz włączenia autoryzacji. en.elektronicznynadawca ten = new en.elektronicznynadawca(); System.Net.NetworkCredential c = new System.Net.NetworkCredential(); c.username = "user"; c.password = "pass"; System.Net.CredentialCache cc = new System.Net.CredentialCache(); cc.add(new Uri("https://e-nadawca.poczta-polska.pl/websrv/en.wsdl"), "Basic", c); ten.credentials = cc; 7. Po ustawieniu autoryzacji można wykonać Wykonanie metody testowej string test = ten.hello("test"); Przekazanie danych o przesyłce ( na przykładnie paczkiplus) List<en.przesylkaType> przes = new List<en.przesylkaType>() { }; en.paczkapocztowaplustype paczka = new en.paczkapocztowaplustype(); paczka. = 20000; paczka.guid = Guid.NewGuid().ToString(); paczka.adres = new en.adrestype(); paczka.adres.nazwa = "Jan Kowalski"; paczka.adres.ulica = "Woronicza"; paczka.adres.numerdomu = "12"; paczka.adres.miejscowosc = "Warszawa"; paczka.adres.kodpocztowy = "00950"; //ważne paczka.adres.telefon = "501123456"; paczka.kategoria = en.kategoriatype.priorytetowa; paczka.gabaryt = en.gabaryttype.gabaryt_a; przes.add(paczka); //{ inne parametry } en.addshipmentresponseitemtype[] resp = ten.addshipment(przes.toarray()); string test = resp[0].numernadania; 25
Pobranie danych o możliwych urzędach nadania en.urzadnadaniafulltype[] unadania = ten.geturzedynadania(); Wysłanie danych o przesyłkach do urzędu int idenvelope; bool idenvelopespec; en.envelopestatustype envelopestatus; bool envelopestatusspec; en.pakiettype[] pakiet = null; en.errortype[] bladwywolania = ten.sendenvelope(pakiet, unadania[0].urzadnadania,out idenvelope,o ut idenvelopespec, out envelopestatus, out envelopestatusspec); string test = envelopestatus.tostring(); Pobranie informacji o statusie pakietu en.envelopestatustype stat; bool b; string test = ten.getenvelopestatus({idpakietu}, false, out stat, out b)[0].errornumber.tostring(); 26
Przykładowe rozwiązanie z wykorzystaniem PHP. Krok 1 to wygenerowanie biblioteki klas, najlepiej przy pomocy narzędzia wsdl2php (http://sourceforge.net/projects/wsdl2php/ ). Przykładowa zawartość w załączeniu: W liniach 1037,1038 umieszczamy nazwę użytkownika i hasło $options["login"] = "{username}"; $options["password"] = "{password}"; Poniżej przekładowy kod pozwalający dodać jedną przesyłkę, tu na paczka pocztowa include "ElektronicznyNadawca.php"; class Client { // --------------------------------------------------------------------- public function test001() { echo "test 001 paczkapocztowatype <br>"; $E = new ElektronicznyNadawca(); $P = new paczkapocztowatype(); $A = new adrestype(); $tmp = new addshipment(); $A->nazwa = "Jan"; $A->nazwa2 = "Nowak"; $A->ulica = "Cicha"; $A->numerDomu = "1"; $A->numerLokalu = "2"; $A->miejscowosc = "Warszawa"; $A->kodPocztowy = "00002"; $P->adres = $A; $P->iloscPotwierdzenOdbioru = 1; $P->kategoria = kategoriatype::ekonomiczna; $P->gabaryt = gabaryttype::gabaryt_a; $P-> = 1230;// w gramach $P->guid = getguid();// wygenerowany guid $tmp->przesylki[] = $P; $E->addShipment($tmp); // wysłanie zapytania } // --------------------------------------------------------------------- } // ----------------------------------------------------------------------------- function getguid() { mt_srand((double)microtime()*10000); $charid = strtoupper(md5(uniqid(rand(), true))); $retval = substr($charid, 0, 32); return $retval; } // ----------------------------------------------------------------------------- $c = new Client(); $c->test001(); 27