Rozhranie Kokiskashop.sk

Táto sekcia dokumentuje API na našej strane. Pri volaní akejkoľvek služby je nutné uvádzať pole login a password, inak bude požiadavka odmietnutá. Nasleduje vymenovanie služieb vrátane vstupných, výstupných parametrov, možných chybových situácií a príkladov.

Volanie api je zostavené nasledovne: https://www.kokiskashop.sk/api/heureka/1/ :sluzba/:akcia, kde :sluzba označuje oblasť pôsobnosti požiadavky a :akcia už konkrétnu žiadosť. V popise služieb je :služba vždy pred lomítkom a :akcia za lomítkom.

Ak je volanie úspešné, odpoveď vždy obsahuje kód 200. V opačnom prípade je hlásený chybový kód 404 a zobrazená chybová hláška.

Upozornenie:
Pri implementácii API (predovšetkým odosielanie objednávok) si vždy overujte dostupnosť zvolenej dopravy pomocou služby payment/delivery pre aktuálnu sadu produktov v košíku. Môže sa stať, že niektorý produkt je pre danú prepravu nedoručiteľný. Typická situácia je horné obmedzenie hmotnosti. Služba payment/delivery Vám poskytne všetky možnosti prepravy pre zvolené produkty, a to vrátane cien a podporovaných platobných metód. Volaním služby získate aj delivery_id a payment_id nutné pre odoslanie objednávky. Objednávky, ktoré budú obsahovať neplatné hodnoty delivery_id alebo payment_id budú automaticky odmietané.

Dostupnosť API
Snažíme sa mať maximálnu možnú dostupnosť, môže sa však stať nejaký problém, kedy nebude možné prijímať objednávky. V takom prípade by ste mali mať naprogramované riešenie, ktoré sa neskôr pokúsi objednávku odoslať znovu.

Validácia dát
Pri každej požiadavke je nutné uvádzať Váš login, ale aj heslo. To platí aj pre požiadavky na dostupnosť tovaru, príp. prepravu. Všetky dotazy na API bez správnych prihlasovacích údajov budú odmietnuté. Najčastejšie problémy nastávajú pri volaní služby order/send, kde v časti customer chýba buď parameter firstname alebo surname. Je nutné uvádzať oboje. Tiež rozdelenie ulice a čísla domu je veľmi dôležité (dopravcovia vyžadujú dáta zvlášť a my ich potom musíme ručne upravovať).

Id dopravy a platby získate jedine volaním služby payment/delivery. Poprípade id dopravy nájdete vo feede pri elementoch s dopravou. Nikde inde správne id nenájdete.

Všetky dáta použité v príkladoch sú iba ilustračné.

GET products/availability

Aktuálne dáta o požadovaných produktoch. Zistenie skladovej dostupnosti, prípadné doby dodania, ceny a mená.

Metóda:

GET

Parametre:

products - array - polia s produktmi, môže obsahovať ľubovoľný počet položiek
- id - integer - jedinečný identifikátor produktu, vo feede označený ako ID
- count - integer - počet požadovaných kusov produktu
login - string - login používateľa, ktorý sa k službe pripája
password - string - heslo používateľa, ktorý sa k službe pripája (buď ako plain text alebo hash algoritmom "sha256")

Odpoveď:

products - array - polia s produktmi, môže obsahovať ľubovoľný počet položiek
- id - integer - jedinečný identifikátor produktu, vo feede označený ako ID
- available - boolean - udáva dostupnosť produktu - dostupný: true, nedostupný: false. (Pozn. False sa v PHP často reprezentuje ako 0, NULL alebo prázdny string)
- count - integer - počet dostupných kusov (vždy menšie rovno počtu požadovaných kusov) v deklarovanej dostupnosti
- delivery - integer|string - počet dní na odoslanie (0 - expedícia do 24 hodín, 1 - 1 deň do expedície, ...), pokiaľ nie je tento údaj k dispozícii, je uvedená približná informácia (do 5 dní, na otázku, ..)
- name - string - celý názov produktu
- price - float - cena za 1 kus vrátane DPH
- priceTotal - float - cena za všetky kusy vrátane DPH (cena x počet kusov)
priceSum - float - celková cena za všetky produkty

