Interfejs Kokiskashop.pl

Ten rozdział opisuje API po naszej stronie.. Przy wywołaniu jakiejkolwiek usługi w pierwszej kolejności należy podać pola login a password, w innym przypadku żądanie zostanie odrzucone. Poniżej znajduje się lista usług, w tym parametry wejściowe, wyjściowe, możliwe sytuacje błędów i przykłady

Wywołanie API zestawia się w następujący sposób: https://www.kokiskashop.pl/api/heureka/1/:usługa/:akcja , gdzie :usługa znaczy obszar żądania a :akcja konkretne żądanie. W opisie usługi występuje usługa przed slash a :akcja za slash.

Jeśli połączenie zakończy się powodzeniem, odpowiedź zawiera kod 200. W przeciwnym razie zgłaszany jest kod błędu 404 i wyświetlany jest komunikat o błędzie.

Uwaga:
Podczas wdrażania interfejsu API (głównie podczas wysyłania zamówień) prosimy zawsze sprawdzać dostępność wybranej dostawy za pomocą usługi payment/delivery dla bieżącego zestawu produktów w koszyku. Może się zdarzyć, że produkt będzie niedoręczalny w ramach przesyłki. Typową sytuacją jest górne ograniczenie wagi. Usługa payment/delivery określi Państwu wszystkie możliwości dostawy dla wybranych produktów wraz z cenami i metodami płatności. Wywołując usługę, otrzymają Państwo także delivery_id a payment_id niezbędne do wysłania zamówienia. Zamówienia zawierające nieprawidłowy identyfikator dostawy lub identyfikator płatności będą automatycznie odrzucane.

Dostępność API
Staramy się zapewnić maksymalną dostępność, jednak może wystąpić problem, gdy nie będzie możliwe odbieranie zamówień. W tym celu powinno być zaprogramowane rozwiązanie, które ponowi później próbę wysłania zamówienia.

Sprawdzanie danych
Do każdego żądania należy podać zarówno swój login, jak i hasło. Dotyczy to również wymagań dotyczących dostępności towarów lub transportu. Wszystkie zapytania API bez poprawnych danych logowania zostaną odrzucone. Najczęstsze problemy występują podczas wywoływania usługi order/send gdzie w części customer brakują parametry firstname albo surname. Należy wprowadzić obydwa. Ważne jest również rozdzielenie ulicy i numeru domu, ponieważ firmy transportowe żądają poszczególne dane osobno.

Id dostawy i płatności można uzyskać wyłącznie wywołaniem usługi payment/delivery. Ewentualnie id dostawy można znaleźć w feed w elemencie dostawy. W żadnym innym miejscu prawidłowe id nie są umieszczane.

Wszystkie dane użyte w przykładach są jedynie ilustracyjne.

GET products/availability

Aktualne dane dotyczące pytanych produktów. Określanie dostępności zapasów, prognozowanych terminów dostawy, ceny i nazwy.

Metoda:

GET

Parametry:

products - array - Pole z produkty mogą zawierać dowolną liczbę elementów
- id - integer - unikalny identyfikator produktu, oznaczony jako ID w feed
- count - integer - liczba wymaganych sztuk produktu
login - string - login użytkownika, który łączy się z usługą
password - string - hasło użytkownika, które łączy się z usługą (jako zwykły tekst lub hash algorytm "sha256")

Odpowiedź:

products - array - Pole z produkty mogą zawierać dowolną liczbę elementów
- id - integer - unikalny identyfikator produktu, oznaczony jako ID w feed
- available - boolean - wskazuje dostępność produktu - dostępny: true, niedostępny: false. (Uwaga False w PHP często jest reprezentowane jako 0, NULL albo pusty string.)
- count - integer - liczba dostępnych sztuk w deklarowanej dostępności
- delivery - integer|string - liczba dni do wysłania (0- wysyłka do 24h. 1 - 1 dzień do wysłania,....), jeżeli informacja ta nie jest dostępna, podane są przybliżone informacje (do 5 dni, na żądanie, ..)
- name - string - cała nazwa produktu
- price - float - cena za 1 sztukę z VAT
- priceTotal - float - cena za wszystkie sztuki, w tym VAT (cena x liczba sztuk)
priceSum - float - łączna cena dla wszystkich produktów

