Rozhraní Kokiskashop.cz

Tato sekce dokumentuje API na naší straně. Při volání jakékoliv služby je nutné uvádět pole login a password, jinak bude požadavek odmítnut. Následuje výčet služeb včetně vstupních, výstupních parametrů, možných chybových situacích a příkadu

Volání api je sestaveno následovně: https://www.kokiskashop.cz/api/heureka/1/:sluzba/:akce , kde :sluzba značí oblast působnosti požadavku a :akce již konkrétní žádost. V popisu služeb je :služba vždy před lomítkem a :akce za lomítkem.

Je-li volání úspěšné, odpověď vždy obsahuje kod 200. V opačném případě je hlášen chybový kod 404 a zobrazena chybová hláška.

Upozornění:
Při implementaci API (především odesílání objednávek) si vždy ověřujte dostupnost zvolené dopravy pomocí služby payment/delivery pro aktuální sadu produktů v košíku. Může se stát, že některý produkt je pro danou přepravou nedoručitelný. Typická situace je horní omezení hmotnosti. Služba payment/delivery, Vám poskytne všechny možnosti přepravy pro zvolené produkty a to včetně cen a podporovaných platebních metod. Voláním služby získáte také delivery_id a payment_id nutné pro odeslání objednávky. Objednávky, které budou obsahovat neplatné hodnoty delivery_id nebo payment_id budou automaticky odmítány.

Dostupnost API
Snažíme se mít maximální možnou dostupnost, nicméně se může stát nějaký problém, kdy nebude možné přijímat objednávky. V takovém případě byste měli mít naprogramované řešení, které se později pokusí objednávku odeslat znovu.

Validace dat
U každého požadavku je nutné uvádět jak váš login, tak heslo. To platí i pro požadavky na dostupnost zboží, popřípadě přepravu. Všechny dotazy na API bez správných přihlašovacích údajů budou odmítnuty. Nejčastější problémy nastávají při volání služby order/send , kde v části customer chybí buď parametr firstname nebo surname. Je nutné uvádět oba dva. Také rozdělení ulice a čísla domu je velmi důležité (dopravci vyžadují data zvlášť a musíme je nyní ručně upravovat).

Id dopravy a platby získáte jedině voláním služby payment/delivery. Popřípadě id dopravy naleznete ve feedu u elementů s dopravou. Nikde jinde správná id nenaleznete

Všechny data použitá v příkladech jsou pouze ilustrativní.

GET products/availability

Aktuální data o požadovaných produktech. Zjištění skladové dostupnosti, případné doby dodání, ceny a jména.

Metoda:

GET

Parametry:

products - array - pole s produkty, může obsahovat libovolný počet položek
- id - integer - jedinečný identifikátor produktu, ve feedu značeno jako ID
- count - integer - počet požadovaných kusů produktu
login - string - login uživatele, který se ke službě připojuje
password - string - heslo uživatele, který se ke službě připojuje (bud jako plain text nebo hash algoritmem "sha256")

Odpověď:

products - array - pole s produkty, může obsahovat libovolný počet položek
- id - integer - jedinečný identifikátor produktu, ve feedu značeno jako ID
- available - boolean - udává dostupnost produktu - dostupný: true, nedostupný: false. (Pozn. false se v PHP často reprezentuje jako 0, NULL nebo prázdný string)
- count - integer - počet dostupných kusů (vždy menší nebo rovno počtu požadovaných kusů) v deklarované dostupnosti
- delivery - integer|string - počet dnů k odeslání (0 - expedice do 24 hodin, 1 - 1 den do expedice,...), pokud není tento údaj k dispozice je uvedena přibližná informace (do 5 dnů, na dotaz,..)
- name - string - celý název produktu
- price - float - cena za 1 kus včetně DPH
- priceTotal - float - cena za všechny kusy včetně DPH (cena x počet kusů)
priceSum - float - celková cena za všechny produkty

Příklad:

	 
< ?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 = "https://www.kokiskashop.cz/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

Možnosti dopravy a platby. Například zboží lze dodat pomocí České pošty s možností dobírky nebo platby předem. Služba počítá s vždy aktuálním ceníkem a hmotností produktů. Můžete se spolehnout, že vrácená cena odpovídá hmotnosti nejtěžšího produktu v objednávce.