Prí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.sk/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 pre 6 osôb 
            [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. Napríklad tovar je možné dodať pomocou UPS s možnosťou dobierky alebo platby vopred. Služba počíta s vždy aktuálnym cenníkom a hmotnosťou produktov. Môžete sa spoľahnúť, že vrátená cena zodpovedá súhrnnej hmotnosti produktov.

Metóda:

GET

Parametre:

products - array - polia s produktmi, môže obsahovať ľubovoľný počet položiek
- id - integer - jedinečný identifikátor produktu, vo feede označený ako ID
- count - integer - počet požadovaných kusov produktu
login - string - login používateľa, ktorý sa k službe pripája
password - string - heslo používateľa, ktorý sa k službe pripája (buď ako plain text alebo hash algoritmom "sha256")

Odpoveď:

transport - array - doprava produktu (UPS, osobný odber,...)
- id - integer - jedinečný identifikátor dopravy
- type - integer - druh dopravy
- name - string názov prepravy
- price - float - cena dopravy vrátane DPH
- description - string - doplňujúci popis dopravy (napr: do 2 kg, ...)
payment - array - možnosť platby (napríklad dobierka a ako je spoplatnená)
- id - integer - jedinečný identifikátor platby
- type - integer - druh platby
- name - string názov platby
- price - float - cena za platbu vrátane DPH
binding - array - podľa väzieb dopravy a platby. Znázorňuje napríklad, že UPS má dobierku za 1,60 €.
- id - integer - identifikátor väzby
- transportId - integer - ID spôsobu dopravy
- paymentId - integer -ID spôsobu platby

Príklad

GET order/status

Vráti v akom stave je objednávka.

Metóda:

GET

Parametre:

order_id - integer - identifikátor objednávky v Kokiskashop.sk. Tento údaj je vrátený pri tvorbe objednávky pomocou služby order/send
login - string - login užívateľa, ktorý sa ku službe pripája
password - string - heslo užívateľa, ktorý sa ku službe pripája (buď ako plain text alebo hash algoritmom "sha256")

Odpoveď:

order_id - integer - identifikátor objednávky v Kokiskashop.sk. Tento údaj je vrátený pri tvorbe objednávky pomocou služby order/send
status - integer - stav objednávky - 0 - objednávka vyexpedovaná (obchod odoslal objednávku zákazníkovi), 1 - objednávka odoslaná do obchodu, 2 - objednávka bola vybavená iba čiastočne, 3 - objednávka potvrdená (obchod objednávku prijal a potvrdzuje, že ju začína spracovávať), 4 - storno z pohľadu obchodu (obchod stornoval objednávku), 5 - storno z pohľadu zákazníka (zákazník sa rozhodol stornovať objednávku), 6 - storno - objednávka nebola zaplatená (zákazník nezaplatil za objednávku), 7 - vrátené v 14-dennej lehote (zákazník vrátil tovar v zákonnej 14-dennej lehote), 8 - objednávka bola dokončená u partnera, 9 - objednávka dokončená (zákazník zaplatil a prevzal objednávku), 10 - objednávka pripravená k vyzdvihnutiu

Prí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.sk/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

Odoslanie objednávky do obchodu. V momente odoslania sa požadovaný tovar zablokuje pre túto objednávku a zákazník oň už nepríde.

Služba prijíma parametre deliveryId a paymentId, ktoré sú označné ako jedinečné identifikátory možností platby. Hodnoty pre konkrétnu sadu produktov získate pomocou služby payment/delivery. Bez ich uvedenia nie je možné objednávku vytvoriť a tiež by ste nemohli správne očakávať celkovú cenu (cena dopravy je závislá na hmotnosti produktov).

Metóda:

POST

Parametre:

products - array - pole s produktmi, môže obsahovať ľubovoľný počet položiek
- id - integer - jedinečný identifikátor produktu, vo feede značený ako ID
- count - integer - počet požadovaných kusov produktu
- price - float - cena za 1 kus vrátane DPH, za ktorú si zákazník tovar objednal
productsTotalPrice - float - celková cena za produkty - nie je zahrnutá cena za dopravu
customer - array - informácie o kupujúcom. Budú uvedené na faktúre.
- firstname - string - meno
- lastname - string - priezvisko
- email - string - emailová adresa
- phone - string - telefón
- street - string - ulica
- houseNumber - string - číslo domu
- city - string - mesto
- postCode - string - PSČ
- state - string - štát. Preferujeme v plnom tvare, napr.: Česká republika namiesto CZ alebo ČR
- company - string nepovinný parameter - názov firmy, na ktorú sa fakturuje. Na faktúre nakoniec bude "Firma, meno priezvisko"
- ic - integer nepovinný parameter - IČO
- dic - string nepovinný parameter - DIČ / IČ DPH
deliveryAddress - array - dodacia adresa. V súčasnej dobe je nutné uvádzať vždy
- firstname - string - meno
- lastname - string - priezvisko
- street - string - ulica
- houseNumber - string - číslo domu
- city - string - mesto
- postCode - string - PSČ
- state - string - štát. Preferujeme v plnom tvare, napr.: Česká republika namiesto CZ alebo ČR
- company - string nepovinný parameter - názov firmy, dodávať sa bude na "Firma, meno priezvisko"
deliveryId - integer - identifikátor zvolenej dopravy
paymentId - integer - identifikátor zvolenej platby
note - string - poznámka k objednávke, typicky žiadosť alebo oznámenie zákazníka. Napr.: doručte v dopoludňajších hodinách,...
login - string - login užívateľa, ktorý sa k službe pripája
password - string - heslo užívateľa, ktorý sa k službe pripája (buď ako plain text alebo hash algoritmom "sha256")

Odpoveď:

order_id - integer - identifikátor objednávky. Používa sa pri každom ďalšom volaní ako je napr. order/status alebo order/cancel
internal_id - string - interný identifikátor. V našom prípade zhodný s id_order
variableSymbol - big integer - variabilný symbol (max. 10 číslic a bez nevýznamných núl), slúži ku spárovaniu platieb a objednávok

Prí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'] = "Novotný";
$data['customer']['email'] = "frantisek.novotny@example.com";
$data['customer']['phone'] = "+421 902 123 456";
$data['customer']['street'] = "Dlhá";
$data['customer']['houseNumber'] = "16";
$data['customer']['city'] = "Kocúrkovo";
$data['customer']['postCode'] = "111 11";
$data['customer']['state'] = "Slovenská 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átka";
$data['deliveryAddress']['houseNumber'] = "99";
$data['deliveryAddress']['city'] = "Kocúrkovo";
$data['deliveryAddress']['postCode'] = "111 11";
$data['deliveryAddress']['state'] = "Slovenská 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 dodať do piatka, potom odchádzame na dovolenku.";
 
//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.sk/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

Stornovanie objednávky. Doporučujeme používať veľmi obozretne. Môže dôjsť až ku stornovaniu faktúry.

Metóda:

PUT

Parametre:

order_id - integer - identifikátor objednávky v Kokiskashop.sk. Tento údaj je vrátený pri tvorbe objednávky pomocou služby order/send
login - string - login užívateľa, ktorý sa ku službe pripája
password - string - heslo užívateľa, ktorý sa ku službe pripája (buď ako plain text alebo hash algoritmom "sha256")

Odpoveď:

status - boolean - ukazovateľ úspechu. Ak je true, tak všetko prebehlo v poriadku. V opačnom prípade je hodnota false

Prí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.sk/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šom obchode. Typické použitie ak máte implementovanú platbu platobnou kartou a informácie o platbe sa načítajú k Vám do obchodu.

Metóda:

PUT

Parametre:

order_id - integer - identifikátor objednávky v Kokiskashop.sk. Tento údaj je vrátený pri tvorbe objednávky pomocou služby order/send
status - integer - stav platby(1 - zaplatené, -1 - neuhradené)
date - string - dátum kedy došlo ku zmene (YYYY-MM-DD)
login - string - login užívateľa, ktorý sa ku službe pripája
password - string - heslo užívateľa, ktorý sa ku službe pripája (buď ako plain text alebo hash algoritmom "sha256")

Odpoveď:

status - boolean - ukazovateľ úspechu. Ak je true, tak všetko prebehlo v poriadku. V opačnom prípade je hodnota false

Prí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.sk/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 prípade zlyhania objednávky Vám náš systém pošle automatický email s chybovou správou. Príkladom takej hlášky je: Pri produkte M0426 je zle vyplnená hodnota množstva. Buď chýba alebo je prázdna. Email obsahuje dátum a čas vytvorenia, kompletné vstupné dáta, ktoré sme obdržali, a nakoniec chybovú hlášku, prečo sa prenos nepodaril.

Rozhranie Kokiskashop.sk

GET products/availability

Metóda:

Parametre:

Odpoveď:

GET payment/delivery

Metóda:

Parametre:

Odpoveď:

GET order/status

Metóda:

Parametre:

Odpoveď:

POST order/send

Metóda:

Parametre:

Odpoveď:

PUT order/cancel

Metóda:

Parametre:

Odpoveď:

PUT payment/status

Metóda:

Parametre:

Odpoveď:

Chybové hlášky

Informácie

Podpora

Kontakt