Przykład:

	 
< ?php
//include wrapper for curl library
include ('./RequestFactory.php');
 
//initiate array
$data['products'] = array();
//add first product
$data['products'][] = array('id' => 599, 'count' => 2);
//add next products
$data['products'][] = array('id' => 1091, 'count' => 1);
//add next products
$data['products'][] = array('id' => 109, 'count' => 6);
 
//add authentification info
$data['login'] = "yourLogin";
 
//password as plain text
$data['password'] = "yourPassword";
//password as hashcode
$data['password'] = hash("sha256", "yourPassword");
 
//set url for request
$url = "http://www.kokiskashop.pl/api/heureka/1/products/availability";
 
//choose method of request - products/availability should be GET
$method = RequestFactory::$METHOD_GET;
 
//make request and get response in JSON
$jsonResponse = RequestFactory::doRequest($url, $data, $method);
 
//decode response - bacause it is possible to handle big integers, it is necessary
//to set up json_decode function
$response = json_decode($jsonResponse, TRUE, 512, JSON_BIGINT_AS_STRING);
 
//now one has associative array. Print it
print_r($response); 
?>
 
OUTPUT: 
 
Array ( 
    [products] => Array ( 
        [0] => Array ( 
            [id] => 599 
            [available] => 1 
            [count] => 2 
            [delivery] => 0 
            [name] => Stan pro 6 osob 
            [price] => 3327 
            [priceTotal] => 6654 )  
        [1] => Array ( 
            [id] => 1091    
            [available] => 1 
            [count] => 1 
            [delivery] => 0 
            [name] => Didgeridoo 130 cm 
            [price] => 461 
            [priceTotal] => 461 ) 
        [2] => Array ( 
            [id] => 109 
            [available] => 0) 
        ) 
    [priceSum] => 7115 
)

GET payment/delivery

Opcje wysyłki i płatności. Na przykład towary mogą być wysyłane DPD za gotówkę lub przedpłatę. Usługa zawsze oblicza według aktualnego cennika i wagi produktów. Można polegać na tym, że zwrócona cena odpowiada całkowitej masie produktów.

Metoda:

GET

Parametry:

products - array - Pole z produkty mogą zawierać dowolną liczbę elementów
- id - integer - Unikalny identyfikator produktu, oznaczony jako ID w feed
- count - integer - liczba wymaganych sztuk produktu
login - string - login użytkownika, który łączy się z usługą
password - string - hasło użytkownika, które łączy się z usługą (jako zwykły tekst lub hash algorytm "sha256")

Odpowiedź:

transport - array - dostawa produktu (DPD, odbiór osobisty,...)
- id - integer - unikalny identyfikator transportu
- type - integer - rodzaj transportu
- name - string nazwy transportu
- price - float - cena transportu z VAT
- description - string - dodatkowy opis transportu (np. do 2 kg, ...)
payment - array - mopcja płatności (na przykład płatność przy odbiorze i sposób jej naliczania)
- id - integer - unikalny identyfikator płatności
- type - integer - rodzaj płatności
- name - string nazwy płatności
- price - float - cena za płatność z VAT
binding - array - pole powiązania transportu i płatności. Pokazuje na przykład, że DPD ma pobranie za 4 zł, podczas gdy na przykład Poczta za 6 zł, ...

id - integer - identyfikator powiązania
transportId - integer - ID sposób wysyłki
paymentId - integer ID rodzaju płatności

Przykład:

GET order/status

Zwraca status zamówienia.

Metoda:

GET

Parametry:

order_id - integer - identyfikator zamówienia na Kokiskashop.pl. Informacja ta jest zwracana przy tworzeniu zlecenia za pomocą usługi order/send
login - string - login użytkownika, który łączy się z usługą
password - string - hasło użytkownika, które łączy się z usługą (jako zwykły tekst lub hash algorytm "sha256")

Odpowiedź:

