Opis usługi WebService7 v1.9.5 Usługa WebService7 W WebMobile7 Dział Nowych Projektów Warszawa 2011
Opis usługi WebService7 v1.9.5 Spis treści 1 KONTROLA DOKUMENTU... 3 2 SKRÓCONY OPIS USŁUGI... 4 3 METODY... 5 4 METODA LISTNADANIE.... 8 5 METODA WYDRUKETYKIETAEPL... 13 6 METODA WYDRUKETYKIETAZPL... 14 7 METODA WYDRUKLISTPDF... 14 8 METODA NOWYDOKUMENTWYDANIA... 15 9 METODA POBIERZNUMERDOKUMENTULIST... 15 10 METODA POBIERZDOKUMENTWYDANIA... 16 11 METODA STATUSYPRZESYLKI... 17 12 METODA WYDRUKETYKIETAPNG... 18 13 METODA WYDRUKETYKIETAPDF... 19 14 METODA DODAJNADAWCE... 19 15 METODA DODAJODBIORCE... 21 16 METODA EDYTUJKLIENTA... 22 17 METODA SZUKAJKLIENTA... 23 18 METODA LISTNADAJNUMEREXT... 24 19 METODA LISTPOTWIERDZZWROTDOK... 25 20 METODA STATUSYPRZESYLKIV1... 27 21 METODA ZAMOWKURIERA... 29 22 LISTA KODÓW BŁĘDU ZWRACANYCH PRZEZ METODY WYKORZYSTANE W WEBSERVICE7.... 31 23 TESTOWANIE WEBSERVICE7 W WEBMOBILE7... 35 24 DODATEK A: OGRANICZENIA PÓL W METODZIE LISTNADANIE... 36 25 DODATEK B: PREFIXY UŻYWANE DO WALIDACJI TELEFONU KOMÓRKOWEGO... 41 2
1 Kontrola dokumentu Wersja Data Autor Opis zmian 1.8.0 2011-09-05 Piotr Taraszkiewicz Utworzenie dokumentu 1.8.1 2011-12-08 Piotr Taraszkiewicz Uszczegółowienie maksymalnej ilości znaków w polach metody listnadanie: Dodatek B 1.8.2 2011-12-20 Piotr Taraszkiewicz Uszczegółowienie maksymalnej ilości znaków w polach metody listnadanie: Dodatek B 1.9.0 2011-12-30 Piotr Taraszkiewicz Metody: Dodanie nazw nowych metod (nie dostępnych) Dodatek B: Zmiana funkcjonowania pól: - listnadanie zkld - listnadanie formapobrania - listnadanie awizacjatelefoniczna - listnadanie zastrzdornagodz Dodatek B: zmiana opisu pól: - listnadanie potwdostemail - listnadanie potwdostsms 1.9.1 2012-01-01 Piotr Taraszkiewicz Aktualizacja XML w metody listnadanie 1.9.2 10.04.2013 Paweł Fidryk Aktualizacja kodów błędów, dodanie metody wydruketykietazpl 1.9.3 8.08.2013 Paweł Fidryk Opis metod listnadajnrext i listpotwierdzzwrotdok _1.9.4 9.06.2014 Paweł Fidryk Opis metody statusyprzesylkiv1 _1.9.5 24.06.2014 Paweł Fidryk Dodanie metody zamowkuriera
2 Skrócony opis usługi Siódemka S.A. udostępnia usługi WebService7 za pomocą których można komunikować się z aplikacją bez potrzeby logowania się przez przeglądarkę do samej aplikacji. Usługa to pozwala na zbudowanie własnego i dopasowanego do swoich potrzeb oprogramowania do drukowania listów przewozowych. W ramach usługi udostępniamy metody, które odzwierciedlają funkcjonalności aplikacji WebMobile7, dodatkowo wszystkie listy utworzone poprzez WebService7 mogą być drukowane/podglądane/raportowane bezpośrednio z aplikacji WebMobile7. Schemat komunikacji wygląda następująco: 1. Z oprogramowania klienta wysyłane są dane o liście przewozowym (metoda: listnadanie): dane odbiorcy, usługi, dane kontaktowe itp. W odpowiedzi z naszego serwera zostaje przesłany numer listu przewozowego (oraz numery podpaczek jeżeli zostały załączone do komunikatu). 2. Po otrzymaniu numeru, możemy wydrukować etykietę metoda: wydruketykietepl (w odpowiedzi przesłane będą dane gotowe do przesłania na port drukarki) 3. Następnie pozostanie przygotowanie dokumentu wydania za pomocą pozostałych metod. 4. Następnie można zamówić kuriera za pomocą metody zamowkuriera (klienci mający stałe zlecenie podjęcia nie muszą wykonywać tego punktu). Szerszy opis metod i przykładowe komunikaty znajdują się w dalszej części instrukcji. 4
3 Metody Metody dostępne są za pomocą standardowych mechanizmów WebService za pośrednictwem protokołu SOAP. W skład metod udostępnianych przez Siódemkę wchodzą: listnadanie (przygotowanie listu przewozowego) wydruketykietaepl (wydruk etykiety w formacie EPL) wydruketykietazpl (wydruk etykiety w formacie ZPL) wydruketykietapng (wydruk etykiety w formacie PNG) wydruketykietapdf (wydruk etykiety/etykiet w formacie PDF) wydruklistpdf (wydruk listu A4 w formacie PDF) nowydokumentwydania (przygotowanie Dokumentu Wydania Paczek) pobierznumerdokumentulist (pobranie numeru Dokumentu Wydania Paczek) pobierzdokumentwydania (pobranie Dokumentu Wydania Paczek) statusyprzesylki (pobranie statusów przesyłki) dodajodbiorce (Metoda pozwala na dodanie odbiorcy gotówkowego) dodajnadawce (Metoda pozwala na dodanie nadawcy gotówkowego) szukajklienta (Metoda pozwala na wyszukiwanie danych odbiorcy lub nadawcy gotówkowego) listnadajnumerext (Metoda służy do nadania przesyłce numeru zewnętrznego) listpotwierdzzwrotdok (Metoda służy do potwierdzenia otrzymania dokumentów zwrotnych) edytujklienta (Metoda pozwala na edycję danych odbiorcy) statusyprzesylkiv1 (pobieranie statusów według numeru przesyłki lub numeru zewnętrznego) zamowkuriera - ( zamówienie kuriera do wydrukowanych listów przewozowych) bazaplacowek metoda nie aktywna znajdzplacowke metoda nie aktywna Metoda Parametry Wynik Opis listnadanie Dane o liście Numer listy (numer Metoda służy do: - Wygenerowania 5
Metoda Parametry Wynik Opis wydruketykietaepl Numer listu przewozowego wydruketykietazpl Numer listu przewozowego wydruklistpdf Numer listu przewozowego podpaczek opcjonalnie) Kod EPL gotowy do przekazania na port drukarki Kod ZPL gotowy do przekazania na port drukarki List przewozowy (PDF w postaci binarnej) nowydokumentwydania Numery listów Dokument Wydania Paczek (PDF w postaci binarnej) pobierznumerdokumentulist Numer listu Numer dokumentu wydania pobierzdokumentwydania Numer dokumentu wydania statusyprzesylki Numer listu przewozowego wydruketykietapng Numer listu przewozowego Dokument Wydania Paczek (PDF w postaci binarnej) Lista (bądź pojedynczy) statusów danej przesyłki Etykieta adresowa (PNG w postaci binarnej) numeru listu przewozowego - Wygenerowania numerów podpaczek (jeżeli zawarte w wywołaniu) - Obliczenia wag gabarytowych (jeżeli zawarte w wywołaniu) Metoda służy do wygenerowania wydruku etykiety w formacie EPL Metoda służy do wygenerowania wydruku etykiety w formacie ZPL Metoda służy do wygenerowania wydruku listu w formacie A4 Wygenerowanie dokumentu wydania paczek z załączonymi listami podanymi w parametrach wywołania Metoda pobiera numer dokumentu wydania na którym zawarty jest numer listu podany w parametrach Wygenerowanie dokumentu wydania paczek o numerze podanym w parametrach Metoda pobiera całą listę statusów bądź tylko ostatni stan dla danej przesyłki Metoda pozwala na pobranie etykiety (10x10) w postaci 6
Metoda Parametry Wynik Opis wydruketykietapdf Numery listów przewozowych `Etykiety adresowe (PDF w postaci binarnej) dodajnadawce Dane nadawcy Dane nadawcy uzupełnione o jego numer dodajodbiorce Dane odbiorcy Dane odbiorcy uzupełnione o jego numer edytujklienta Nowe dane odbiorcy/ nadawcy szukajklienta listnadajnumerext listpotwierdzzwrotdok Niepełne odbiorcy/nadawcy Numer listu, numer zewnętrzny Numer zewnętrzny, Podpis, Numer kuriera statusyprzesylkiv1 Numer listu przewozowego lub numer zewnętrzny zamowkuriera Numery listów przewozowych, data podjęcia, dane kontaktowe bazaplacowek metoda nie aktywna znajdzplacowke metoda nie aktywna Zaktualizowane dane nadawcy Dane odbiorcy/nadawcy Numer zewnętrzny Numer przesyłki Lista statusów (bądź pojedynczy status) danej przesyłki Nadany numer zlecenia podjęcia metoda aktywna metoda aktywna nie nie obrazka PNG, co umożliwia dalszą obróbkę po stornie klienta. Metoda pozwala na pobranie etykiet (10x10) w podanych w wywołaniu numerach Metoda pozwala na dodanie nadawcy gotówkowego Metoda pozwala na dodanie odbiorcy gotówkowego Metoda pozwala na edycję danych odbiorcy lub /nadawcy gotówkowego Metoda pozwala na wyszukiwanie danych odbiorcy lub nadawcy gotówkowego Metoda służy do nadania przesyłce numeru zewnętrznego Metoda służy do potwierdzenia otrzymania dokumentów zwrotnych Metoda pobiera całą listę statusów bądź tylko ostatni stan dla danej przesyłki Metoda służy do zamówienia kuriera do już wydrukowanych listów. metoda nie aktywna metoda nie aktywna 7
4 Metoda listnadanie. Metoda służy do wprowadzenia do aplikacji WebMobile7 informacji o liście przewozowym, na którym ma zostać wykonana usługa transportowa. Informacją zwrotną jest nadany numer przesyłki lub komunikat błędu. 4.1 Definicja komunikatu.xsd <schema xmlns="http://www.w3.org/2001/xmlschema" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:xsi="http://www.w3.org/2001/xmlschema-instance" xmlns:soap11- enc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:tns="http://app.siodemka.com/mm7ws/type/" targetnamespace="http://app.siodemka.com/mm7ws/type/" elementformdefault="qualified"> <complextype name="kontrahentnadawca"> <sequence> <element name="numer" type="string" nillable="false" /> <element name="nazwisko" type="string" nillable="true" /> <element name="imie" type="string" nillable="true" /> <element name="telkontakt" type="string" nillable="true" /> <element name="emailkontakt" type="string" nillable="true" /> </sequence> </complextype> <complextype name="kontrahentodbiorca"> <sequence> <element name="numer" type="string" nillable="true" /> <element name="nrext" type="string" nillable="true" /> <element name="czyfirma" type="string" nillable="false" /> <element name="nazwa" type="string" nillable="true" /> <element name="nip" type="string" nillable="true" /> <element name="nazwisko" type="string" nillable="true" /> <element name="imie" type="string" nillable="true" /> <element name="kodkraju" type="string" nillable="false" /> <element name="kod" type="string" nillable="false" /> <element name="miasto" type="string" nillable="false" /> <element name="ulica" type="string" nillable="false" /> <element name="nrdom" type="string" nillable="false" /> <element name="nrlokal" type="string" nillable="true" /> <element name="telkontakt" type="string" nillable="true" /> <element name="emailkontakt" type="string" nillable="true" /> </sequence> </complextype> <complextype name="kontrahentplatnik"> <sequence> <element name="numer" type="string" nillable="false" /> <element name="telkontakt" type="string" nillable="true" /> </sequence> </complextype> <complextype name="ubezpieczenie"> <sequence> <element name="kwotaubezpieczenia" type="string" nillable="true" /> <element name="opiszawartosci" type="string" nillable="true" /> </sequence> </complextype> <complextype name="pobranie"> <sequence> <element name="kwotapobrania" type="string" nillable="true" /> 8
<element name="formapobrania" type="string" nillable="true" /> <element name="nrkonta" type="string" nillable="true" /> </sequence> </complextype> <complextype name="uslugi"> <sequence> <element name="nrbezpiecznejkoperty" type="string" nillable="true" /> <element name="zkld" type="string" nillable="true" /> <element name="zd" type="string" nillable="true" /> <element name="ubezpieczenie" type="tns:ubezpieczenie" nillable="true" /> <element name="pobranie" type="tns:pobranie" nillable="true" /> <element name="awizacjatelefoniczna" type="string" nillable="true" /> <element name="potwnademail" type="string" nillable="true" /> <element name="potwdostemail" type="string" nillable="true" /> <element name="potwdostsms" type="string" nillable="true" /> <element name="skladowanie" type="string" nillable="true" /> <element name="nadodbpkp" type="string" nillable="true" /> <element name="odbnadgodziny" type="string" nillable="true" /> <element name="odbwlas" type="string" nillable="true" /> <element name="palnextday" type="string" nillable="true" /> <element name="osobafiz" type="string" nillable="true" /> <element name="market" type="string" nillable="true" /> <element name="zastrzdornagodz" type="string" nillable="true" /> <element name="zastrzdornadzien" type="string" nillable="true" /> </sequence> </complextype> <complextype name="paczki"> <sequence> <element name="paczka" type="tns:paczka" nillable="false" minoccurs="1" maxoccurs="unbounded" /> </sequence> </complextype> <complextype name="paczka"> <sequence> <element name="nrpp" type="string" nillable="true" /> <element name="typ" type="string" nillable="false" /> <element name="waga" type="string" nillable="false" /> <element name="gab1" type="string" nillable="true" /> <element name="gab2" type="string" nillable="true" /> <element name="gab3" type="string" nillable="true" /> <element name="ksztalt" type="string" nillable="false" /> <element name="wagagabaryt" type="string" nillable="true" /> </sequence> </complextype> <complextype name="potwierdzenienadania"> <sequence> <element name="datanadania" type="string" nillable="false" /> <element name="numerkuriera" type="string" nillable="false" /> <element name="podpisnadawcy" type="string" nillable="false" /> </sequence> </complextype> <complextype name="list"> <sequence> <element name="nrprzesylki" type="string" nillable="true" /> <element name="nrext" type="string" nillable="true" /> <element name="mpk" type="string" nillable="true" /> <element name="rodzajprzesylki" type="string" nillable="false" /> <element name="placi" type="string" nillable="false" /> <element name="formaplatnosci" type="string" nillable="false" /> <element name="nadawca" type="tns:kontrahentnadawca" nillable="false" /> <element name="odbiorca" type="tns:kontrahentodbiorca" nillable="false" /> <element name="platnik" type="tns:kontrahentplatnik" nillable="true" /> <element name="uslugi" type="tns:uslugi" nillable="true" /> <element name="paczki" type="tns:paczki" nillable="false" /> <element name="potwierdzenienadania" type="tns:potwierdzenienadania" nillable="false" /> <element name="uwagi" type="string" nillable="true" /> </sequence> </complextype> <complextype name="fault"> <sequence> <element name="bledy" type="tns:bledy" nillable="true" /> </sequence> </complextype> <complextype name="bledy"> <sequence> <element name="blad" type="tns:blad" nillable="true" minoccurs="0" maxoccurs="unbounded" /> </sequence> 9
</complextype> <complextype name="blad"> <sequence> <element name="kod" type="long" nillable="true" /> <element name="opis" type="string" nillable="true" /> </sequence> </complextype> <element name="listnadanieelement"> <complextype> <sequence> <element name="przesylka" type="tns:list" nillable="false" /> <element name="klucz" type="string" nillable="false" /> </sequence> </complextype> </element> <element name="listnadanieresponseelement"> <complextype> <sequence> <element name="result" type="tns:list" nillable="true" /> </sequence> </complextype> </element> <element name="faultelement" type="tns:fault" /> </schema> 4.2 Przykładowy komunikat.xml <soap:envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:body xmlns:ns1="http://app.siodemka.com/mm7ws/type/"> <ns1:listnadanieelement> <ns1:przesylka> <ns1:nrprzesylki></ns1:nrprzesylki> <ns1:nrext></ns1:nrext> <ns1:mpk></ns1:mpk> <ns1:rodzajprzesylki>k</ns1:rodzajprzesylki> <ns1:placi>1</ns1:placi> <ns1:formaplatnosci>p</ns1:formaplatnosci> <ns1:nadawca> <ns1:numer>8140604</ns1:numer> <ns1:nazwisko></ns1:nazwisko> <ns1:imie></ns1:imie> <ns1:telkontakt>506999888</ns1:telkontakt> <ns1:emailkontakt>nadawca@test.com</ns1:emailkontakt> </ns1:nadawca> <ns1:odbiorca> <ns1:numer></ns1:numer> <ns1:nrext></ns1:nrext> <ns1:czyfirma>1</ns1:czyfirma> <ns1:nazwa>tesotwa</ns1:nazwa> <ns1:nip></ns1:nip> <ns1:nazwisko></ns1:nazwisko> <ns1:imie></ns1:imie> <ns1:kodkraju></ns1:kodkraju> <ns1:kod>11-111</ns1:kod> <ns1:miasto>testowo</ns1:miasto> <ns1:ulica>testowa</ns1:ulica> <ns1:nrdom>47</ns1:nrdom> <ns1:nrlokal></ns1:nrlokal> <ns1:telkontakt>506007038</ns1:telkontakt> 10
<ns1:emailkontakt>odbiorca@test.com</ns1:emailkontakt> </ns1:odbiorca> <ns1:platnik> <ns1:numer></ns1:numer> <ns1:telkontakt></ns1:telkontakt> </ns1:platnik> <ns1:uslugi> <ns1:nrbezpiecznejkoperty></ns1:nrbezpiecznejkoperty> <ns1:zkld>2</ns1:zkld> <ns1:zd>0</ns1:zd> <ns1:ubezpieczenie> <ns1:kwotaubezpieczenia>5000</ns1:kwotaubezpieczenia> <ns1:opiszawartosci>kamyki</ns1:opiszawartosci> </ns1:ubezpieczenie> <ns1:pobranie> <ns1:kwotapobrania>100</ns1:kwotapobrania> <ns1:formapobrania>p</ns1:formapobrania> <ns1:nrkonta>73150010701210700799640000</ns1:nrkonta> </ns1:pobranie> <ns1:awizacjatelefoniczna>0</ns1:awizacjatelefoniczna> <ns1:potwnademail>1</ns1:potwnademail> <ns1:potwdostemail>1</ns1:potwdostemail> <ns1:potwdostsms>0</ns1:potwdostsms> <ns1:skladowanie>0</ns1:skladowanie> <ns1:nadodbpkp>0</ns1:nadodbpkp> <ns1:odbnadgodziny>0</ns1:odbnadgodziny> <ns1:odbwlas>0</ns1:odbwlas> <ns1:palnextday>0</ns1:palnextday> <ns1:osobafiz>1</ns1:osobafiz> <ns1:market>0</ns1:market> <ns1:zastrzdornagodz>0</ns1:zastrzdornagodz> <ns1:zastrzdornadzien>b</ns1:zastrzdornadzien> </ns1:uslugi> <ns1:paczki> <ns1:paczka> <ns1:nrpp></ns1:nrpp> <ns1:typ>pc</ns1:typ> <ns1:waga>20</ns1:waga> <ns1:gab1>0</ns1:gab1> <ns1:gab2>0</ns1:gab2> <ns1:gab3>0</ns1:gab3> <ns1:ksztalt>0</ns1:ksztalt> <ns1:wagagabaryt></ns1:wagagabaryt> </ns1:paczka> </ns1:paczki> <ns1:potwierdzenienadania> <ns1:datanadania>2012-01-01 18:00</ns1:dataNadania> <ns1:numerkuriera>233</ns1:numerkuriera> <ns1:podpisnadawcy>kowalski</ns1:podpisnadawcy> </ns1:potwierdzenienadania> <ns1:uwagi></ns1:uwagi> </ns1:przesylka> <ns1:klucz>c33ef81ba362985514ef2b0a0cc8426e</ns1:klucz> </ns1:listnadanieelement> </soap:body> </soap:envelope> Należy pamiętać aby pomiędzy znacznikami: <ns1:datanadania>2009-10-22 18:00</ns1:dataNadania> 11
Znajdowała się aktualna data nadania przesyłki, w przypadku gdy wpiszemy datę wsteczną będzie zwrócony komunikat z błędem. Ograniczenia co do wprowadzanych wartości przedstawione są w dodatku A. 4.3 Uwagi Standardowo obsługiwane są następujące definicje wartości null (pustej) <ns1:zastrzdornadzien xsi:nil="1"/> <ns1:zastrzdornagodz xsi:nil="1"/> lub <ns1:zastrzdornadzien xsi:nil="true"/> <ns1:zastrzdornagodz xsi:nil="true"/> Jeśli implementacja wywoływania metod WebService nie obsługuje takiego wywołania to można użyć poniższych wartości dla podanych usług: wartość pola zastrzdornadzien - może przybierać wartości - S - sobota, N - niedziela, B - brak lub standardowo null (<ns1:zastrzdornadzien xsi:nil="true"/>) wartość pola zastrzdornagodz - może przybierać godzinowe przy czym wartość 0, 00:00, 00 jest traktowana jako brak usługi. Standardowo można użyć "wartości" null (<ns1:zastrzdornagodz xsi:nil="true"/>) 12
4.4 Słowniki wykorzystane w typach komunikatu XML. TN_TYPE_NIE = "0"; TN_TYPE_TAK = "1"; FORMA_PLATNOSCI_TYPE_GOTOWKA = "G"; FORMA_PLATNOSCI_TYPE_PRZELEW = "P"; RODZAJ_PRZESYLKI_TYPE_LOKALNA = "L"; RODZAJ_PRZESYLKI_TYPE_KRAJOWA = "K"; RODZAJ_PRZESYLKI_TYPE_ZAGRANICZNA = "Z"; PLACI_TYPE_NADAWCA = "1"; PLACI_TYPE_ODBIORCA = "2"; PLACI_TYPE_PLATNIK = "3"; FORMA_POBRANIA_TYPE_BANK = "B"; FORMA_POBRANIA_TYPE_PRZEKAZ = "P"; PACZKA_TYP_KOPERTA = "KP"; PACZKA_TYP_PACZKA = "PC"; PACZKA_TYP_PALETA = "PL"; ZASTRZ_DOR_NA_DZIEN_SOBOTA = "S"; ZASTRZ_DOR_NA_DZIEN_NIEDZIELA = "N"; 5 Metoda wydruketykietaepl Metoda służy do pobrania z aplikacji WebMobile7 wydruku etykiet/ty w formacie EPL, na którym/ych ma zostać wykonana usługa transportowa. Informacją zwrotną jest etykieta w formacie EPL lub komunikat błędu. Przykładowy komunikat.xml <soap:envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:body xmlns:ns1="http://app.siodemka.com/mm7ws/type/"> <ns1:wydruketykietaeplelement> <ns1:numery>9130030936916</ns1:numery> <ns1:klucz>c33ef81ba362985514ef2b0a0cc8426e</ns1:klucz> <ns1:separator></ns1:separator> </ns1:wydruketykietaeplelement> </soap:body> </soap:envelope> Gdzie: Numer numery listów które chcemy wydrukować Klucz klucz API do usług WS Separator znak umieszczany pomiędzy numerami listów w celu ich oddzielenia 13
6 Metoda wydruketykietazpl Metoda służy do pobrania z aplikacji WebMobile7 wydruku etykiet/ty w formacie ZPL, na którym/ych ma zostać wykonana usługa transportowa. Informacją zwrotną jest etykieta w formacie EPL lub komunikat błędu. Przykładowy komunikat.xml <soap:envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:body xmlns:ns1="http://app.siodemka.com/mm7ws/type/"> <ns1:wydruketykietazplelement> <ns1:numery>9130030936916</ns1:numery> <ns1:klucz>c33ef81ba362985514ef2b0a0cc8426e</ns1:klucz> <ns1:separator></ns1:separator> <ns1:dpi></ns1:dpi> </ns1:wydruketykietazplelement> </soap:body> </soap:envelope> Gdzie: Numer numery listów które chcemy wydrukować Klucz klucz API do usług WS Separator znak umieszczany pomiędzy numerami listów w celu ich oddzielenia Dpi rozdzielczość drukarki, dopuszczalne wartości to: 200, 300. Domyślna wartość 200. 7 Metoda wydruklistpdf Metoda służy do pobrania z aplikacji WebMobile7 wydruku listu przewozowego w formacie A4, na którym/ych ma zostać wykonana usługa transportowa. Informacją zwrotną jest dokument PDF w postaci binarnej lub komunikat błędu. Przykładowy komunikat.xml <soap:envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:body xmlns:ns1="http://app.siodemka.com/mm7ws/type/"> <ns1:wydruklistpdfelement> <ns1:numer>9130030936916</ns1:numer> <ns1:klucz>c33ef81ba362985514ef2b0a0cc8426e</ns1:klucz> </ns1:wydruklistpdfelement> </soap:body> </soap:envelope> Gdzie: 14
Numer numery listów które chcemy wydrukować Klucz klucz API do usług WS 8 Metoda nowydokumentwydania Metoda służy do wygenerowania w aplikacji WebMobile7 dokumentu wydania na podstawie podanego zakresu listów przewozowych oraz jego pobrania. Informacją zwrotną dane binarne (base64binary) z dokumentem wydania. Przykładowy komunikat.xml <soap:envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:body xmlns:ns1="http://app.siodemka.com/mm7ws/type/"> <ns1:nowydokumentwydaniaelement> <ns1:kurier>233</ns1:kurier> <ns1:numery>9130030936916</ns1:numery> <ns1:klucz>c33ef81ba362985514ef2b0a0cc8426e</ns1:klucz> <ns1:separator></ns1:separator> </ns1:nowydokumentwydaniaelement> </soap:body> </soap:envelope> gdzie: kurier - nr kuriera numery - wykaz numerów listów do załączenia na dokumencie wydania klucz klucz API do usługi WS separator - separator numerów listów 9 Metoda pobierznumerdokumentulist Metoda ta służy do pobrania numeru dokumentu wydania paczek. Jako parametr przekazujemy numer przesyłki która załączona jest w pożądanym dokumencie Przykładowy komunikat.xml <soap:envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:body xmlns:ns1="http://app.siodemka.com/mm7ws/type/"> <ns1:pobierznumerdokumentulistelement> <ns1:numerlistu>9130030936916</ns1:numerlistu> <ns1:klucz>c33ef81ba362985514ef2b0a0cc8426e</ns1:klucz> </ns1:pobierznumerdokumentulistelement> </soap:body> </soap:envelope> Gdzie: numerlistu numer listu który jest zawarty do dokumentu 15
klucz klucz API 10 Metoda pobierzdokumentwydania Metoda służy do pobrania wygenerowanego wcześniej w aplikacji WebMobile7 dokumentu wydania na podstawie numeru dokumentu wydania. Informacją zwrotną dane binarne (base64binary) z dokumentem wydania. Przykładowy komunikat.xml <soap:envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:body xmlns:ns1="http://app.siodemka.com/mm7ws/type/"> <ns1:pobierzdokumentwydaniaelement> <ns1:numerdokumentu>2010-06-28/813703</ns1:numerdokumentu> <ns1:klucz>c33ef81ba362985514ef2b0a0cc8426e</ns1:klucz> </ns1:pobierzdokumentwydaniaelement> </soap:body> </soap:envelope> gdzie: numerdokumentu numer dokumentu (taki jak na PDF-ie) klucz klucz do usługi WS 16
11 Metoda statusyprzesylki Metoda umożliwia śledzenie stanu (statusu) przesyłki z poziomu usług WebService7. Dzięki tej metodzie jesteśmy w stanie pobrać całą listę statusów bądź najbardziej aktualny (ostatni) sterowanie parametrem wywołania. Dzięki tej metodzie mogą Państwo sprawdzić statusy przesyłek w Państwa aplikacjach bez wykonywania dodatkowych czynności. Przykładowy komunikat.xml <soap:envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:body xmlns:ns1="http://app.siodemka.com/mm7ws/type/"> <ns1:statusyprzesylkielement> <ns1:numerlistu>9130030936916</ns1:numerlistu> <ns1:czyostatni>0</ns1:czyostatni> <ns1:klucz>c33ef81ba362985514ef2b0a0cc8426e</ns1:klucz> </ns1:statusyprzesylkielement> </soap:body> </soap:envelope> gdzie: numerlistu numer listu przewozowego czyostatni parametr pozwalający określić czy zwracana będzie cała lista statusów (0) czy tylko ostatni najbardziej aktualny (1) klucz klucz WebAPI Przykładowa odpowiedź.xml <env:envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/xmlschema" xmlns:xsi="http://www.w3.org/2001/xmlschema-instance" xmlns:ns0="http://app.siodemka.com/mm7ws/type/"> <env:body> <ns0:statusyprzesylkiresponseelement> <ns0:result> <ns0:skrot>ds</ns0:skrot> <ns0:oddsymbol>ldz</ns0:oddsymbol> <ns0:nrp>4130046283160</ns0:nrp> <ns0:datas>2011-08-31 11:10</ns0:dataS> <ns0:opis>przesyłka doręczona (DS)</ns0:opis> </ns0:result>... <ns0:result> <ns0:skrot>wk</ns0:skrot> <ns0:oddsymbol>ldz</ns0:oddsymbol> <ns0:nrp>4130046283160</ns0:nrp> <ns0:datas>2011-08-31 06:25</ns0:dataS> <ns0:opis>wydanie kurierowi doręczającemu (WK)</ns0:opis> 17
</ns0:result> </ns0:statusyprzesylkiresponseelement> </env:body> </env:envelope> Za pomocą tej metody możemy uzyskać następujące statusy: Symbol statusu (<ns0:skrot>) PK WK WE ZK OW PP UD NP AN ZN AV NA BA OP DS Opis statusu (<ns0:opis>) Przyjęcie od kuriera (PK) Wydanie kurierowi doręczającemu (WK) Przyjęcie do magazynu doręczającego (WE) Zwrot przez kuriera (ZK) Odbiór Własny Przemanifestowanie Umówione Doręczenie Nieudana próba doręczenia Przesyłka Anulowana Zwrot do nadawcy (ZN) Przesyłka awizowana (AV) Nie znaleziono adresu (NA) Błędny Adres (BA) Odbiorca odmówił przyjęcia (OP) Przesyłka doręczona (DS) 12 Metoda wydruketykietapng Metoda ta pozwala na pobranie etykiety adresowej (10 cm x 10 cm) w postaci obrazka (format PNG). Metoda ta udostępniania jest na specjalne życzenie klienta i w porozumieniu z działem IT Siódemki z powodu niebezpieczeństwa które niesie za sobą przeskalowanie pobranego obrazka. 18
Przykładowy komunikat.xml <soap:envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:body xmlns:ns1="http://app.siodemka.com/mm7ws/type/"> <ns1:wydruketykietapngelement> <ns1:numer>9130030936916</ns1:numer> <ns1:klucz>c33ef81ba362985514ef2b0a0cc8426e</ns1:klucz> </ns1:wydruketykietapngelement> </soap:body> </soap:envelope> gdzie: numer numer listu przewozowego klucz klucz WebAPI 13 Metoda WydrukEtykietaPdf Metoda ta pozwala na pobranie etykiety adresowej (10 cm x 10 cm) w postaci dokumentu binarnego PDF Przykładowy komunikat.xml <soap:envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:body xmlns:ns1="http://app.siodemka.com/mm7ws/type/"> <ns1:wydruketykietapdfelement> <ns1:numery>9130030936916</ns1:numery> <ns1:klucz>c33ef81ba362985514ef2b0a0cc8426e</ns1:klucz> <ns1:separator>;</ns1:separator> </ns1:wydruketykietapdfelement> </soap:body> </soap:envelope> gdzie: numer numer listu przewozowego klucz klucz WebAPI separator znak oddzielający numery listów 14 Metoda dodajnadawce Metoda służy do dodania do bazy danych klientów nadawcy gotówkowego. Dane wejściowe są przekazywane w postaci struktury, która jest także wykorzystywana do dodawania odbiorcy, edycji klienta i wyszukiwania klienta. Zwracana jest analogiczna struktura z uzupełnionym 19
numerem klienta. Struktura komunikatu (patrz typ danych Kontrahent w WSDL) z danymi klienta przedstawia się następująco: <ns1:ulica> - dane adresowe (ulica) <ns1:emailkontakt> - e-mail kontaktowy <ns1:imie> - imię (w przypadku osób fizycznych) <ns1:numer> - numer klienta <ns1:nazwisko> - nazwisko (w przypadku osób fizycznych) <ns1:nrdom> - dane adresowe (nr domu) <ns1:nrlokal> - dane adresowe (nr lokalu) <ns1:kod> - dane adresowe (kod pocztowy) <ns1:nrext> - numer zewnętrzny numer nadawany przez klienta do łatwego wyszukiwania <ns1:nazwa> - nazwa klienta (nazwa firmy) <ns1:telkontakt> - telefon kontaktowy <ns1:nip> - nr NIP (bez kresek) <ns1:czyfirma> - znacznik czy firma (wartości 1 lub T oznacza firmę) <ns1:kodkraju> - dwuliterowy kod kraju domyślnie PL <ns1:miasto> - dane adresowe (miasto) <ns1:fax> - numer faksu <ns1:telefonkom> - numer telefonu komórkowego <ns1:czynadawca> - znacznik czy klient jest nadawcą (1 lub T) l UWAGA!!! Użytkownik musi mieć nadane przez firmę Siódemka S. A. uprawnienia do używania tej metody. Uwagi do funkcjonowania metody: 1. Metoda dodaje TYLKO nadawcę gotówkowego (nie ma znaczenia ustawienia pola czy nadawca 2. Po zapisie zwracane są dane klienta z uzupełnionym numerem klienta 3. W przypadku osób fizycznych pola imię i nazwisko są zamieniane na pełną nazwę klienta (w komunikacie zwrotnym pole nazwa jest uzupełnione, pola imię i nazwisko są wyczyszczone) Przykładowy komunikat.xml <soap:envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:body xmlns:ns1="http://app.siodemka.com/mm7ws/type/"> <ns1:dodajnadawceelement > <ns1:daneklienta> <ns1:ulica>nowoprojektowana</ns1:ulica> <ns1:emailkontakt>test@nowy.pl</ns1:emailkontakt> <ns1:imie></ns1:imie> <ns1:numer>a</ns1:numer> <ns1:nazwisko></ns1:nazwisko> <ns1:nrdom>6</ns1:nrdom> <ns1:nrlokal>7a</ns1:nrlokal> <ns1:kod>00-950</ns1:kod> 20
<ns1:nrext>gamma</ns1:nrext> <ns1:nazwa>gamma instytut</ns1:nazwa> <ns1:telkontakt>123-456-789</ns1:telkontakt> <ns1:nip>955-125-12-86</ns1:nip> <ns1:czyfirma>1</ns1:czyfirma> <ns1:kodkraju>pl</ns1:kodkraju> <ns1:miasto>warszawa</ns1:miasto> <ns1:fax></ns1:fax> <ns1:telefonkom>601123456</ns1:telefonkom> <ns1:czynadawca>1</ns1:czynadawca> </ns1:daneklienta> <ns1:klucz>688ebf5d509e5fe310fcc304e0570425</ns1:klucz> </ns1: dodajnadawceelement> </soap:body> </soap:envelope> Gdzie: daneklienta struktura z danymi klienta Klucz klucz API do usług WS 15 Metoda dodajodbiorce Metoda służy do dodania do bazy danych klientów odbiorcy gotówkowego. Dane wejściowe są przekazywane analogicznie jak opisano to powyżej w przypadku metody dodajna dawce. Zwracana jest analogiczna struktura z uzupełnionym numerem klienta. Uwagi do funkcjonowania metody: 1. Metoda dodaje TYLKO odbiorcę gotówkowego (nie ma znaczenia ustawienia pola czy nadawca 2. Po zapisie zwracane są dane klienta z uzupełnionym numerem klienta 3. W przypadku osób fizycznych pola imię i nazwisko są zamieniane na pełną nazwę klienta (w komunikacie zwrotnym pole nazwa jest uzupełnione, pola imię i nazwisko są wyczyszczone) Przykładowy komunikat.xml <soap:envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:body xmlns:ns1="http://app.siodemka.com/mm7ws/type/"> <ns1: dodajodbiorceelement > <ns1:daneklienta> <ns1:ulica>nowoprojektowana</ns1:ulica> <ns1:emailkontakt>test@nowy.pl</ns1:emailkontakt> <ns1:imie></ns1:imie> <ns1:numer>a</ns1:numer> <ns1:nazwisko></ns1:nazwisko> <ns1:nrdom>6</ns1:nrdom> <ns1:nrlokal>7a</ns1:nrlokal> <ns1:kod>00-950</ns1:kod> <ns1:nrext>gamma</ns1:nrext> <ns1:nazwa>gamma instytut</ns1:nazwa> 21