DOKUMENTACJA TECHNICZNA KurJerzyAPI wersja 1.0

Transkrypt

1 KurJerzyAPI wersja 1.0

2 Spis treści Wstęp Korzystanie z interfejsu KurJerzyAPI Warunki korzystania z interfejsu Zabezpieczenia interfejsu Specyfikacja interfejsu KurJerzyAPI Proces składania zamówienia za pośrednictwem KurJerzyAPI Operacje podstawowe Odbieranie informacji o statusie realizacji zamówienia Przeprowadzanie integracji na środowisku produkcyjnym Uwagi...14

3 Wstęp Prezentowany dokument techniczny jest zbiorem informacji, reguł oraz zasad koniecznych do integracji zewnętrznych aplikacji klienckich z platformą KurJerzy.pl. Integracja ta jest możliwa dzięki wykorzystaniu logiki biznesowej zawartej w udostępnionym interfejsie KurJerzyAPI. Dokument zawiera następujące pojęcia oraz oznaczenia: KurJerzyAPI nazwa interfejsu umożliwiającego obsługę zamówień platformy KurJerzy.pl apikey ciąg znaków, będący identyfikatorem użytkownika KurJerzyAPI apipin ciąg znaków, wymagany do poprawnego wygenerowania kluczy Hash Hash ciąg znaków, weryfikujący poprawność i wiarygodność przesłanych danych <?php - przykładowe fragmenty kodu w języku PHP?> - prezentacja tablic, które są przekazywane oraz zwracane w trakcie wywołań operacji na KurJerzyAPI

4 1. Korzystanie z interfejsu KurJerzyAPI Współpraca z interfejsem udostępnionym przez platformę odbywa się za pośrednictwem protokołu SOAP w wersji 1.2 z kodowaniem znaków UTF-8. Zabezpieczenia przesyłanych danych opierają się na weryfikacji poprawności z wykorzystaniem klucza Hash. Sposób połączenia oraz generowania klucza zostanie przedstawiony w dalszej części dokumentu. 1.1 Warunki korzystania z interfejsu Dostęp do interfejsu może być wykorzystywany tylko przez podmiot, który zaakceptował Regulamin korzystania z KurJerzyAPI oraz zarejestrował się i uzyskał indywidualne dane logowania w procesie rejestracji. Przekazywanie danych dostępowych do interfejsu KurJerzyAPI traktowane jest jako nadużycie ze skutkiem zablokowanie dostępu do interfejsu KurJerzyAPI. 1.2 Zabezpieczenia interfejsu Podstawowym sposobem zabezpieczenia oraz zweryfikowania danych przesyłanych do KurJerzyAPI jest generowanie klucza Hash, który musi zostać przekazany jako parametr każdego wywołania operacji na interfejsie. Sposób tworzenia klucza Hash na przykładzie języka PHP został przedstawiony poniżej. <?php // generowanie klucza Hash $tablica_danych = array('1', '2', '3'); $apipin = '123456'; $hashkey = md5( md5( serialize( $tablica_danych ) ). $apipin );?>

5 Do poprawnego wygenerowania klucza Hash potrzebna jest tablica danych, która będzie przekazywana w wywołaniu SOAP oraz apipin użytkownika interfejsu.

6 2. Specyfikacja interfejsu KurJerzyAPI Operacje (metody), które zostały zaimplementowane w interfejsie KurJerzyAPI, można podzielić na operacje podstawowe (kluczowe do przeprowadzenia poprawnego składania zamówienia) oraz operacje dodatkowe (wspomagające proces składania zamówienia). Kolejność w jakiej powinny być wykonywane operacje podstawowe jest ściśle określona co zostało pokazane na diagramie w punkcie Proces składania zamówienia za pośrednictwem KurJerzyAPI Przebieg procesu składania zamówień za pośrednictwem interfejsu KurJerzyAPI, który

7 został przedstawiony na powyższym diagramie, dzieli się na 4 etapy: I. Pobranie danych potrzebnych do złożenia zamówienia a) pobranie danych produktowych (1:) b) pobranie terminów odbiorów przesyłek (3:) II. Złożenie zamówienia (5:) III. Przyjęcie statusu zamówienia (9:) (niewymagane, można pominąć ten krok) IV. Pobranie etykiety kurierskiej (10:) 2.2 Operacje podstawowe getuserproducts ( userapikey, requesthash, requestdata ) Parametry wejściowe: userapikey klucz użytkownika KurJerzyAPI requesthash klucz Hash (sposób generowania opisany w punkcie 1.3) requestdata tablica danych (należy przekazać pusta tablicę) Parametry wyjściowe: tablica_produktow tablica, której klucze stanowią identyfikator produktu, natomiast wartości zestawieniem parametrów usługi (nazwa produktu, cena produktu, maksymalna waga produktu).

