DOKUMENTACJA TECHNICZNA KurJerzyAPI wersja 1.0

Transkrypt

DOKUMENTACJA TECHNICZNA
KurJerzyAPI
wersja 1.0
KurJerzyAPI wersja 1.0
Spis treści
Wstęp........................................................................3
1. Korzystanie z interfejsu KurJerzyAPI.................................4
1.1 Warunki korzystania z interfejsu.............................................4
1.2 Zabezpieczenia interfejsu.....................................................4
2. Specyfikacja interfejsu KurJerzyAPI.................................6
2.1 Proces składania zamówienia za pośrednictwem KurJerzyAPI...........6
2.2 Operacje podstawowe..........................................................7
2.3 Odbieranie informacji o statusie realizacji zamówienia................12
2.4 Przeprowadzanie integracji na środowisku produkcyjnym..............13
3. Uwagi....................................................................14
iTBross | ul. Dąbrowszczaków 1/104 | 80-374 Gdańsk | NIP 5842358236 | REGON 220900466
email: [email protected]
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
1. Korzystanie z interfejsu KurJerzyAPI
Współpraca z interfejsem udostępnionym przez platformę www.KurJerzy.pl 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
);
?>
Do poprawnego wygenerowania klucza Hash potrzebna jest tablica danych, która będzie
przekazywana w wywołaniu SOAP oraz apiPin użytkownika interfejsu.
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 2.1.
2.1 Proces składania zamówienia za pośrednictwem KurJerzyAPI
Przebieg procesu składania zamówień za pośrednictwem interfejsu KurJerzyAPI, który
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).
getShipmentDates ( userApiKey , requestHash, requestData )
requestData – tablica danych (należy przekazać pustą tablicę)
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ż
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 )
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
99999.99
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
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 )
requestData – tablica danych (należy przekazać parametry zamówienia)
plik_etykiety – wartość typu tekstowej zakodowana w postaci Base64
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. KJ1234567890).
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
<?php
// potwierdzenie odebrania statusu zamowienia
echo 'CONFIRMED';
?>
2.4 Przeprowadzanie integracji na środowisku produkcyjnym
Dokonywanie testów integracji na środowisku produkcyjnym https://www.kurjerzy.pl
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).
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:
[email protected]

DOKUMENTACJA TECHNICZNA KurJerzyAPI wersja 1.0

Transkrypt

Podobne dokumenty

Instrukcja uruchomienia usługi KurJerzyAPI dla OsCommerce 2.2

Instrukcja uruchomienia usługi KurJerzyAPI dla sklepu opartego na

Formularz zamówienia

WYKONAWCA Nazwa firmy: . REGON . NIP . adres firmy: . tel/fax

Formularz zamówienia PL

Wielkanocna zabawa z jajem na KurJerzy.pl!

upoważnienie - GTS Logistics

DEKLARACJA CZŁONKOWSKA Radzyńskigo Klubu Biznesu

Obudowa 2-SIM do SIEMENS C35 - GSM

Generuj PDF - Centralny Szpital Kliniczny MSWiA