order_id - integer - identyfikator zamówienia na Kokiskashop.pl. Informacja ta jest zwracana przy tworzeniu zlecenia za pomocą usługi order/send
status - integer - status zamówienia (0 - zamówienie jest wysyłane (sklep wysłał zamówienie do klienta), 1 - zamówienie wysłane do sklepu, 2 - Zamówienie zostało zrealizowane jedynie częściowo 3 - zamówienie potwierdzone (zamówienie zostało przyjęte przez sklep, potwierdza, że jest przetwarzane); 4 - anulowane przez sklep (sklep anulował zamówienie), 5 - anulowane przez klienta (klient anulował zamówienie), 6 - storno - zamówienie nie zostało zapłacone (klient nie zapłacił za zamówienie) 7 - zwrócone w ciągu 14 dni (klient odesłał towar w ustawowym terminie 14 dni), 8 - zamówienie zostało zakończone u Partnera, 9 - zamówienie dokończone (zamówienie opłacone i otrzymane przez klienta), 10 - zamówienie gotowe do odbioru

Przykład:

< ?php
//include wrapper for curl library
include ('./RequestFactory.php');
 
//set order id
$data['order_id'] = 5016282;
 
//add authentification info
$data['login'] = "yourLogin";
 
//password as plain text
$data['password'] = "yourPassword";
//password as hashcode
$data['password'] = hash("sha256", "yourPassword");
 
//set url for request
$url = "http://www.kokiskashop.pl/api/heureka/1/order/status";
 
//choose method of request - order/status should be GET
$method = RequestFactory::$METHOD_GET;
 
//make request and get response in JSON
$jsonResponse = RequestFactory::doRequest($url, $data, $method);
 
//decode response - bacause it is possible to handle big integers, it is necessary
//to set up json_decode function
$response = json_decode($jsonResponse, TRUE, 512, JSON_BIGINT_AS_STRING);
 
//now one has associative array. Print it
print_r($response); 
?>
 
OUTPUT: 
 
Array ( 
    [order_id] => 5016282 
    [status] => 3 
)

POST order/send

Wysłanie zamówienia do sklepu. W momencie odesłania zamówiony towar się zablokuje dla tego zamówienia by klient mógł go otrzymać.

Usługa przyjmuje parametry deliveryId i paymentId, który wskazują unikalne identyfikatory opcji płatności. Wartości dla określonego zestawu produktów są dostępne za pośrednictwem usługi payment/delivery. Bez ich przekazania nie można utworzyć zamówienia i nie można poprawnie oczekiwać ceny łącznej (cena transportu zależy od wagi produktów).

Metoda:

POST

Parametry:

products - array - Pole z produkty mogą zawierać dowolną liczbę elementów
- id - integer - unikalny identyfikator produktu, oznaczony jako ID w feed
- count - integer - liczba wymaganych sztuk produktu
- price - float - cena za 1 sztukę z VAT za którą klient towar zamówił
productsTotalPrice - float - łączna cena produktów - cena transportu nie jest wliczona w cenę
customer - array - informacje o kupującym. Zostaną umieszczone na fakturze.
- firstname - string - imię
- lastname - string - nazwisko
- email - string - adres e-mail
- phone - string - telefon
- street - string - ulica
- houseNumber - string - numer domu, mieszkania
- city - string - miejscowość
- postCode - string - Kod pocztowy
- state - string - kraj. Preferujemy w pełnej formie, np.: Polska zamiast PL lub RP.
- company - string nieobowiązkowy parametr - nazwa firmy, na którą wystawia się fakturę. Na fakturze będzie ostatecznie "Firma, imię, nazwisko".
- ic - integer nieobowiązkowy parametr - Regon
- dic - string nieobowiązkowy parametr - NIP
deliveryAddress - array - adres dostawy. Obecnie, należy zawsze wprowadzić
- firstname - string - imię
- lastname - string - nazwisko
- street - string - ulica
- houseNumber - string - numer domu, mieszkania
- city - string - miejscowość
- postCode - string - Kod pocztowy
- state - string - kraj. Preferujemy w pełnej formie, np.: Polska zamiast PL lub RP.
- company - string nieobowiązkowy parametr - nazwa firmy, przyłącza się do "Firma, imię, nazwisko"
deliveryId - integer - identyfikator wybranego transportu
paymentId - integer - identyfikator wybranej płatności
note - string - uwaga do zamówienia, zazwyczaj prośba lub informacja od klienta Np .: dostarczyć rano, ...
login - string - login użytkownika, który łączy się z usługą
password - string - hasło użytkownika, które łączy się z usługą (jako zwykły tekst lub hash algorytm "sha256")

Odpowiedź:

order_id - integer - identyfikator zamówienia. Jest używany przy każdym kolejnym połączeni, jak np. order/status albo order/cancel.
internal_id - string - wewnętrzny identyfikator. W naszym przypadku, zgodny z id_order
variableSymbol - big integer - variabilní symbol (max. 10 cyfr i bez nieznaczących zer), służy do dopasowywania płatności i zamówień.

Przykład:

< ?php
//include wrapper for curl library
include ('./RequestFactory.php');
 
//initiate array
$data['products'] = array();
//add first product
$data['products'][] = array('id' => 599, 'count' => 2, 'price' => 3327);
//add next products
$data['products'][] = array('id' => 1091, 'count' => 1, 'price' => 461);
//add next products
$data['products'][] = array('id' => 1123, 'count' => 6, 'price' => 421);
 
//set total price for products
$data['productsTotalPrice'] = 9641;
 
//set info about customer
$data['customer']['firstname'] = "František";
$data['customer']['lastname'] = "Vomáčka";
$data['customer']['email'] = "frantisek.vomacka@example.com";
$data['customer']['phone'] = "+420 606 123 456";
$data['customer']['street'] = "Dlouhá";
$data['customer']['houseNumber'] = "16";
$data['customer']['city'] = "Kocourkov";
$data['customer']['postCode'] = "111 11";
$data['customer']['state'] = "Česká republika";
//optional params, could be empty
$data['customer']['company'] = "";
$data['customer']['id'] = "";
$data['customer']['dic'] = "";
 
//set info about delivery address
$data['deliveryAddress']['firstname'] = "Pavla";
$data['deliveryAddress']['lastname'] = "Nováková";
$data['deliveryAddress']['street'] = "Krátká";
$data['deliveryAddress']['houseNumber'] = "99";
$data['deliveryAddress']['city'] = "Kocourkov";
$data['deliveryAddress']['postCode'] = "111 11";
$data['deliveryAddress']['state'] = "Česká republika";
//optional params, could be empty
$data['deliveryAddress']['company'] = "";
 
//set deliveryId
$data['deliveryId'] = 2;
//set paymentId
$data['paymentId'] = 2;
 
//set note
$data['note'] = "Prosím dodat do pátku, poté odjíždíme na dovolenou.";
 
//add authentification info
$data['login'] = "yourLogin";
 
//password as plain text
$data['password'] = "yourPassword";
//password as hashcode
$data['password'] = hash("sha256", "yourPassword");
 
//set url for request
$url = "http://www.kokiskashop.pl/api/heureka/1/order/send";
 
//choose method of request - order/send should be POST
$method = RequestFactory::$METHOD_POST;
 
//make request and get response in JSON
$jsonResponse = RequestFactory::doRequest($url, $data, $method);
 
//decode response - bacause it is possible to handle big integers, it is necessary
//to set up json_decode function
$response = json_decode($jsonResponse, TRUE, 512, JSON_BIGINT_AS_STRING);
 
//now one has associative array. Print it
print_r($response); 
?>
 
OUTPUT: 
 
Array ( 
    [order_id] => 5016293
    [internal_id] => 5016293
    [variableSymbol] => 5016293
)

PUT order/cancel

Anulowanie zamówienia. Zalecamy korzystanie z najwyższą ostrożnością. Może dojść aż do anulowania faktury.

Metoda:

PUT

Parametry:

order_id - integer - identyfikator zamówienia na Kokiskashop.pl. Informacja ta jest zwracana przy tworzeniu zlecenia za pomocą usługi order/send
login - string - login użytkownika, który łączy się z usługą
password - string - hasło użytkownika, które łączy się z usługą (jako zwykły tekst lub hash algorytm "sha256")

Odpowiedź:

status - boolean - wskaźnik powodzenia. Jeżeli true, tak wszystko przebiegło w porządku. W przeciwnym przypadku jest wartość false

Przykład

< ?php
//include wrapper for curl library
include ('./RequestFactory.php');
 
//set order id
$data['order_id'] = 5016282;
 
//add authentification info
$data['login'] = "yourLogin";
 
//password as plain text
$data['password'] = "yourPassword";
//password as hashcode
$data['password'] = hash("sha256", "yourPassword");
 
//set url for request
$url = "http://www.kokiskashop.pl/api/heureka/1/order/cancel";
 
//choose method of request - order/cancel should be PUT
$method = RequestFactory::$METHOD_PUT;
 
//make request and get response in JSON
$jsonResponse = RequestFactory::doRequest($url, $data, $method);
 
//decode response - bacause it is possible to handle big integers, it is necessary
//to set up json_decode function
$response = json_decode($jsonResponse, TRUE, 512, JSON_BIGINT_AS_STRING);
 
//now one has associative array. Print it
print_r($response); 
?>
 
OUTPUT: 
 
Array ( 
    [success] => 1 
)

PUT payment/status

Dostosowanie statusu płatności w naszym sklepie. Typowe zastosowanie w przypadku płatności kartą, informacje o płatności naczyta się do sklepu.

Metoda:

PUT

Parametry:

order_id - integer - identyfikator zamówienia na Kokiskashop.pl. Informacja ta jest zwracana przy tworzeniu zlecenia za pomocą usługi order/send
status - integer - status płatności (1 – zapłacono, 0 - niezapłacona)
date - string - data, gdy dojdzie do zmiany (YYYY-MM-DD)
login - string - login użytkownika, który łączy się z usługą
password - string - hasło użytkownika, które łączy się z usługą (jako zwykły tekst lub hash algorytm "sha256")

Odpowiedź:

status - boolean - wskaźnik powodzenia. Jeżeli true, tak wszystko przebiegło w porządku. W przeciwnym razie wartość wynosi false

Przykład:

< ?php
//include wrapper for curl library
include ('./RequestFactory.php');
 
//set order id
$data['order_id'] = 5016282;
 
//add authentification info
$data['login'] = "yourLogin";
 
//password as plain text
$data['password'] = "yourPassword";
//password as hashcode
$data['password'] = hash("sha256", "yourPassword");
 
//set url for request
$url = "http://www.kokiskashop.pl/api/heureka/1/payment/status";
 
//choose method of request - payment/status should be PUT
$method = RequestFactory::$METHOD_PUT;
 
//make request and get response in JSON
$jsonResponse = RequestFactory::doRequest($url, $data, $method);
 
//decode response - bacause it is possible to handle big integers, it is necessary
//to set up json_decode function
$response = json_decode($jsonResponse, TRUE, 512, JSON_BIGINT_AS_STRING);
 
//now one has associative array. Print it
print_r($response); 
?>
 
OUTPUT: 
 
Array ( 
    [success] => 1 
)

Komunikaty o błędach

W przypadku niepowodzenia zamówienia, nasz system wyśle automatyczny e-mail z komunikatem o błędzie. Przykładami takiego komunikatu jest: W przypadku produktu M0426 niepoprawnie wypełniona ilość. Nie występuje lub pusta. E-mail zawiera datę i godzinę wywołania utworzenia, pełne dane wejściowe, które otrzymaliśmy oraz na koniec komunikat o błędzie, dlaczego transfer się nie powiódł.

Interfejs Kokiskashop.pl

GET products/availability

Metoda:

Parametry:

Odpowiedź:

GET payment/delivery

Metoda:

Parametry:

Odpowiedź:

GET order/status

Metoda:

Parametry:

Odpowiedź:

POST order/send

Metoda:

Parametry:

Odpowiedź:

PUT order/cancel

Metoda:

Parametry:

Odpowiedź:

PUT payment/status

Metoda:

Parametry:

Odpowiedź:

Komunikaty o błędach

Informacje

Wsparcie

Kontakt