Kokiskashop.hu felület

Ez a szakasz dokumentálja az API-t a mi oldalunkon. Bármely szolgáltatás hívásakor szükséges a felhasználói név és jelszó mezők feltüntetése. Ellenkező esetben a kérés elutasításra kerül. Szolgáltatások kivonata beleértve a bejövő és kimenő paramétereket, lehetséges hibás helyzeteket és példákat:

API hívás összetétele a következő: https://www.kokiskashop.hu/api/heureka/1/:szolgáltatás/:akció, ahol a :szolgáltatás jelzi a követelmény hatáskörének a területét és az :akció a már konkrét kérést. A szolgáltatások leírásában a :szolgáltatás mindig a dőlt vonal előtt és az :akció a dőlt vonal után helyezkedik el.

Amennyiben a hívás sikeres, a válasz tartalmazza a 200 kód- ot. Ellenkező esetben a bejelentett hibakód 404 és hibajelentés látható.

Figyelmeztetés:
Az API megvalósításakor (főleg rendelés elküldése) mindig ellenőrizze a választott szállítási mód elérhetőségét payment/delivery szolgáltatás segítségével. Előfordulhat, hogy a kosárban elhelyezett termékek valamelyikét a választott futárszolgálat nem kézbesíti. Tipikus szituáció a felső súlyhatár. A payment/delivery szolgáltatás felkínálja Önnek a kiválasztott termék összes kiszállítási lehetőségeit és árait, beleértve a támogatott fizetési lehetőségeket is. A szolgáltatás hívásával a rendelés elküldéséhez szükséges delivery_id és payment_id- re is szert tesz. Automatikus elutasításra kerülnek azok a megrendelések, melyek érvénytelen delivery_id-t vagy payment_id-t tartalmaznak.

API elérhetőség
Igyekszünk fenntartani a maximális elérhetőséget, azonban probléma merülhet fel és nem lesz lehetőség a rendelés felvételére. Ilyen esetben programozott megoldással rendelkezne, mely a későbbiekben újra küldené a megrendelést.

Az adatok validációja
Minden lekérdezésnél szükséges a felhasználói név és jelszó megadása. Ez a termékek elérhetőségére és a szállítási módra is vonatkozik. Helyes belépési adatok hiányában minden kérés el lesz utasítva. Leggyakoribb problémák az order/send szolgáltatás használatakor lépnek fel, mikor a customer részben hiányzik a parametr firstname vagy a surname. Szükséges mindkettőt feltüntetni. Az utcanév és házszám elkülönítése is további fontos tényező (a futárcégek megkövetelik külön-külön az adatokat).

Kizárólag a payment/delivery szolgáltatás hívásával kaphat fizetési és szállítási Id-t. Szállítási Id esetében megtalálható a szállítási feed elemeiben. Helyes Id-t sehol máshol nem talál.

A példákban felhasznált összes adat kizárólag szemléltető jellegű.

GET products/availability

Aktuális adatok a kért termékekről. Raktári elérhetőség ellenőrzése, kiszállítás időtartama, árak és nevek.

Módszer: 

GET

Paraméterek:

  • products - array - a termék-mező tetszőleges számú tételt tartalmazhat
    • id - integer - egyedi termékazonosító, a feedben ID-vel jelölve
    • count - integer - a termékek kért darabszáma
  • login - string - felhasználó neve a belépéshez
  • password - string - felhasználó jelszava a belépéshez (mint plaintext vagy hash algoritmus "sha256")

Válasz:

  • products - array - a termék-mező tetszőleges számú tételt tartalmazhat
    • id - integer - egyedi termékazonosító, a feedben ID-vel jelölve
    • available - boolean - jelzi a termék elérhetőségét - elérhető: true, nem elérhető: false. (A false megjegyzés PHP-ban gyakran 0-ként van említve, NULL vagy üres string)
    • count - integer - elérhető darabszám
    • delivery - integer|string - napok száma a szállításig (0 - szállítás 24 órán belül, 1 - 1 nap a szállításig,...), amennyiben ez az adat hiányzik, hozzávetőleges információ lett feltüntetve (5 napon belül, kérésre,..)
    • name - string - a termék teljes neve
    • price - float - 1 db ára ÁFÁ-val
    • priceTotal - float - az összes db ára ÁFÁ-val (ár x darabszám)
  • priceSum - float - teljes ár az összes termékért

Példa:
	 