8 getshipmentdates ( userapikey, requesthash, requestdata ) Parametry wejściowe: userapikey klucz użytkownika KurJerzyAPI requesthash klucz Hash (sposób generowania opisany w punkcie 1.3) requestdata tablica danych (należy przekazać pustą tablicę) Parametry wyjściowe: tablica_terminow tablica, która zawiera dostępne daty odbioru (dates) oraz zakresy godzinowe dla odbioru przesyłki w najbliższy możliwy dzień (time_from, time_to, time_from_max, time_to_max). dates tablica zawierająca możliwe daty odbiorów, której kluczami są liczby całkowite (unix timestamp) natomiast wartościami jest reprezantacja tekstowa daty time_from wartość typu integer określająca dolną wartość zakresu godzinowego początku odbioru (początkowa godzina odbioru nie może być mniejsza niż time_from) time_to - wartość typu integer określająca dolną wartość zakresu godzinowego końca odbioru (końcowa godzina odbioru nie może być mniejsza niż time_to) time_from_max - wartość typu integer określająca górną wartość zakresu godzinowego początku odbioru (początkowa godzina odbioru nie może być większa niż

9 time_from_max) time_to_max - wartość typu integer określająca górną wartość zakresu godzinowego końca odbioru (końcowa godzina odbioru nie może być większa niż time_to_max) Przykład: Początkowa godzina odbioru musi zawierać się pomiędzy godziną 13 a 15. Końcowa godzina odbioru musi zawierać się pomiędzy godziną 15 a 17. makeorder ( userapikey, requesthash, requestdata ) Parametry wejściowe: userapikey klucz użytkownika KurJerzyAPI requesthash klucz Hash (sposób generowania opisany w punkcie 1.3) requestdata tablica danych (należy przekazać parametry zamówienia) Kolorem czerwonym zostały oznaczone pola wymagane. Typy dopuszczalnych wartości: integer(4) oznacza wartośc typu liczby całkowitej o maksymalnej długości 4 znaków string(50) oznacza wartość typu tekst o maksymalnej długości 50 znaków float(7) oznacza wartośc typu liczby zmiennoprzecinkowej o maksymalnej wartości Określenie pól szczegółowych przesyłki (details): content zawartość przesyłki order_value wartość przesyłki (wartość wysyłanego towaru) insurance kwota ubezpieczenie przesyłki charging kwota pobrania przesyłki

10

11 Parametry wyjściowe: tablica_bledow tablica zawierająca błędy w przetwarzaniu operacji tablica_zamowien tablica, w której zwracane są numery zamówień getlabel ( userapikey, requesthash, requestdata ) Parametry wejściowe: userapikey klucz użytkownika KurJerzyAPI requesthash klucz Hash (sposób generowania opisany w punkcie 1.3) requestdata tablica danych (należy przekazać parametry zamówienia) Parametry wyjściowe: plik_etykiety wartość typu tekstowej zakodowana w postaci Base64

12 2.3 Odbieranie informacji o statusie realizacji zamówienia Status realizacji zamówienia wysyłany jest metodą GET na adres URL aplikacji klienckiej KurJerzyAPI, podany w trakcie ustalania szczegółów integracji. W obecnej wersji interejsu KurJerzyAPI nie ma potrzeby oczekiwania na status realizacji zamówienia gdyż zamówienia generowane są od razu po przekazaniu danych do systemu. Wywołanie skryptu aplikacji będzie zawierało następujące wartości: ordernumber numer zamówienia, którego dotyczy status (np. KJ ). orderstatus status w postaci liczby całkowitej (1 w trakcie realizacji, 2 zrealizowana popranie, -1 problem z realizacją zamówienia). hash klucz generowany z wyliczenia sumy funkcją md5 ze złączenia kolejno ordernumber, orderstatus oraz PIN użytkownika KurJerzyAPI. Poniżej przykład w języku PHP. <?php // generowanie klucza Hash dla skryptu odbierajacego status zamowienia $apipin = '123456'; $hash = md5( $ordernumber. $orderstatus. $apipin );?> Skrypt wysyłający powiadomienia o statusach zamówień, oczekuje na potwierdzenie odebrania statusu ciągiem znaków CONFIRMED

13 <?php // potwierdzenie odebrania statusu zamowienia echo 'CONFIRMED';?> 2.4 Przeprowadzanie integracji na środowisku produkcyjnym Dokonywanie testów integracji na środowisku produkcyjnym możliwe jest po uprzednim odznaczeniu opcji Tryb testowy w Panelu klienta w zakładce KurJerzyAPI. Tryb testowy pozwala na składanie zleceń poprzez KurJerzyAPI bez ich realizacji. Oznacza to, że zamówienia składane w trybie testowym nie obciążą salda konta Prepaid oraz nie zostanie wygenerowany list przewozowy lecz będzie możliwość przetestowania pełnej funkcjonalności KurJerzyAPI (składanie zleceń, pobieranie listów przewozowych).

14 3. Uwagi KurJerzyAPI jest w fazie rozwojowej co oznacza, iż kolejne wersje interfejsu będą wzbogacane o nowe funkcjonalności. Zmiany wprowadzane do interfejsu będą kompatybilne z poprzednimi wersjami klientów API. Wszelkie sugestie oraz uwagi prosimy kierować na adres: api@kurjerzy.pl