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
< ?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/payment/delivery";
 
//choose method of request - payment/delivery 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 ( 
    [binding] => Array ( 
        [0] => Array ( 
            [id] => 31 
            [transportId] => 3 
            [paymentId] => 1 ) 
        [1] => Array ( 
            [id] => 33 
            [transportId] => 3 
            [paymentId] => 3 ) 
        [2] => Array ( 
            [id] => 22 
            [transportId] => 2 
            [paymentId] => 2 ) 
        [3] => Array ( 
            [id] => 23 
            [transportId] => 2 
            [paymentId] => 3 ) 
        [4] => Array ( 
            [id] => 52 
            [transportId] => 5 
            [paymentId] => 2 ) 
        [5] => Array ( 
            [id] => 53 
            [transportId] => 5 
            [paymentId] => 3 ) 
        [6] => Array ( 
            [id] => 72 
            [transportId] => 7 
            [paymentId] => 2 ) 
        [7] => Array ( 
            [id] => 73 
            [transportId] => 7 
            [paymentId] => 3 ) 
        [8] => Array ( 
            [id] => 63 
            [transportId] => 6 
            [paymentId] => 3 ) 
    ) 
    [transport] => Array ( 
        [0] => Array ( 
            [id] => 3 
            [name] => osobní odběr Karlovy Vary 
            [description] => Stráň 3, 360 01 Karlovy Vary - Sadov, Česká Republika 
            [type] => 1 
            [price] => 0 ) 
        [1] => Array ( 
            [id] => 2 
            [name] => TopTrans standard 
            [description] => dodání do následujícího pracovního dne. U varianty XXXL je cena domluvou. 
            [type] => 3 
            [price] => 120 ) 
        [2] => Array ( 
            [id] => 5 
            [name] => TopTrans TopTime 
            [description] => dopolední doručení do 12 hod. 
            [type] => 4 
            [price] => 150 ) 
        [3] => Array ( 
            [id] => 7 
            [name] => TopTrans Top weekend 
            [description] => sobotní doručení 
            [type] => 3 
            [price] => 680 ) 
        [4] => Array ( 
            [id] => 6 
            [name] => Slovensko TopTrans standard 
            [description] => dodání do 48 hodin (pracovní dny) 
            [type] => 3 [price] => 399 ) 
    ) 
    [payment] => Array ( 
        [0] => Array ( 
            [id] => 1 [type] => 0 
            [price] => 0 
            [name] => hotově ) 
        [1] => Array ( 
            [id] => 3 
            [type] => 0 
            [price] => 0 
            [name] => předem ) 
        [2] => Array ( 
            [id] => 2 
            [type] => 0 
            [price] => 45 
            [name] => dobírka ) 
    ) 
)

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.

 

BIGtheme.net Joomla 3.3 Templates