< ?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.hu/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] => 6 személyes sátor 
            [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

Szállítási és fizetési lehetőségek. Például a megrendelés kiszállítható és kiegyenlíthető utánvéttel vagy banki előreutalással. Az ár az aktuális árlistától és a termék súlyától függ. Biztos lehet abban, hogy az ár megegyezik a termék összsúlyával.

Módszer: 

GET

Paraméterek:

  • products - array - a termék-mező tetszőleges számú tételt tartalmazhat
    • id - integer - egyedi termékazonosító, a feedben ID-vel jelölve
    • count - integer - a termékek kért darabszáma
  • login - string - felhasználó neve a belépéshez
  • password - string - felhasználó jelszava a belépéshez (mint plaintext vagy hash algoritmus "sha256")

Válasz:

  • transport - array - a termék kiszállítása (GLS, személyes átvétel,...)
    • id - integer - egyedi szállítási azonosító
    • type - integer - szállítás módja
    • name - string szállítás neve
    • price - float - a kiszállítás ára ÁFÁ-val
    • description - string - kiegészítő információ (pl.: 2 kg-ig,...)
  • payment - array - fizetési lehetőségek (például utánvét és annak ára)
    • id - integer - egyedi fizetési azonosító
    • type - integer - fizetés módja
    • name - string fizetés neve
    • price - float - a fizetés ára ÁFÁ-val
  • binding - array - fizetés és szállítás közötti kapcsolat. Feltünteti például, hogy utánvét a GLS-nél 429 Ft felár ellenében...
    • id - integer - kapcsolat azonosító
    • transportId - integer - id szállítási mód
    • paymentId - integer id fizetési mód
Példa
< ?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.hu/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] => személyes átvétel Karlovy Vary 
            [description] => Stráň 3, 360 01 Karlovy Vary - Sadov, Csehország 
            [type] => 1 
            [price] => 0 ) 
        [1] => Array ( 
            [id] => 6 
            [name] => GLS 
            [description] => kiszállítás 48 órán belül (munkanapokon) 
            [type] => 3 [price] => 399 ) 
    ) 
    [payment] => Array ( 
        [0] => Array ( 
            [id] => 1 [type] => 0 
            [price] => 0 
            [name] => készpénz ) 
        [1] => Array ( 
            [id] => 3 
            [type] => 0 
            [price] => 0 
            [name] => előreutalás ) 
        [2] => Array ( 
            [id] => 2 
            [type] => 0 
            [price] => 45 
            [name] => utánvét ) 
    ) 
)

GET order/status

Visszajelzi a megrendelés állapotát

Módszer: 

GET

Paraméterek:

  • order_id - integer - megrendelés azonosító a Kokiskashop.hu-n. Az információ visszajelzésre kerül rendelés létrehozásakor a következő szolgáltatással order/send
  • login - string - felhasználó neve a belépéshez
  • password - string - felhasználó jelszava a belépéshez (mint plaintext vagy hash algoritmus "sha256")

