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).
Všechny data použitá v příkladech jsou pouze ilustrativní.
GET products/availability
Metoda:
GETParametry:
- 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
Metoda:
GETParametry:
- 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
< ?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
Metoda:
GETParametry:
- 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
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:
POSTParametry:
- 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
Metoda:
PUTParametry:
- 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
Metoda:
PUTParametry:
- 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