Metoda:

GET

Parametry:

products - array - pole s produkty, může obsahovat libovolný počet položek
- id - integer - jedinečný identifikátor produktu, ve feedu značeno jako ID
- count - integer - počet požadovaných kusů produktu
login - string - login uživatele, který se ke službě připojuje
password - string - heslo uživatele, který se ke službě připojuje (bud jako plain text nebo hash algoritmem "sha256")

Odpoveď:

transport - array - doprava produktu (Česká pošta, DPD, osobní odběr,...)
- id - integer - jedinečný identifikátor dopravy
- type - integer - druh dopravy
- name - string název přepravy
- price - float - cena dopravy včetně DPH
- description - string - doplňující popis dopravy (např: do 2 kg,...)
payment - array - možnost platby (například dobírka a jak je zpoplatněna)
- id - integer - jedinečný identifikátor platby
- type - integer - druh platby
- name - string název platby
- price - float - cena za platbu včetně DPH
binding - array - pole vazeb dopravy a platby. Znázornuje například, že DPD má dobírku za 45 Kč, kdežto např. Česká pošta za 50 Kč,...
- id - integer - identifikátor vazby
- transportId - integer - id způsobu dopravy
- paymentId - integer id upůsobu platby

Příklad

GET order/status

Vrátí, v jakém stavu je objednávka

Metoda:

GET

Parametry:

order_id - integer - identifikátor objednávky v Kokiskashop.cz. Tento údaj je vrácen při tvorbě objednávky pomocí služby order/send
login - string - login uživatele, který se ke službě připojuje
password - string - heslo uživatele, který se ke službě připojuje (bud jako plain text nebo hash algoritmem "sha256")

Odpoveď:

order_id - integer - identifikátor objednávky v Kokiskashop.cz. Tento údaj je vrácen při tvorbě objednávky pomocí služby order/send
status - integer - stav objednávky (0 - objednávka vyexpedována (obchod odeslal objednávku zákazníkovi), 1 - objednávka odeslána do obchodu, 2 - objednávka byla vyřízena jen částečně, 3 - objednávka potvrzena (obchod objednávku přijal a potvrzuje, že ji začíná zpracovávat), 4 - storno z pohledu obchodu (obchod stornoval objednávku), 5 - storno z pohledu zákazníka (zákazník se rozhodl stornovat objednávku), 6 - storno - objednávka nebyla zaplacena (zákazník nezaplatil za objednávku), 7 - vráceno ve 14 denní lhůtě (zákazník vrátil zboží v zákonné 14 denní lhůtě), 8 - objednávka byla dokončena u partnera, 9 - objednávka dokončena (zákazník zaplatil a převzal objednávku), 10 - objednávka připravena k vyzvednutí

Příklad

< ?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 = "https://www.kokiskashop.cz/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

Odeslání objednávky do obchodu. V momentu odeslání se požadované zboží zablokuje pro tuto objednávku a zákazník o něj již nepřijde.

Služby přijímá parametry deliveryId a paymentId, které značí jedinečné identifikátory možností platby. Hodnoty pro konkrétní sadu produktů získáte pomocí služby payment/delivery. Bez jejich uvedení není možné objednávku vytvořit a také byste nemohli správně očekávat celkovou cenu (cena dopravy je závislá na hmotnosti produktů).

Metoda:

POST

Parametry:

products - array - pole s produkty, může obsahovat libovolný počet položek
- id - integer - jedinečný identifikátor produktu, ve feedu značeno jako ID
- count - integer - počet požadovaných kusů produktu
- price - float - cena za 1 kus včetně DPH, za kterou si zákazník zboží objednal
productsTotalPrice - float - celková cena za produkty - není zahrnuta cena za dopravu
customer - array - informace o nakupujícím. Budou uvedeny na faktuře.
- firstname - string - jméno
- lastname - string - příjmení
- email - string - emailová adresa
- phone - string - telofon
- street - string - ulice
- houseNumber - string - číslo domu
- city - string - město
- postCode - string - PSČ
- state - string - stát. Preferujeme v plném tvaru, např: Česká republika místo CZ nebo ČR
- company - string nepovinný parametr - název firmy na kterou se fakturuje. Na faktuře nakonec bude "Firma, jméno přijmení"
- ic - integer nepovinný parametr - IČ
- dic - string nepovinný parametr - DIČ
deliveryAddress - array - dodací adresa. V současné době je nutné uvádět vždy
- firstname - string - jméno
- lastname - string - příjmení
- street - string - ulice
- houseNumber - string - číslo domu
- city - string - město
- postCode - string - PSČ
- state - string - stát. Preferujeme v plném tvaru, např: Česká republika místo CZ nebo ČR
- company - string nepovinný parametr - název firmy, dodávat se bude na "Firma, jméno přijmení"
deliveryId - integer - identifikátor zvolené dopravy
paymentId - integer - identifikátor zvolené platby
note - string - poznámka k objednávce, typicky žádost nebo sdělení zákazníka. Např: doručte v dopoledních hodinách,...
login - string - login uživatele, který se ke službě připojuje
password - string - heslo uživatele, který se ke službě připojuje (bud jako plain text nebo hash algoritmem "sha256")

Odpoveď:

order_id - integer - identifikátor objednávky. Používá se při každém dalším volání jako je např. order/status nebo order/cancel
internal_id - string - interní identifikátor. V našem případě shodný s id_order
variableSymbol - big integer - variabilní symbol (max. 10 číslic a bez nevýznamných nul), slouží ke spárovnání plateb a objednávek

Příklad

< ?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 = "https://www.kokiskashop.cz/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

Stornování objednávky. Doporučejeme používat velmi obezřetně. Může dojít až ke stornování faktury.

Metoda:

PUT

Parametry:

order_id - integer - identifikátor objednávky v Kokiskashop.cz. Tento údaj je vrácen při tvorbě objednávky pomocí služby order/send
login - string - login uživatele, který se ke službě připojuje
password - string - heslo uživatele, který se ke službě připojuje (bud jako plain text nebo hash algoritmem "sha256")

Odpoveď:

status - boolean - ukazatel úspěchu. Je-li true, tak vše proběhlo v pořádku. V opačné případě je hodnota false

Příklad

< ?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 = "https://www.kokiskashop.cz/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

Úprava stavu platby v našem obchodě. Typické použití máte-li implementovánu platbu platební kartou a informace o platbě se načte k vám do obchodu.

Metoda:

PUT

Parametry:

order_id - integer - identifikátor objednávky v Kokiskashop.cz. Tento údaj je vrácen při tvorbě objednávky pomocí služby order/send
status - integer - stav platby(1 - zaplaceno, -1 - nezaplaceno)
date - string - datum kdy došlo ke změně (YYYY-MM-DD)
login - string - login uživatele, který se ke službě připojuje
password - string - heslo uživatele, který se ke službě připojuje (bud jako plain text nebo hash algoritmem "sha256")

Odpoveď:

status - boolean - ukazatel úspěchu. Je-li true, tak vše proběhlo v pořádku. V opačné případě je hodnota false

Příklad

< ?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 = "https://www.kokiskashop.cz/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 
)

Chybové hlášky

V případě selhání objednávky Vám náš systém pošle automatický email s chybou zprávou. Příkladem takové hlášky je: U produktu M0426 je špatně vyplněna hodnota množství. Buď chybí nebo je prázdná. Email obsahuje datum a čas volání vytvoření, kompletní vstupní data, která jsme obdrželi, a nakonec chybovou hlášku, proč se přenos nezdařil.

Rozhraní Kokiskashop.cz

GET products/availability

Metoda:

Parametry:

Odpověď:

GET payment/delivery

Metoda:

Parametry:

Odpoveď:

GET order/status

Metoda:

Parametry:

Odpoveď:

POST order/send

Metoda:

Parametry:

Odpoveď:

PUT order/cancel

Metoda:

Parametry:

Odpoveď:

PUT payment/status

Metoda:

Parametry:

Odpoveď:

Chybové hlášky

Informace

Podpora

Kontakt