Válasz:

  • order_id - integer - megrendelés azonosító a Kokiskashop.hu-n. Az információ visszajelzésre kerül rendelés létrehozásakor a következő szolgáltatással order/send
  • status - integer - a megrendelés állapota (0 - szállításra került (a bolt elküldte a megrendelést az ügyfélnek), 1 - a megrendelés elküldve a boltnak, 2 - a megrendelés csak részben teljesült, 3 - megrendelés visszaigazolás (a bolt a megrendelést fogadta és visszaigazolja, hogy feldolgozásra került), 4 - törölve a bolt oldaláról (a bolt lemondta a megrendelést), 5 - törölve az ügyfél oldaláról (az ügyfél lemondta a megrendelést), 6 - törölve - a megrendelés nem lett kifizetve (az ügyfél nem fizette ki a megrendelést), 7 - visszaküldve 14 napos határidőn belül (az ügyfél visszaküldte a terméket a törvényes, 14 napos határidőn belül), 8 - a megrendelés befejezve a partnernél, 9 - a megrendelés befejezve (az ügyfél kifizette és átvette a megrendelést), 10 - a megrendelés készen áll az átvételre

Példa
< ?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.hu/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

Megrendelés elküldése a boltba. Az elküldés pillanatában a megrendelt termék leblokkolódik, így a vásárló biztos lehet abban, hogy a megrendelt mennyiségben kapja a terméket.

A szolgáltatás fogadja a deliveryId és paymentId paramétereket, melyek a fizetési lehetőségek egyedi azonosítójaként lettek jelölve. A payment/delivery szolgáltatás segítségével értéket kap konkrét termékcsomagról. Bevezetésük nélkül lehetetlen létrehozni a megrendelést és nem várható el a végösszeg pontos kimutatása sem (a szállítási költség függ a termékek súlyától).

Módszer: 

POST

Paraméterek:

  • products - array - a termék-mező tetszőleges számú tételt tartalmazhat položek
    • id - integer - egyedi termékazonosító, a feedben ID-vel jelölve
    • count - integer - a termékek kért darabszáma
    • price - float - az ügyfél által rendelt termék 1 darabjának ára ÁFÁ-val
  • productsTotalPrice - float - a termékek teljes ára - nem tartalmazza a szállítási költségeket
  • customer - array - információk a vásárlóról. A számlán feltüntetésre kerül.
    • firstname - string - keresztnév
    • lastname - string - vezetéknév
    • email - string - email cím
    • phone - string - telofonszám
    • street - string - utca
    • houseNumber - string - házszám
    • city - string - város
    • postCode - string - irányítószám
    • state - string - állam. Preferáljuk teljes formájában, pl: Magyarország (HU vagy HUN helyett)
    • company - string nem kötelező paraméter - a vállalat neve, melyre történik a számlázás. A számlán végül fel lesz tüntetve "Vállalat, keresztnév és vezetéknév"
    • ic - integer nem kötelező paraméter - cégjegyzékszám
    • dic - string nem kötelező paraméter - adószám
  • deliveryAddress - array - szállítási cím. Jelenleg szükséges mindíg feltüntetni
    • firstname - string - keresztnév
    • lastname - string - vezetéknév
    • street - string - utca
    • houseNumber - string - házszám
    • city - string - város
    • postCode - string - irányítószám
    • state - string - állam. Preferáljuk teljes formájában, pl: Magyarország (HU vagy HUN helyett)
    • company - string nem kötelező paraméter - a vállalat neve, a kiszállítás a "Vállalat, keresztnév és vezetéknév"-re történik
  • deliveryId - integer - a választott szállítás azonosítója
  • paymentId - integer - a választott fizetés azonosítója
  • note - string - megjegyzés a rendeléshez, az ügyfél tipikus kérelme vagy közlése. Például: dél körüli szállítást kérek,...
  • login - string - felhasználó neve a belépéshez
  • password - string - felhasználó jelszava a belépéshez (mint plaintext vagy hash algoritmus "sha256")

Válasz:

  • order_id - integer - megrendelés azonosító. Minden további hívásnál felhasználásra kerül, mint pl. order/status vagy order/cancel
  • internal_id - string - belső azonosító. A mi esetünkben azonos az  id_order-el
  • variableSymbol - big integer - variabilis szám (max. 10 számjegy, jelentéktelen nullák nélkül), a megrendelések és fizetések párosítására szolgál.

Példa
< ?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.hu/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

A megrendelés törlése. Használatát fokozott óvatossággal javasoljuk. Megtörténhet akár a számla törlése is.

Módszer: 

PUT

Paraméterek:

  • order_id - integer - megrendelés azonosító a Kokiskashop.hu-n. Az információ visszajelzésre kerül rendelés létrehozásakor a következő szolgáltatással order/send
  • login - string - felhasználó neve a belépéshez
  • password - string - felhasználó jelszava a belépéshez (mint plaintext vagy hash algoritmus "sha256")

Válasz:

  • status - boolean - sikermutató. Amennyiben true, minden rendben történt. Ellenkező esetben az érték false

Példa
< ?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.hu/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

A fizetés állapotának szerkesztése boltunkban. Tipikus felhasználás, ha bankkártyás fizetés lett implementálva és a fizetési információk betöltődnek boltjába.

Módszer: 

PUT

Paraméterek:

  • order_id - integer - megrendelés azonosító a Kokiskashop.hu-n. Az információ visszajelzésre kerül rendelés létrehozásakor a következő szolgáltatással order/send
  • status - integer - kifizetés állapota (1 - fizetve, -1 - nincs fizetve)
  • date - string - a változás időpontja (YYYY-MM-DD)
  • login - string - felhasználó neve a belépéshez
  • password - string - felhasználó jelszava a belépéshez (mint plaintext vagy hash algoritmus "sha256")

Válasz:

  • status - boolean - sikermutató. Amennyiben true, minden rendben történt. Ellenkező esetben az érték false

Példa
< ?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.hu/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 
)

Hibaüzenetek

A megrendelés meghibásodása esetén rendszerünk automatikus e-mailen keresztül elküldi a hibaüzenetet. Példa a hibaüzenetre: Az M0426-os terméknél hibásan lett kitöltve a mennyiség. Hiányzik vagy üres. Az e-mail tartalmazza a hívás pontos időponját, a teljes körű bejövő adatokat, melyeket fogadtunk és végül a hibaüzenetet, miért lett sikertelen az átvitel.

 

BIGtheme.net Joomla 3.3 Templates