GlobKurier API - Globkurier.pl
Transkrypt
GlobKurier API - Globkurier.pl
Dokumentacja GlobKurier API Wersja: 1.12 Dokumentacja GlobKurier API Autorzy dokumentu: Tomasz Solik / Paweł Woszczyk Dane kontaktowe: [email protected] +48 032 700 34 30 Wersja: 112 Ostatnia zmiana: 21.11.2016 1. Wstęp 2. Metody 2.1 Pobieranie informacji o koncie 2.2 Rejestracja 2.3 Składanie zamówienia 2.3.1 Zamówienia GlobBox 2.3.2 Zamówienia terminalowe 2.4 Zamówienia klienta (historia) 2.5 Pobieranie etykiet 2.6 Lista usług 2.7 Lista krajów 2.8 Lista punktów GlobBox 2.9 Lista terminali 2.10 Lista celów przesyłki 2.11 Protokół zbiorczy 3. Podsumowanie GlobKurier.pl 1/33 Dokumentacja GlobKurier API Wersja: 1.12 1. Wstęp Api wykorzystuje wzorzec restowy, dane przesyłane muszą być w postaci tablicy POST. Klucze muszą być zgodne z dokumentacją. W odpowiedzi serwer zwraca obiekt JSON, w surowej formie. Lokalizacja: Wersja testowa: http://www.test.webservices.globkurier.pl Wersja produkcyjna: https://www.webservices.globkurier.pl Dane testowego użytkownika: Login: [email protected] Hasło: e10adc3949ba59abbe56e057f20f883e Klucz api: nLx1f-km1WN-bqQlW-zF6WE Api daje możliwość: - Pobierania informacji o koncie, - Rejestracji nowego konta, - Składania zamówienia, - Pobierania informacji o punktach nadań Większość wywołań metod jest autoryzowana nazwą użytkownika, hasłem oraz kluczem api. Wywołania są rejestrowane przez serwer. Dostęp do usługi jest nadawany poprzez obsługę globkurier.pl. 2. Metody 2.1 Pobieranie informacji o koncie URL: http://www.test.webservices.globkurier.pl/services/login/ Zwraca szczegółowe informacje na temat konta użytkownika, na podstawie jego loginu, hasła i klucza API. Parametry Pole Opis Typ Wymagany LOGIN Login użytkownika (email, na jaki string tak GlobKurier.pl 2/33 Dokumentacja GlobKurier API Wersja: 1.12 zarejestrowano konto w systemie globkurier.pl) PASSWORD Hasło zakodowane funkcją skrótu MD5 string tak APIKEY Klucz API string tak Dane wyjściowe Pole Typ Opis status bool true - brak błędu false - błąd error string informacja o błędzie userParams obj collection zwracana jest kolekcja obiektów Pole Typ Opis get_data bool Czy załadowano poprawnie dane idklient int idg int id grupy rabatowej klienta aktywny int 0 - nieaktywny 1 - aktywny zablokowany int 0 - odblokowany 1 - zablokowany rodzaj string/enum firma / osoba numer_klienta int imie string nazwisko string telefon string kraj string adres string userParams GlobKurier.pl ulica 3/33 Dokumentacja GlobKurier API Wersja: 1.12 adres_dom string adres_lokal string kod string miasto string mail string firma string nip string regon string nrkonta string konto_nazwa string konto_adres string konto_adres_cd string faktura_papierowa int zarejestrowany datetime (YYYY-mm-dd hh:mm:ss) zalogowany datetime (YYYY-mm-dd hh:mm:ss) 0 - nie 1 - tak platnosc_odroczona int platnosc_odroczona int _dni platnik_netto int 0 - nie 1 - tak api_key_expiration_t date (YYYY-mm-dd) ime prepaid_am float stan konta prepaid arrear_am float stan zaległości GlobKurier.pl 4/33 Dokumentacja GlobKurier API Wersja: 1.12 Zwracane błędy Komunikat Opis Brak danych. Brak wymaganych pól w POST Brak parametru LOGIN. Proszę uzupełnić login Brak parametru PASSWORD. Proszę uzupełnić hasło Brak parametru APIKEY. Proszę uzupełnić apikey Nieprawidłowy login lub hasło. Nieprawidłowy klucz api. Konto nieaktywne. Konto zablokowane. 2.2 Rejestracja URL: http://www.test.webservices.globkurier.pl/services/register/ Rejestruje nowe konto użytkownika w serwisie globkurier.pl. Parametry Pole Opis Typ Wymagany EMAIL Login(email) string tak PASSWORD Hasło string tak TYPE Typ konta: 1 - firmowy 2 - prywatny int tak COMPANY string nie NIP int nie REGON int nie NAME string tak SURNAME string tak GlobKurier.pl 5/33 Dokumentacja GlobKurier API Wersja: 1.12 STREET string tak HOUSE string tak LOCAL string nie CITY string tak ZIP string tak PHONE string tak Dane wyjściowe Pole Typ Opis status bool true - brak błędu false - błąd error string informacja o błędzie Zwracane błędy Komunikat Opis Brak danych. Brak wymaganych pól w POST Brak parametu EMAIL. Proszę uzupełnić email Brak parametu PASSWORD. Proszę uzupełnić hasło Brak parametu TYPE. Proszę uzupełnić typ konta Brak parametu COMPANY. Proszę uzupełnić nazwę firmy Brak parametu NIP. Proszę uzupełnić NIP Brak parametu NAME. Proszę uzupełnić imię Brak parametu SURNAME. Proszę uzupełnić nazwisko Brak parametu STREET. Proszę uzupełnić ulicę Brak parametu HOUSE. Proszę uzupełnić numer domu Brak parametu CITY. Proszę uzupełnić miasto Brak parametu PHONE. Proszę uzupełnić telefon kontaktowy GlobKurier.pl 6/33 Dokumentacja GlobKurier API Wersja: 1.12 Nieprawidłowy adres email. Adres email został już zarejestrowany w serwisie. NIP został już zarejestrowany w serwisie. Błąd w wysyłce. Proszę spróbować ponowić próbę za kilka minut. Błąd spowodowany ewentualną chwilową przerwą w wysyłce wiadomości email po stronie naszego serwera. 2.3 Składanie zamówienia URL: http://www.test.webservices.globkurier.pl/services/order/ Dodanie nowego zamówienia do dalszego procesowania w systemie globkurier.pl. Po prawidłowej rejestracji wysyłany jest email potwierdzający złożenie zamówienia. Parametry Pole Opis Typ Wymagany DATA XML z danymi zamówienia string tak Przykładowy plik wejściowy <?xml version="1.0" encoding="UTF-8" standalone="no"?> <globkurier> <login>[email protected]</login> <password>e10adc3949ba59abbe56e057f20f883e</password> <apikey>nLx1f-km1WN-bqQlW-zF6WE</apikey> <order_method>SAVE</order_method> <order_source>API</order_source> <orders> <order> <sent_date>2015-07-15</sent_date> <base_service>S704</base_service> <additional_services> <additional_service>A707</additional_service> <additional_service>A709</additional_service> <additional_service>A716</additional_service> </additional_services> <cod_amount>11000</cod_amount> <cod_account>08103000190109853300016905</cod_account> GlobKurier.pl 7/33 Dokumentacja GlobKurier API Wersja: 1.12 <insurance_amount>50000</insurance_amount> <declared_value></declared_value> <payment_type>T</payment_type> <content>Klapki Kubota</content> <length>15</length> <width>35</width> <height>28</height> <weight>2</weight> <number_of_parcels>1</number_of_parcels> <comments></comments> <sender> <name>Andrzej Kowalski</name> <street>Dworcowa</street> <house_number>12</house_number> <apartment_number></apartment_number> <postal_code>40-226</postal_code> <city>Warszawa</city> <country>PL</country> <contact_person>Andrzej Kowalski</contact_person> <phone>1234567890</phone> <email>[email protected]</email> </sender> <receiver> <name>Tomasz Nowak</name> <street>Poziomkowa</street> <house_number>1</house_number> <apartment_number>1</apartment_number> <postal_code>30-259</postal_code> <city>Katowice</city> <country>PL</country> <contact_person>Tomasz Nowak</contact_person> <phone>1234567890</phone> <email>[email protected]</email> </receiver> </order> </orders> </globkurier> GlobKurier.pl 8/33 Dokumentacja GlobKurier API Wersja: 1.12 Znaczniki XML Znacznik Opis Typ Wymagany globkurier Węzeł rozpoczynający login Login string tak password Hasło zakodowane algorytmem MD5 string tak apikey Klucz API - weryfikowany string jest cały klucz, znaki „-” między jego partiami są ważne tak order_method Obecnie dostępna jest tylko akcja: “SAVE” tak order_source Identyfikator źródła string zlecenia. W celu lepszego wsparcia można zgłosić chęć autoryzowania własnego identyfikatora źródła. Nie, domyślnie przypisywanym identyfikatorem jest API shipmentPurpose Cel Wysyłki – dostępne wartości można pobrać przy pomocy metody purposes Tak, jeżeli został wybrany produkt przewoźnika Fedex International orders Węzły podrzędne order Węzły podrzędne custom_lp Węzły podrzędne sent_date Data nadania przesyłki nie przekazując wartości wygenerowany zostanie najbliższy możliwy termin. W razie opóźnień w dokonaniu płatności data zostanie przesunięta na najbliższą możliwą. GlobKurier.pl string string tak, jeżeli wybrany dodatek “Indywidualne dane na liście przewozowym” data (YYYYmm-dd HH:ii:ss) lub (YYYYmm-dd) wówczas wybrany zostanie nie 9/33 Dokumentacja GlobKurier API Wersja: 1.12 najbliższy możliwy przedział godzin base_service Usługa podstawowa additional_services Węzły podrzędne - usługi dodatkowe do usługi podstawowej additional_service Usługa dodatkowa skorzystanie z usług dodatkowych wiąże się z przekazaniem dodatkowych pól lub dobrania innych usług dodatkowych np. usługa pobrania lub nko wymusza dobranie ubezpieczenia, nko wymusza sposób płatności string nie cod_amount Kwota pobrania [PLN] float tak, w przypadku wybrania usługi dodatkowej pobranie cod_account Numer konta do pobrania string - zwroty pobrań tylko na polskie konta bankowe tak, w przypadku wybrania usługi dodatkowej pobranie insurance_amount Kwota ubezpieczenia [PLN] float tak, w przypadku wybrania usługi dodatkowej ubezpieczenie declared_value Wartość deklarowana [PLN] float tak, jeśli przesyłka międzynarodowa poza obszar Unii Europejskiej [PLN] payment_type T - przelew bankowy O - płatność online P - płatność prepaid D - płatność odroczona COD - na koszt odbiorcy string tak content zawartość string tak length długość [cm] int tak GlobKurier.pl string tak nie 10/33 Dokumentacja GlobKurier API Wersja: 1.12 width szerokość [cm] int tak height wysokość [cm] int tak weight waga [kg] float tak number_of_parcels ilość paczek/palet w przesyłce, max 10 int tak comments komentarz, jeżeli uzupełniony procesowanie będzie wstrzymane do czasu ręcznej weryfikacji przez Biuro Obsługi Klienta string nie sender Dane nadawcze name Nazwa nadawcy string tak street Ulica string tak house_number Numer domu string tak apartment_number Numer mieszkania string nie postal_code Kod pocztowy string tak city Miejscowość string tak country Kod kraju, lista dostępnych kodów zwracana jest metodą opisaną w punkcie 2.7 Lista krajów string tak, dla zleceń międzynarodowych. Domyślnie przyjmuje wartość „PL” contact_person Imię i nazwisko osoby kontaktowej string tak, jeśli nadanie odbywa się w terminalu. Umożliwia to w przypadku zwrotu przesyłki jej odbiór w punkcie po okazaniu dowodu tożsamości phone Numer telefonu string tak, jeśli chcemy skorzystać z usług dodatkowych typu powiadomienia SMS należy podawać numer komórkowy email Adres e-mail string tak GlobKurier.pl 11/33 Dokumentacja GlobKurier API Wersja: 1.12 receiver Dane odbiorcze name Nazwa odbiorcy string tak street Ulica string tak house_number Numer domu string tak apartment_number Numer mieszkania string nie postal_code Kod pocztowy string tak city Miejscowość string tak country Kod kraju, lista dostępnych kodów zwracana jest metodą opisaną w punkcie 2.7 Lista krajów string tak, dla zleceń międzynarodowych. Domyślnie przyjmuje wartość „PL” contact_person Imię i nazwisko osoby kontaktowej string tak, w przypadku skorzystania z usługi do rąk własnych phone Numer telefonu string tak, jeśli chcemy skorzystać z usług dodatkowych typu powiadomienia SMS należy podawać numer komórkowy email Adres e-mail string tak Dane wyjściowe Pole Typ Opis status bool true - brak błędu false - błąd error string informacja o błędzie params obj collection zwracana jest kolekcja obiektów Pole Typ Opis nrgk string numer zamówienia globkurier params GlobKurier.pl 12/33 Dokumentacja GlobKurier API Wersja: 1.12 Zwracane błędy Komunikat Opis Brak danych. Brak wymaganych pól w POST Nieprawidłowy login lub hasło. Nieprawidłowe dane. Brak wybranej usługi. Brak płatności. Proszę podać poprawną datę odbioru przesyłki. Nie posiadasz wystarczająco środków na koncie prepaid. Błędny typ płatności, proszę wybrać inny. Nie mogę załadować danych, proszę spróbować ponownie. Nie mogę zaktualizować danych, proszę spróbować ponownie. Błędna kwota ubezpieczenia. Błędna kwota pobrania. Błędny numer konta. 2.3.1 Zamówienia GlobBox Uwaga: dla produktów globbox można od wersji Api 1.7 wykorzystać metodę opisaną w punkcie 2.3.2. URL: http://www.test.webservices.globkurier.pl/services/order/ Dodanie nowego zamówienia z opcją punktu GlobBox do dalszego procesowania w systemie globkurier.pl. Po prawidłowej rejestracji wysyłany jest email potwierdzający złożenie zamówienia. Do struktury zamówienia opisanego w pkt. 2.3 należy dołączyć dodatkowe węzły z parametrami punktów opisane w tabeli. GlobKurier.pl 13/33 Dokumentacja GlobKurier API Wersja: 1.12 Przykładowy plik wejściowy <?xml version="1.0" encoding="UTF-8" standalone="no"?> <globkurier> <login>[email protected]</login> <password>e10adc3949ba59abbe56e057f20f883e</password> <apikey>nLx1f-km1WN-bqQlW-zF6WE</apikey> <order_method>SAVE</order_method> <order_source>API</order_source> <orders> <order> <sent_date>2015-07-26</sent_date> <base_service>S2201</base_service> <additional_services></additional_services> <cod_amount></cod_amount> <cod_account></cod_account> <insurance_amount></insurance_amount> <declared_value></declared_value> <payment_type>T</payment_type> <content>Klapki Kubota</content> <length>12</length> <width>12</width> <height>3</height> <weight>2</weight> <number_of_parcels>1</number_of_parcels> <comments></comments> <sender> <name>Andrzej Kowalski</name> <street>Dworcowa</street> <house_number>12</house_number> <apartment_number></apartment_number> <postal_code>05-090</postal_code> <city>Warszawa</city> <country>PL</country> <contact_person>Andrzej Kowalski</contact_person> <phone>1234567890</phone> <email>[email protected]</email> </sender> <receiver> <name>Tomasz Nowak</name> <street>Poziomkowa</street> <house_number>1</house_number> GlobKurier.pl 14/33 Dokumentacja GlobKurier API Wersja: 1.12 <apartment_number>1</apartment_number> <postal_code>30-259</postal_code> <city>Katowice</city> <country>PL</country> <contact_person>Tomasz Nowak</contact_person> <phone>1234567890</phone> <email>[email protected]</email> </receiver> <globbox> <sender_type>osoba</sender_type> <receiver_type>partner</receiver_type> <receiver_id_point>143</receiver_id_point> </globbox> </order> </orders> </globkurier> Znaczniki XML Znacznik Opis globbox Węzły podrzędne tak, jeżeli wybrana usługa podstawowa GlobBox sender_type typ nadawcy, parametry: string osoba - nadawcą jest osoba zadeklarowana w sekcji sender partner - nadawcą jest punkt GlobBox, dane pozyskane po nadaniu paczki w punkcie tak receiver_type typ odbiorcy, parametry: osoba - odbiorcą jest osoba zadeklarowana w sekcji receiver partner - odbiorcą jest punkt GlobBox konieczne jest podanie id punktu w receiver_id_point tak receiver_id_point Id punktu odbiorczego, id int uzyskujemy dzięki metodzie opisanej w punkcie 2.8 Lista punktów Globbox GlobKurier.pl Typ string Wymagany tak, jeżeli wybrano receiver_type: partner 15/33 Dokumentacja GlobKurier API Wersja: 1.12 2.3.2 Zamówienia terminalowe URL: http://www.test.webservices.globkurier.pl/services/order/ Do niektórych typów usług można zamiast kuriera zamawianego pod dany adres skorzystać z punktów nadania lub odbioru. Wówczas klient zobowiązuje się osobiście dostarczyć lub odebrać przesyłkę ze wskazanego punktu. Dla niektórych produktów usługa jest alternatywą np. K-EX, Poczta-Polska Kurier48 a dla innych usługą podstawową np. inPost, Paczka w Ruchu. Nie każdy produkt dostępny jest też w parze nadanie / doręczenie, możliwe są także oddzielne warianty. Dla produktów, gdzie usługa jest usługą podstawową wymagane jest przesłanie informacji o punktach w celu wygenerowania zlecenia, nie przekazanie tych informacji skutkuje błędem. Dla innych produktów z alternatywną usługą przesłanie informacji o punktach spowoduje wygenerowanie odpowiedniego zlecenia. Do struktury opisanej w punkcie 2.3 należy dołączyć dodatkowe węzły. Przykładowy plik wejściowy <?xml version="1.0" encoding="UTF-8" standalone="no"?> <globkurier> <login>[email protected]</login> <password>e10adc3949ba59abbe56e057f20f883e</password> <apikey>nLx1f-km1WN-bqQlW-zF6WE</apikey> <order_method>SAVE</order_method> <order_source>API</order_source> <orders> <order> <sent_date>2015-07-23</sent_date> <base_service>PKA</base_service> <cod_amount /> <cod_account /> <insurance_amount /> <declared_value /> <payment_type>T</payment_type> <content>Klapki Kubota</content> <length>8</length> <width>38</width> <height>64</height> <weight>25</weight> <number_of_parcels>1</number_of_parcels> <comments></comments> GlobKurier.pl 16/33 Dokumentacja GlobKurier API Wersja: 1.12 <sender> <name>Andrzej Kowalski</name> <street>Dworcowa</street> <house_number>12</house_number> <apartment_number></apartment_number> <postal_code>40-226</postal_code> <city>Katowice</city> <country>PL</country> <contact_person>Andrzej Kowalski</contact_person> <phone>1234567890</phone> <email>[email protected]</email> <terminal>BRZ01ML</terminal> </sender> <receiver> <name>Tomasz Nowak</name> <street>Mszczonowska</street> <house_number>3</house_number> <apartment_number /> <postal_code>05-090</postal_code> <city>Warszawa Janki</city> <country>PL</country> <contact_person>Tomasz Nowak</contact_person> <phone>1234567890</phone> <email>[email protected]</email> <terminal>JAS289</terminal> </receiver> </order> </orders> </globkurier> Znaczniki XML Znacznik Opis sender Dane nadawcy terminal Identyfikator terminalu nadawczego pobrany metodą opisaną w pkt. 2.9Lista terminali receiver Dane odbiorcy GlobKurier.pl Typ Wymagany string tak, jeśli w odpowiedzi z listą terminali pole isSenderMandatory ustawione jest na true 17/33 Dokumentacja GlobKurier API Wersja: 1.12 terminal Identyfikator terminalu doręczenia string pobrany metodą opisaną w pkt. 2.9 Lista terminali tak, jeśli w odpowiedzi z listą terminali pole isReceiverMandatory ustawione jest na true 2.4 Zamówienia klienta (historia) URL: http://www.test.webservices.globkurier.pl/services/history_order/ Pobranie informacji 50 ostatnich przesyłek klienta globkurier.pl Parametry Pole Opis Typ Wymagany LOGIN Login(email) string tak PASSWORD Hasło string tak Pole Typ Opis status bool true - brak błędu false - błąd error string informacja o błędzie historyOrder obj collection zwracana jest kolekcja obiektów Dane wyjściowe historyOrder Pole Typ Opis number string numer przesyłki w systemie GlobKurier sum_net float suma zamowienia netto payment_status string status opłaty za zamówienie: Null - brak płatności Oczekuje Zrealizowana Anulowana invoice string dokument za zamówienie GlobKurier.pl 18/33 Dokumentacja GlobKurier API Wersja: 1.12 preliminary_invoice string faktura proforma status int status przesyłki 0 - nowa 1 - w realizacji 2 - zrealizowana 3 - anulowana 4 - zwrot do nadawcy 5 - zamówienie błędne created_date datetime (YYYYmm-dd hh:mm:ss) data utworzenia zamówienia pickup_date date(YYYY-mm-dd) data nadania delivery_date date(YYYY-mm-dd) data odbioru recipient_name string nazwa nadawcy recipientr_address string adres nadawcy: ulica, numer domu, numer lokalu recipient_address_cont string adres nadawcy cd: kod pocztowy, miejscowość recipient_phone string telefon nadawcy recipient_mail string email nadawcy content string zawartośc przesyłki product string nazwa wybranej przesyłki Zwracane błędy Komunikat Opis Brak danych. Brak wymaganych pól w POST Brak parametru LOGIN. Proszę uzupełnić login Brak parametru PASSWORD. Proszę uzupełnić hasło Nieprawidłowy login lub hasło. Konto nieaktywne. GlobKurier.pl 19/33 Dokumentacja GlobKurier API Wersja: 1.12 Konto zablokowane. GlobKurier.pl 20/33 Dokumentacja GlobKurier API Wersja: 1.12 2.5 Pobieranie etykiet URL: http://www.test.webservices.globkurier.pl/services/label/ W przypadku, gdy została wygenerowana etykieta do danego zamówienia możemy pobrać ją z danego źródła. Parametry Pole Opis Typ Wymagany LOGIN Login(email) string tak PASSWORD Hasło string tak GKNUMBER Numer przesyłki w systemie GK string tak Dane wyjściowe Pole Typ Opis status bool true - brak błędu false - błąd error string informacja o błędzie url string odnośnik https:// do źródła, gdzie możemy pobrać etykietę. Zwracane błędy Komunikat Opis Brak danych. Brak wymaganych pól w POST Brak parametru LOGIN. Proszę uzupełnić login Brak parametru PASSWORD. Proszę uzupełnić password Brak parametru GKNUMBER. Proszę uzupełnić numer GK Nieprawidłowy login lub hasło. Nieprawidłowy numer przesyłki. Nie można pobrać etykiety, ponieważ przesyłka nie jest powiązana z tym kontem. GlobKurier.pl 21/33 Dokumentacja GlobKurier API Wersja: 1.12 Brak listu przewozowego, proszę spróbować ponownie. List przewozowy, nie został jeszcze wygenerowany. Konto nieaktywne. Konto zablokowane. 2.6 Lista usług URL: http://www.test.webservices.globkurier.pl/services/product/ Pobranie listy dostępnych produktów i dodatków. Parametry Pole Opis Typ Wymagany LOGIN Login (email użytkownika w systemie globkurier.pl) string tak PASSWORD Hasło, zakodowane funkcją skrótu MD5 string tak Dane wyjściowe Pole Typ Opis status bool true - brak błędu false - błąd error string informacja o błędzie list obj collection lista produktów, dodatków Fragment przykładowej struktury wyjścia: "status": true, "error": null, "list": { "product": [ { "symbol": "S110", "name": "Do 30kg dostawa do 12:00", "carrier": "DHL", "carrier_img": "https://www.globkurier.pl/materialy/kurier/min/1.png" GlobKurier.pl 22/33 Dokumentacja GlobKurier API Wersja: 1.12 }, { "symbol": "S101", "name": "Do 30kg dostawa do 9.30", "carrier": "DHL", "carrier_img": "https://www.globkurier.pl/materialy/kurier/min/1.png" }, … ], "addon": [ { "symbol": "A114", "name": "Pobranie COD do 11.000 zł w 2 dni", "carrier": "DHL", "carrier_img": "https://www.globkurier.pl/materialy/kurier/min/1.png" }, { "symbol": "A109", "name": "Powiadomienie o doręczeniu (SMS)", "carrier": "DHL", "carrier_img": "https://www.globkurier.pl/materialy/kurier/min/1.png" }, … ] } } Zwracane błędy Komunikat Opis Brak danych. Brak wymaganych pól w POST Brak parametru LOGIN. Proszę uzupełnić login Brak parametru PASSWORD. Proszę uzupełnić hasło Nieprawidłowy login lub hasło. Konto nieaktywne. Konto zablokowane. GlobKurier.pl 23/33 Dokumentacja GlobKurier API Wersja: 1.12 2.7 Lista krajów URL: http://www.test.webservices.globkurier.pl/services/country/ Pobranie listy obsługiwanych krajów, kody są wykorzystywane do wyceny przesyłek oraz do składania zamówień. Kody bazują na kodach ISO 3166-1 alfa-2 https://pl.wikipedia.org/wiki/ISO_3166-1_alfa-2 z tym, że wydzielono dodatkowe obszary dla lepszego dopasowania cennika np. Wielka Brytania występuje w wariantach GB1, GB2, GB3, GB4, GB5 dla rozróżnienia poszczególnych państw członkowskich. Parametry: Usługa nie przyjmuje dodatkowych parametrów, zawsze zwracana jest pełna lista krajów. Usługa nie wymaga autoryzacji. Dane wyjściowe Pole Typ Opis status bool true – brak błędu false – wystąpił błąd error apiError Struktura informacyjna o błędzie list array of apiCountry Tablica struktur informacji o krajach apiError Pole Typ Opis code string Kod błędu message string Komunikat błędu apiCountry Pole Typ Opis isoCode string Kod kraju, wykorzystywany w strukturach Order jako węzeł <country> country string Nazwa kraju isRoadAvailable bool true - dostępny jest transport drogowy false – brak możliwości transportu drogowego isUeMember bool true - Państwo członkowskie Unii Europejskiej false - Państwo spoza obszaru Unii Europejskiej GlobKurier.pl 24/33 Dokumentacja GlobKurier API Wersja: 1.12 blockedTransport NULL | string null - brak blokady nałożonej na kraj, IMPORT - państwo wykluczone z importu przesyłek, EXPORT - państwo wykluczone z eksportu przesyłek, ALL - państwo wykluczone z importu oraz eksportu przesyłek Sugerowane użycie to blokada opcji w kontrolce dropdown, gdy kraj występuje po stronie blokady. Wycena w takim przypadku zwróci pustą ofertę produktową. Fragment przykładowej struktura wyjścia: { "list": [ { "isoCode": "AF", "country": "Afganistan", "isRoadAvailable": false, "isUeMember": false, "blockedTransport": null }, { "isoCode": "AL", "country": "Albania", "isRoadAvailable": true, "isUeMember": false, "blockedTransport": null }, … ], "status": true, "error": null } GlobKurier.pl 25/33 Dokumentacja GlobKurier API Wersja: 1.12 2.8 Lista punktów GlobBox URL: http://www.test.webservices.globkurier.pl/services/globbox/get_points/ Wyszukanie punktu GlobBox po kodzie pocztowym lub miejscowości. Parametry Pole Opis Typ Wymagany LOGIN Login (email użytkownika w systemie glob kurier.pl) string tak PASSWORD Hasło, zakodowane funkcją skrótu MD5 string tak APIKEY Klucz API string tak LOCATION Parametr lokalizacyjny, po którym wyszukujemy punkt globbox. Może to być miejscowość, lub kod pocztowy podany w formacie XX-XXX lub XXXXX string tak Dane wyjściowe Pole Typ Opis status bool true - brak błędu false - błąd error string informacja o błędzie points obj collection lista punktów Przykładowa struktura wyjścia: { "status": true, "error": null, "points": [ { "id_partner_klienci": "869", "nazwa_marketingowa": "Tabak Polska (Kaufland)", "nip": "6312331460", "ulica": "ul. Struga", "nr_dom": "29", GlobKurier.pl 26/33 Dokumentacja GlobKurier API Wersja: 1.12 "nr_lokal": "", "kod_pocztowy": "70-784", "miasto": "Szczecin", "wojewodztwo": "Zachodniopomorskie", "telefon": "516188393", "godziny_otwarcia": "pon-ndz: 07:00-21:00", "dlugosc_geograficzna": "14.658233", "szerokosc_geograficzna": "53.384588" }, { "id_partner_klienci": "971", "nazwa_marketingowa": "Akademickie Centrum Us\u0142ug", "nip": "995-162-23-05", "ulica": "ul. Cukrowa ", "nr_dom": "8 ", "nr_lokal": "", "kod_pocztowy": "71-004 ", "miasto": "Szczecin", "wojewodztwo": "Zachodniopomorskie", "telefon": "503 737 811", "godziny_otwarcia": "pon-pt: 11:00-19:00", "dlugosc_geograficzna": "14.498425", "szerokosc_geograficzna": "53.403211" }, { "id_partner_klienci": "685", "nazwa_marketingowa": "Instytut Rozwoju Edukacji", "nip": "852-162-07-49", "ulica": "ul. Boh. Warszawy", "nr_dom": "83", "nr_lokal": "", "kod_pocztowy": "71-061", "miasto": "Szczecin", "wojewodztwo": "zachodniopomorskie", "telefon": "784658518", "godziny_otwarcia": "pon.-pt.: 10:00-18:00 sb.: 10:00-14:00", "dlugosc_geograficzna": "14.531960", "szerokosc_geograficzna": "53.423114" } ] } GlobKurier.pl 27/33 Dokumentacja GlobKurier API Wersja: 1.12 Zwracane błędy Komunikat Opis Brak danych. Brak wymaganych pól w POST Nieprawidłowy login lub hasło. Konto nieaktywne. Konto zablokowane. Brak lokalizacji. Brak punktów pod wskazaną lokalizacją. 2.9 Lista terminali URL: http://www.test.webservices.globkurier.pl/services/terminal/ Pobranie listy terminali dla zadanych kryteriów. Terminalem może być automat typu paczkomat, urząd pocztowy, placówka kurierska lub punkt obsługi klienta. Parametry Pole Opis PRODUCT Symbol produktu uzyskany string z wyceny (dokumentacja w osobnym dokumencie Globkurier Zdalna wycena) lub z metody opisanej w punkcie 2.6 Lista usług tak COD 0 - pełna lista terminali 1 - lista zostanie ograniczona do punktów z możliwością obsługi płatności za pobranie COD int nie, domyślnie przyjmuje 0 TOWN Miasto - lista zostanie ograniczona do punktów z danej miejscowości string Dla Paczki w Ruchu POSTCODE Kod pocztowy - lista zostanie ograniczona do punktów spod danego kodu pocztowego string Dla Paczki w Ruchu GlobKurier.pl Typ Wymagany 28/33 Dokumentacja GlobKurier API Wersja: 1.12 Dane wyjściowe Pole Typ Opis status bool true – brak błędu false – wystąpił błąd error apiError Struktura informacyjna o błędzie list array of apiDepartment Tablica struktur informacji o terminalach isSender bool true - terminal może służyć jako punkt nadań dla wybranej usługi false - terminal nie może służyć jako punkt nadań isSenderMandatory bool true - Przekazanie kodu terminalu w zleceniu jest obowiązkowe, false – Przekazanie kodu terminalu jest opcjonalne isReceiver bool true - terminal może służyć jako punkt odbioru dla wybranej usługi false – terminal nie może służyć jako punkt odbioru isReceiverMandatory bool true - Przekazanie kodu terminalu w zleceniu jest obowiązkowe, false – Przekazanie kodu terminalu jest opcjonalne Pole Typ Opis code string Kod błędu message string Komunikat błędu apiError apiDepartment Pole Typ Opis departmentId string Identyfikator terminalu department string Nazwa punktu town string Miasto, w którym znajduje się punkt address string Adres punktu GlobKurier.pl 29/33 Dokumentacja GlobKurier API Wersja: 1.12 postalCode string Kod pocztowy codAvailable bool Punkt obsługuje płatność za pobranie COD type string MACHINE – automat paczkowy OFFICE – punkt obsługi klienta, placówka kurierska lub urząd pocztowy Przykładowa struktura wyjścia: { "list": [ { "departmentId": "BRZ01ML", "department": "Katowice BRZ01ML", "town": "Katowice", "address": "Kurpiowska 1A", "postalCode": "40-215", "codAvailable": true, "type": "MACHINE" }, { "departmentId": "JAN424", "department": "Warszawa Janki JAN424", "town": "Warszawa Janki", "address": "Mszczonowska 3", "postalCode": "05-090", "codAvailable": true, "type": "MACHINE" }, … ], "isSender": true, "isSenderMandatory": true, "isReceiver": true, "isReceiverMandatory ": true, "status": true, "error": null } GlobKurier.pl 30/33 Dokumentacja GlobKurier API Wersja: 1.12 2.10 Lista celów przesyłki URL: http://www.test.webservices.globkurier.pl/services/purposes/ Pobranie listy dostępnych celów przesyłki. Jako parametr wejściowy przyjmuje symbol produktu. Parametry Pole Opis Typ Wymagany product Symbol produktu uzyskany z wyceny (dokumentacja w osobnym dokumencie Globkurier Zdalna wycena) lub z metody opisanej w punkcie 2.6 Lista usług string tak Dane wyjściowe Pole Typ Opis code string Nazwa celu do wykorzystania w zamówienie label string Tłumaczenie celu Przykładowa struktura wyjścia: { "list": [ { "code": "GIFT", "label": "Prezenty" }, { "code": "NOT_SOLD", "label": "Rzeczy do użytu własnego" }, { "code": "PERSONAL_EFFECTS", "label": "Przedmioty osobiste" }, { "code": "REPAIR_AND_RETURN", "label": "Naprawa i zwrot" GlobKurier.pl 31/33 Dokumentacja GlobKurier API Wersja: 1.12 }, { "code": "SAMPLE", "label": "Próbki" }, { "code": "SOLD", "label": "Cel handlowy" } ], "status": true, "error": null } 2.11 Protokół zbiorczy URL: http://www.test.webservices.globkurier.pl/services/protocol/ Generacja protokołu zbiorczego. Przekazywane jako parametry numery przesyłek GK muszą posiadać tą samą datę nadania, adres nadawcy oraz przewoźnika. Obecnie wspierana dla zleceń przewoźnika DPD. Parametry Pole Opis Typ Wymagany login Login (email użytkownika w systemie glob kurier.pl) string tak password Hasło, zakodowane funkcją skrótu MD5 string tak apikey Klucz API string tak shipments Tablica numerów GK przesyłek Array of strings tak Dane wyjściowe Pole Typ Opis status bool true – brak błędu false – wystąpił błąd GlobKurier.pl 32/33 Dokumentacja GlobKurier API Wersja: 1.12 error apiError Struktura informacyjna o błędzie list array Tablica zwracanych parametrów list/pdfProtocolContent string Protokół w formacie PDF zakodowany algorytmem base64 apiError Pole Typ Opis code string Kod błędu message string Komunikat błędu Przykładowa struktura wyjścia: { "list": [ { "pdfProtocolContent":"JVBERi0xLjQKJaqrrK0KNCAwIG9iag…" } ], "status": true, "error": null } 3. Podsumowanie Z systemu należy korzystać rozważnie, wszelkie próby nadużycia będą skutkowały zablokowaniem konta. W przypadku jakichkolwiek problemów z przyznaniem dostępów do środowiska produkcyjnego prosimy kontaktować się z administratorem API wymienionym w nagłówku dokumentu. Koniec dokumentu GlobKurier.pl 33/33