Informácie o užívateľovi

Heureka Marketplace - API

API slúži na previazanie nákupného radcu Heureka.sk s obchodmi zapojenými do služby Marketplace.

API má RESTful architektúru a snaží sa využívať všetky možnosti HTTP. Využíva plnohodnotne metódy GET, POST a PUT.
Odpovede na HTTP požiadavky sú vrátené vo formáte JSON.

Komunikácia medzi obchodom a Heurekou môže fungovať obojstranne, preto má API dve časti. Jedna časť je na strane obchodu a druhá na strane Heureky. Sú rovnako dôležité a odporúčame mať implementované obe časti.

API na strane obchodu slúži k získavaniu aktuálnych informácií o ponúkaných produktoch - dostupnosti, možnosti dopravy apod. Druhá časť slúži k tomu, aby obchod mohol posielať Heureke napr. informácie o stave objednávky.

API vyžaduje zabezpečené spojenie pomocou SSL (https). Dôležitá je taktiež rýchlosť odozvy API.

Po novom môžete využiť HCAPI - nástroj určený na jednoduchšie napojenie na Marketplace API.

Changelog

==14.12.2023== - Pridávame nové volanie POST payout-report, na výpis objednávok vo výplate prostriedkov z predaja ==12.09.2023== - Nie je povinne vyžadovaná implementácia všetkých volaní. V administrácii Heureky je možné zadať len využívané API URL. - Číslo objednávky “heureka_id” v metóde POST order/send je novo typu big integer - Metóda GET payment/status sa naďalej nevyužíva - Metóda PUT payment/status sa naďalej nevyužíva - Metóda POST order/note sa naďalej nevyužíva - Metóda POST order/invoice sa naďalej nevyužíva - Typ dopravy 6 - Slovenská pošta - Balík na poštu se nadále nevyužívá. Využijte typ 9 - Dopravcovia poskytovaní cez DepotAPI -> store: { type: 3; id: 2 } - Pre komunikáciu cez API je vyžadované povolenie nových IP adries uvedených na konci tohto manuálu. - V prípade nedostupného ID online platby v payment/delivery sa už nesnažíme id nahradiť ID pre bankový prevod - Zmena stavov objednávok má dané poradie (viď Číselníky na konci manuálu) == 30.11.2022 == - POST order/send - pridaný parameter "originalId" do "deliveryAddress", obsahujúce unikátne ID pobočky podľa oficiálneho zoznamu dopravcov == 8.7.2021 == - POST order/send - změna defaultní adresy při osobním odběru == 23.10.2018 == - POST order/send - odkaz na číselník depotAPI poboček nasměrován na github dokumentaci depotAPI == 2.7.2018 == - POST order/send - bol pridaný nepovinný parameter depotId do deliveryAddress obsahujúci ID pobočky. == 7.10.2016 == - POST order/send - pridaná informácia o darčekoch k zakúpeným produktom.

API Obchodu

Základná štruktúra volania požiadaviek

https://www.example.com/api/:verzia_api:/:oblasť:/:akcia:/

verzia_api - verzia API, ktorá je využívaná (momentálne verzia 1)
oblasť - oblasť volania
akcia - príslušná akcia k oblasti

Pre testovanie vášho API môžete využiť testovacie prostredie, ktoré nájdete v administrácii obchodu v časti Marketplace -> Nastavenie Marketplace API. Po prihlásení do správy e-shopu tu.
Alebo v časti Marketplace -> MP testing tu.

Na stránke si môžete vyskúšať ako Heureka volá vaše API a skontrolovať, či sú vaše odpovede správne.

V Heureka administrácii pod záložkou “Marketplace -> Nastavenie Marketplace API” následne vložte jednotlivé API URL do príslušných polí.

Metódy API

GET products/availability

Metóda vracia aktuálne dáta o požadovaných produktoch.

URL

https://www.exaple.com/api/1/products/availability

Vstupné parametre

products array	pole s produktami
id string	ID produktu (ITEM ID)
count integer	počet objednávaných kusov (vždy väčší než 0)

Štruktúra odpovede

products array	pole s produktami
id string	ID produktu (ITEM ID)
count integer	počet objednávaných kusov (vždy väčší než 0)
available boolean	je produkt dostupný? (false pokiaľ produkt nemožno v žiadnom prípade objednať, inak true)
delivery integer \| string	počet dní do odoslania (číselník), pokiaľ obchod nedisponuje číselnou hodnotou, môže uviesť textovú variantu napr. "na vyžiadanie", "do 2 dní".
name string	názov produktu (max. 255 znakov)
price float	cena tovaru za kus (vrátane DPH a všetkých poplatkov)
related array ^[nepovinné]	súvisiace položky k produktu (Ide o určitú pridanú hodnotu k produktu, ktorá nemá vplyv na cenu.)
title string	popis položky
priceTotal float	celková cena produktu (počet × cena)
priceSum float	celková cena (za všetky produkty)

HTTP požiadavka

Na volanie URL je použitý nástroj cURL.

curl https://www.example.com/api/1/products/availability?products[0][id]=ABC123&products[0][count]=1&products[1][id]=ABC124&products[1][count]=2

Odpoveď

{
    "products":[
    {
        "id": "ABC123",
        "available": true,
        "count": 1,
        "delivery": 0,
        "name": "Diesel Zero Plus Masculine",
        "price": 3.5,
        "related": [
        {
            "title": "Zdarma darčeková taška"
        }
        ],
        "priceTotal": 3.5
        },
        {
            "id": "ABC124",
            "available": true,
            "count": 2,
            "delivery": "na vyžiadanie",
            "name": "Mikrovlnná rúra Ariete-Scarlett 933 nerez",
            "price": 200.00,
            "related": [
            {
                "title": "Vynáška do 5. poschodia zdarma"
            },
            {
                "title": "Prepiska zdarma."
            }
            ],
            "priceTotal": 13
        }
    ],
    "priceSum": 16.5
}

Tovar už obchod nepredáva. Ako má vyzerať odpoveď?

Vráťte v available hodnotu false.

Tovar obchod predáva, ale nevie za ako dlho je schopný tovar dodať. Ako má vyzerať odpoveď?

V available musí byť true a v delivery hodnota -1 alebo iný vhodný textový popis. Všeobecne platí, že čo je v XML feede to musí obchod umožniť kúpiť aj na Heureke.

Zákazník požaduje 3 kusy položky, ale obchod má len dva. Ako má vyzerať odpoveď?

V count uveďte hodnotu 2. Zákazník bude na túto skutočnosť upozornený.

Zákazník požaduje 3 kusy, obchod má 2 skladom a 1 dorazí až za 5 dní. Ako má vyzerať hodnota delivery?

Hodnota delivery musí byť najhoršia možná, teda pokiaľ je obchod schopný dodať všetky 3 kusy, bude hodnota 5.

Zákazník požaduje 1 kus položky, ale obchod má k dispozícii 10. V count teda obchod uvedie 10?

Nie. Hodnota count musí byť max. počet kusov ktoré zákazník požaduje.

GET payment/delivery

Vráti možnosti dopravy a platby. Napr. to, že tovar je možné dodať pomocou Slovenskej pošty, alebo PPL s možnosťou dobierky.

Každý zapojený obchod zašle prostredníctvom API akým spôsobom expeduje tovar zákazníkovi. Jeden z týchto spôsobov si zákazník zvolí. Pokiaľ zákazník zvolí platbu vopred (platba kartou), tak platbu zaisťuje Heureka pomocou služby Adyen. A nezáleží na tom, či obchod takúto platbu podporuje alebo nie.
Pri dobierke, kde je platba na strane obchodu, je situácia iná. Tu Heureka naprosto rešpektuje možnosti obchodu a zobrazí ich tak zákazníkovi. To znamená, že pokiaľ obchod nepodporuje dobierku, nebude zákazníkovi ponúknutá.

V parametri binding obchod určí akým spôsobom je daná platba viazaná na spôsob doručenia. Napr. že "platba v hotovosti pri prevzatí" je viazaná na spôsob doručenia "osobný odber na pobočke v Bratislave".

Obchod nepodporuje platbu kartou

Pokiaľ si zákazník zvolí platbu kartou a obchod tento variant nepodporuje, tak sú zákazníkovi zobrazené všetky spôsoby dopravy nezávisle na väzbách uvedených v binding.

Predpokladá sa, že obchod je po zaplatení tovaru schopný zákazníkovi doručiť tovar všetkými ponúknutými možnosťami.

Identifikácia pobočiek

Parameter store slúži k jasnej identifikácii pobočky, kde si možno vyzdvihnúť objednávku. Rozlišujú sa dva typy a to vlastné pobočky / výdajné miesta obchodu.

Vlastné pobočky musia mať správne ID, ktoré je používané taktiež v rámci XML Dostupnostného feedu. Nájdete ho v administrácii pobočiek. Pre vlastné pobočky ide o Depot ID pre dostupnostný XML súbor.

Parameter store má význam len pri osobných odberoch na pobočkách či výdajných miestach. Pri ostatných možnostiach ich neposielajte.

URL

https://www.example.com/api/1/payment/delivery

Vstupné parametre

products array	pole s produktami
id string	ID produktu (ITEM ID)
count integer	počet objednávaných kusov

Štruktúra odpovede

transport array	doprava
id integer	ID dopravy
type integer	typ dopravy (číselník)
name string	názov dopravy
price float	cena
description string	popis
store	identifikácia pobočky
type integer	typ pobočky / výdajného miesta (číselník)
id integer	ID pobočky pre Osobný odber (z feedu alebo administrácie) alebo ID obchodu ("shopId") / ID dopravca ("shipperId") pre DepotAPI.
payment array	platba
id integer	ID platby
type integer	typ platby (číselník)
name string	názov platby
price float	cena
binding array	pole väzieb medzi dopravou a platbou
id integer	ID väzby
transportId integer	ID dopravy
paymentId integer	ID platby

HTTP požiadavka

Na volanie URL je použitý nástroj cURL.

curl https://www.example.com/api/1/payment/delivery?products[0][id]=ABC123&products[0][count]=1&products[1][id]=ABC124&products[1][count]=2

Odpoveď

{
    "transport": [
    {
        "id": 1,
        "type": 1,
        "name": "PPL",
        "price": 4,
        "description": "Do 1 - 2 pracovných dní."
    },
    {
        "id": 2,
        "type": 1,
        "name": "Slovenská pošta",
        "price": 3.5,
        "description": "Do 2 - 3 pracovných dní."
    },
    {
        "id": 4,
        "type": 2,
        "name": "Osobný odber Lozorno",
        "price": 0,
        "description": "O tom, že je tovar pripravený k odberu Vás budeme ...",
        "store":
         {
            "id": 2020,
            "type": 1
         }
    }],
    "payment":[
    {
        "id": 123,
        "type":1,
        "price": 1,
        "name": "Dobierka Slovenská pošta"
    },
    {
        "id": 200,
        "type":1,
        "price": 1.1,
        "name": "Dobierka PPL"
    },
    {
        "id": 300,
        "type": 3,
        "price": 0.00,
        "name": "Platba kartou"
    },
    {
        "id": 100,
        "type": 2,
        "price": 0.33,
        "name": "Platba pri prevzatí"
    }],
    "binding": [
    {
        "id": 1,
        "transportId": 1,
        "paymentId": 200
    },
    {
        "id": 5,
        "transportId": 1,
        "paymentId": 300
    },
    {
        "id": 2,
        "transportId": 2,
        "paymentId": 123
    },
    {
        "id": 6,
        "transportId": 2,
        "paymentId": 300
    },
    {
        "id": 4,
        "transportId": 4,
        "paymentId": 300
    },
    {
        "id": 7,
        "transportId": 4,
        "paymentId": 100
    }]
}

Na čo slúžia väzby?

Väzby sú dôležité na to, aby sme mohli zákazníkovi správne zobraziť k vybranej platbe dostupné dopravy.

Musí obchod posielať platby kartou a k ním väzby na dopravu, keď sú vo vašej réžii?

Platbu kartou (a ďalšie online platby) zaisťuje Heureka pomocou Adyen, takže by sa mohlo zdať, že nie sú potrebné informácie od vás o platbe kartou. To do istej miery nie je tak. Pokiaľ ich nepošlete nič sa nedeje, my príslušné väzby vygenerujeme sami. Ale pokiaľ ich posielate, tak my vám pri objednávke pošleme konkrétne ID platby a dopravy, ktoré si nakupujúci vybral. Môže si ich teda obchod správne spárovať vo svojom shopsystéme.

Dva kusy položiek má obchod na sklade a môže ich dodať hneď, ale zákazník chce tri kusy, ale ten tretí bude mať obchod až za päť dní. Ako má vyzerať hodnota v delivery?

V hodnote delivery musí byť taká hodnota, za ktorú je obchod schopný dodať kompletnú objednávku. V tomto prípade teda päť.

Ako posielať Slovenskú poštu s dobierkou a bez dobierky?

Je tu nutné rozlišovať dve veci. Slovenská pošta je možnosť dopravy a dobierka je platba, tieto dve veci je nutné spojiť pomocou väzieb. Chybou by bolo keby sa možnosť platby dobierkou alebo predom rozlišovalo v transport.

Ukážka správneho postupu:

{
	"transport": [
	{
	    "id": 1,
	    "type": 1,
	    "name": "Slovenská pošta",
	    "price": 3.50,
	    "description": "Do 1 - 2 pracovných dní."
	}],
	"payment": [
	{
		"id": 1,
		"type": 1,
		"name": "Dobierka"
		"price": 1
	},
	{
		"id": 2,
		"type": 3,
		"name": "Platobná karta",
		"price": 0.00
	}],
	"binding": [
	{
		"id": 1,
		"transportId": 1,
		"paymentId": 1
	},
	{
		"id": 2,
		"transportId": 1,
		"paymentId": 2
	}]
}

GET order/status

Vráti stav objednávky v obchode.

URL

https://www.example.com/api/1/order/status

Vstupné parametre

order_id integer	ID objednávky

Štruktúra odpovede

order_id integer	ID objednávky
status integer	aktuálny stav objednávky (číselník)

HTTP Metódy API

Na volanie URL je použitý nástroj cURL.

curl https://www.example.com/api/1/order/status?order_id=2011101001

Odpoveď

{
    "order_id": 2011101001,
    "status": 0
}

Ako často sa používa táto požiadavka?

Na stav objednávky sa automaticky pýtame niekoľkokrát denne. Obvykle to býva ráno, okolo poludnia a popoludní.

POST order/send

Odoslanie objednávky do obchodu.

Po odoslaní by malo dôjsť v obchode k rezervácii tovaru a začať proces expedície (pokiaľ je objednávka zaplatená alebo je na dobierku).

V prípade osobného odberu od zákazníka povinne vyžadujeme iba polia meno, priezvisko, e-mail a telefónne číslo. Zákazník má možnosť vyplniť svoju fakturačnú adresu, ak tak ale nevykoná, zasielame cez API vo fakturačných údajoch nasledovnú adresu:

Osobný odber
Ulica č. p.: Osobný odber 1
Mesto: Bratislava
PSČ: 81103
Štát: Slovenská republika

Poznámka – význam deliveryId a paymentId

Aby mohol obchod rozoznať akú platbu a dopravu si zákazník vybral sú posielané ich ID, ktoré boli zaslané obchodom v metóde payment/delivery.

Môže sa stať, že obchod v metóde payment/delivery neposiela (obchod ju nepodporuje) napr. platbu pomocou platobnej karty, napriek tomu si ju používateľ môže vybrať, pretože tento variant platby je nezávislý na obchode (zaisťuje ju Heureka). V tomto prípade nie je k dispozícii hodnota pre paymentId. V paymentId tak bude zaslaná hodnota 0. Pokiaľ však už platba s paymentId 0 existuje, bude použité najvyššie dostupné paymentId zvýšené o 1.

Príklady:

Príklad odpovede	paymentId pre bankový prevod	paymentId pre platbu kartou
{ "transport": ..., "payment":[ { "id": 200, "type":1, "price": 33.00, "name": "Dobírka" }, { "id": 300, "type": 2, "price": 10.00, "name": "Platba při převzetí" }], "binding": ... }	0	301
{ "transport": ..., "payment":[ { "id": 200, "type":1, "price": 33.00, "name": "Dobírka" }, { "id": 0, "type": 2, "price": 10.00, "name": "Platba při převzetí" }], "binding": ... }	201	202
{ "transport": ..., "payment":[ { "id": 200, "type":1, "price": 33.00, "name": "Dobírka" }, { "id": 300, "type": 3, "price": 10.00, "name": "Platba kartou" }], "binding": ... }	0	300

Príklad odpovede

paymentId pre bankový prevod

paymentId pre platbu kartou

    {
        "transport": ...,
        "payment":[
        {
            "id": 200,
            "type":1,
            "price": 33.00,
            "name": "Dobírka"
        },
        {
            "id": 300,
            "type": 2,
            "price": 10.00,
            "name": "Platba při převzetí"
        }],
        "binding": ...
    }

301

    {
        "transport": ...,
        "payment":[
        {
            "id": 200,
            "type":1,
            "price": 33.00,
            "name": "Dobírka"
        },
        {
            "id": 0,
            "type": 2,
            "price": 10.00,
            "name": "Platba při převzetí"
        }],
        "binding": ...
    }

201

202

    {
        "transport": ...,
        "payment":[
        {
            "id": 200,
            "type":1,
            "price": 33.00,
            "name": "Dobírka"
        },
        {
            "id": 300,
            "type": 3,
            "price": 10.00,
            "name": "Platba kartou"
        }],
        "binding": ...
    }

300

Výdajné miesta ponúkané dopravcami

Pokiaľ zákazník zvolí dopravu na výdajné miesto zaslané cez DepotAPI je v dodacej adrese vyplnená adresa vybraného výdajného miesta.

Poznámka k významu parametru eLicence

Parameter eLicence označuje, že objednávka obsahuje produkt s elektronickou licenciou - tieto produkty využívajú elektronickú distribúciu, teda nie klasickú dopravu. V prípade, že objednávka neobsahuje produkt s klasickou dopravou, je deliveryId zvolené z najvyššieho deliveryId z metódy GET payment/delivery, ktoré inkrementujeme o 1 (napr. ak je najvyššia deliveryId 5, pre eLicence bude 6)

Url

https://www.example.com/api/1/order/send

Vstupné parametre

products array	objednané produkty
id string	ID produktu (ITEM ID)
count integer	počet kusov
price float	cena, za ktorú zákazník produkt objednal (za kus)
totalPrice float	celková cena (počet kusov x cena)
params array	vybrané parametre
id integer	ID parametra
value string	hodnota parametra
gifts array	Darčeky ponúkané k produktu (z XML)
name string	názov darčeka
shopGiftId string\|null	ID darčeku dodané obchodom v XML
productsTotalPrice float	celková cena za všetky produkty (bez poplatkov za dopravu a platbu!)
heureka_id big integer	interné číslo objednávky v systéme Heureky - pomocou neho môžete identifikovať duplicitne zasielané objednávky
deliveryId integer	ID vybranej dopravy
paymentId integer	ID vybranej platby
deliveryPrice float	cena vybranej dopravy
paymentPrice float	cena vybranej platby
eLicence bool	príznak, či objednávka obsahuje elektronickú licenciu (a teda aj el. distribúciu)
note string	poznámka k objednávke
paymentOnlineType array	typ online platby, v prípade "offline" platby sa parameter neposiela
title string	názov platby
id integer	ID platby
customer array	nakupujúci (fakturačná adresa)
firstname string	krstné meno
lastname string	priezvisko
email string	e-mail
phone string	telefón
street string	ulica a číslo popisné
city string	mesto
postCode string	PSČ
state string	štát
company string	názov firmy
ic integer	IČ
dic string	DiČ
deliveryAddress array	nakupujúci (dodacia adresa)
firstname string	krstné meno
lastname string	priezvisko
street string	ulica a číslo popisné
city string	mesto
postCode string	PSČ
state string	štát
company string	názov firmy
depotId integer ^[deprecated]	ID pobočky - Heureka neručí za to, že ID depotu, ktoré od nás cez API obdržíte, je totožné s tým, ktoré dopravca zasiela priamo obchodu.
originalId string	Unikátne ID pobočky výdajného miesta/boxu podľa oficiálneho zoznamu dopravcov.

Štruktúra odpovede

order_id integer	číslo objednávky - s týmto číslom ďalej komunikujeme cez API
internal_id string	interné číslo objednávky v obchode (typicky to ktoré uvádzate zákazníkovi na faktúre)
variableSymbol big integer	variabilný symbol (bez nevýznamných núl, max. 10 čísel), bude slúžiť k spárovaniu platieb pri vybíjaní kreditu

HTTP požiadavka

Na volanie URL je použitý nástroj cURL.

curl -d "products[0][id]=ABC123&products[0][count]=1&products[0][price]=100&products[0][totalPrice]=100&products[0][gifts][0][name]=darek&products[0][gifts][0][shopGiftId]=drk1&customer[firstname]=Jan&customer[lastname]=Novak&customer[street]=Jiraskova%209&customer[phone]=728000000&customer[city]=Jablonec&customer[company]=&customer[postCode]=46601&customer[state]=%C4%8Cesk%C3%A1%20republika&customer[email][email protected]&deliveryAddress[firstname]=Jan&deliveryAddress[lastname]=Kos&deliveryAddress[street]=Liberecka%20999&deliveryAddress[city]=Jablonec&deliveryAddress[company]=&deliveryAddress[postCode]=46601&deliveryAddress[state]=%C4%8Cesk%C3%A1%20republika&deliveryAddress[note]=Poznámka%20TEST%20Heureka&deliveryId=100&paymentId=203&productsTotalPrice=500&paymentOnlineType[title]=Testovací%20online%20platba&paymentOnlineType[id]=1&deliveryPrice=100&paymentPrice=30.20&heureka_id=7864287" https://www.example.com/api/1/order/send

Odpoveď

{
    "order_id": 2011101001,
    "internal_id": "HRK-2012-0001",
    "variableSymbol": 1234567890
}

Čo sa stane, keď sa nepodarí odoslať objednávku?

Objednávky sú odesielané pomocou fronty. To znamená, že po vytvorení zákazníkom sa dáta uložia do databázy do fronty a objednávka sa odošle. Pokiaľ nie je vrátené číslo objednávky, tak je to považované za neúspešný pokus a objednávka sa po chvíli pošle znovu. Celkovo sa to opakuje 5 krát, potom sú neodoslané objednávky riešené individuálne.

Môže obchod objednávku odmietnuť?

Nemalo by sa to stávať, pretože všetko čo Heureka ponúka má obchod uvedené v XML feede a teda to predáva. Samozrejme môže sa stať, že dôjde k oneskoreniu medzi zistením dostupnosti a odoslaním objednávky, ale i v tomto prípade by mal obchod objednávku prijať a potom so zákazníkom vyriešiť túto skutočnosť individuálne.

PUT order/cancel

Nastavenie objednávky na storno

K stornu objednávky dochádza len výnimočne, tak aby nedochádzalo k problémom pri expedícii.

Url

https://www.example.com/api/1/order/cancel

Vstupné parametre

order_id integer	ID objednávky
reason integer	dôvod storna (stav objednávky 4-6 z číselníku)

Štruktúra odpovede

status boolean	true došlo k stornu, inak false

HTTP požiadavka

Na volanie URL je použitý nástroj cURL.

curl -X PUT -d "order_id=123&reason=6" https://www.example.com/api/1/order/cancel

Odpoveď

{
    "status": true
}

žiadne otázky

PUT payment/status

Toto volanie je nepovinné a bude v budúcnosti zrušené! Metóda sa teraz volá vždy, keď zákazník vytvorí objednávku s platbou online, ktorú zaisťuje Heureka pomocou platobného poskytovateľa Adyen. Kým sa v poslednom kroku nákupného procesu zákazníkovi nepodarí úspešne zaplatiť, objednávka nie je vytvorená!

Url

https://www.example.com/api/1/payment/status

Vstupné parametre

order_id integer	ID objednávky
status signed integer	stav platby (číselník)
date string	dátum vykonania platby (YYYY-MM-DD)

Štruktúra odpovede

status boolean	podarilo sa nastaviť stav?

HTTP požiadavka

Na volanie URL je použitý nástroj cURL.

curl -X PUT -d "order_id=123&status=1&date=2012-12-30" https://www.example.com/api/1/payment/status

Odpoveď

{
    "status": true
}

žiadne otázky

API Heureka

Základný tvar URL

https://ssl.heureka.sk/api/cart/:API_kľúč:/:verzia_api:/:metoda:/:funkcia:

Kľúč API pre prichádzajúce hovory je váš unikátny identifikátor, ktorý sa používa na autentizáciu jednotlivých volaní do systému Heureka Marketplace. Toto pole je povinné a kľúč nájdete v Heureka administrácii pod záložkou “Marketplace -> Nastavenie Marketplace API”.

Možnosť testovania

Pri každej metóde je uvedený príklad použitia API. Príkaz pomocou cURL je možné rovno vykonať. A možno ho používať pre svoje interné testovanie.

API vracia vygenerované dáta (často náhodne). Cieľom testovania by mala byť štruktúra, a nie samotné dáta.

Upozornenie: URL adresa v príklade má trochu iný tvar než základný tvar.

Metódy API

GET payment/status [deprecated]

Táto metóda sa už nepoužíva!

Url

https://ssl.heureka.sk/api/cart/:APIkľúč:/1/payment/status/

Vstupné parametre

order_id integer	ID objednávky

Štruktúra odpovede

order_id integer	číslo objednávky
status signed integer	stav platby (číselník)
date string	dátum poslednej zmeny stavu (YYYY-MM-DD)

HTTP požiadavka

curl https://api.heureka.sk/cart/validate/1/payment/status?order_id=123

{
    "order_id": 123,
    "status": 1
    "date": "2012-12-24"
}

žiadne otázky

PUT order/status

Nastavenie stavu objednávky na Heureke.

Je dôležité, aby každá zmena objednávky bola prenesená späť do Heureky. Len tak je možné zákazníkom zobraziť, v ktorom stave sa nachádza ich objednávka.

Je daná postupnosť stavov, kedy nie je možné zmeniť stav z jednej úrovne o úroveň nižšiu. Pre presné zobrazenie postupnosti sa pozrite na zápis v Stav objednávok.

Url

https://ssl.heureka.sk/api/cart/:APIkľúč:/1/order/status/

Vstupné parametre

order_id integer	ID objednávky
status integer	stav objednávky (číselník)
transport array ^[nepovinné]	informácie o expedícii - v prípade, že sú k dispozícii
tracking_url string	web, kde je možné sledovať zásielku smerujúcu k zákazníkovi
note string	poznámka k expedícii
expectDelivery string	predpokladaný dátum expedície (YYYY-MM-DD)

Štruktúra odpovede

status boolean	true pokiaľ bolo všetko správne nastavené

HTTP požiadavka

curl -X PUT -d "order_id=123&status=10&transport[tracking_url]=http://www.exmaple.com/?id=101010&transport[expectDelivery]=2013-01-10" https://api.heureka.sk/cart/validate/1/order/status

Odpoveď

{
    "status": true
}

žiadne otázky

PUT payment/status [deprecated]

Táto metóda sa už nepoužíva!

Nastavenie stavu platby na Heureke.

Táto metóda slúži k nastaveniu platby pri dobierke alebo platbe v hotovosti na pobočke obchodu.

Url

https://ssl.heureka.sk/api/cart/:APIkľúč:/1/payment/status/

Vstupné parametre

order_id integer	ID objednávky
status signed integer	stav platby (číselník)
date string	dátum zmeny stavu

Štruktúra odpovede

status boolean	true - pokiaľ bolo všetko správne nastavené

HTTP požiadavka

curl -X PUT -d "order_id=123&status=1&date=2013-01-10" https://api.heureka.sk/cart/validate/1/payment/status

Odpoveď

{
    "status": true
}

žiadne otázky

GET order/status

Informácie o stave objednávky a internom čísle objednávky na Heureke.

Url

https://ssl.heureka.sk/api/cart/:APIkľúč:/1/order/status/

Vstupné parametre

order_id integer	ID objednávky

Štruktúra odpovede

order_id integer	ID objednávky
status integer	stav objednávky (číselník)
internal_id string	interné číslo objednávky v obchode (typicky to, ktoré uvádzate zákazníkovi na faktúre)
heureka_id integer	interné číslo objednávky v systému Heureky (s týmto číslom komunikujeme so zákazníkom)

HTTP požiadavka

curl https://api.heureka.sk/cart/validate/1/order/status?order_id=1234

Odpoveď

{
    "order_id": 123,
    "status": 1,
    "internal_id": 8100000630,
    "heureka_id": 9782212982398
}

žiadne otázky

GET stores

Informácie o pobočkách / výdajných miestach, ktoré má obchod uložené na Heureke.

Slúži k nastaveniu store v GET payment/delivery.

Url

https://ssl.heureka.sk/api/cart/:APIkľúč:/1/stores/

Vstupné parametre

žiadne

Štruktúra odpovede

id integer	ID pobočky / výdajného miesta
type integer	typ pobočky / výdajného miesta (číselník)
name string	názov
city string	umiestnenie

HTTP požiadavka

curl https://api.heureka.sk/cart/validate/1/stores

Odpoveď

[
    {
        "id": 390,
        "type": 1,
        "name": "Pobočka na námestí",
        "city": "Košice"
    },
    {
        "id": 40,
        "type": 2,
        "name": "Zásielkovňa Bratislava",
        "city": "Bratislava"
    }
]

žiadne otázky

GET shop/status

Informácie o aktivácii obchodu v Heureka Marketplace.

Slúži k zisteniu, či je obchod spustený v Marketplace alebo nie. Pokiaľ je Marketplace vypnutý z dôvodu chyby v API alebo nejakej procesnej chyby, je to uvedené v parametri message.

Informácie o aktivácii / deaktivácii sú vždy na 30 minút uložené vo vyrovnávacej pamäti (cache). Pokiaľ testujete stav obchodu pomocou cronu zvoľte interval 30 minút a viac.

Url

https://ssl.heureka.sk/api/cart/:APIkľúč:/1/shop/status/

Vstupné parametre

žiadne

Štruktúra odpovede

status boolean	true pokiaľ je obchod zapnutý
error array	informácie o prípadnej chybe, pokiaľ je obchod aktívny je pole prázdne
message string	text chyby
created string	čas kedy bol obchod deaktivovaný (vo formáte YYYY-MM-DD HH:MM:SS)

HTTP požiadavka

curl https://api.heureka.sk/cart/validate/1/shop/status

Odpoveď

{
    "status": false,
    "error": {
        "message": "Odozva api je väčšia ako 5 sekúnd.",
        "created": "2012-09-21 19:11:01"
    }
}

žiadne otázky

POST order/note [deprecated]

Táto metóda sa už nepoužíva!

Zaslanie poznámky, ktorú obchod vytvoril pri procese odbavovania objednávky.

Tieto poznámky sa zobrazujú zákazníkovi pri objednávke v jeho profile.

Url

https://ssl.heureka.sk/api/cart/:APIkľúč:/1/order/note

Vstupné parametre

order_id integer	ID objednávky
note string	text poznámky (max. 1000 znakov)

Štruktúra odpovede

status boolean	true - pokiaľ sa poznámka uložila

HTTP požiadavka

curl -d "order_id=123&note=Testovaci%20poznámka" https://api.heureka.sk/cart/validate/1/order/note

Odpoveď

{
    "status": true
}

žiadne otázky

POST order/invoice [deprecated]

Táto metóda sa už nepoužíva!

Zaslanie faktúry (dokladu) k objednávke.

Obchody, ktoré posielajú faktúry zákazníkom v elektronickej podobe, ju musia poslať taktiež Heureke, tak aby ich bolo možné opätovne poslať alebo umožniť ich stiahnutie v prehľade objednávok.

Maximálna veľkosť súboru s faktúrou je 3 MB a súbor musí byť v PDF.

Táto metóda predpokladá multipart data v parametri file. POST požiadavka by mal mať nastavený Content-type na multipart / form-data.

Url

https://ssl.heureka.sk/api/cart/:APIkľúč:/1/order/invoice

Vstupné parametre

order_id integer	ID objednávky
invoice multipart data	faktúra

Štruktúra odpovede

status boolean	true faktúra sa uložila

HTTP požiadavka

curl -X POST -F "[email protected]" -F "order_id=123" https://api.heureka.sk/cart/validate/1/order/invoice

Opoveď

{
    "status": true
}

žiadne otázky

POST payout-report

Vráti zoznam objednávok v konkrétnej výplate.

Url

https://ssl.heureka.sk/api/cart/:APIkľúč:/1/payout-report

Vstupné parametre

day string	Dátum výplaty vo formáte YYYY-MM-DD

Štruktúra odpovede

V odpovedi nájdete text/csv. Dáta sú oddelené bodkočiarkou (;). Súbor obsahuje nasledujúce stĺpce:

Číslo objednávky
Dátum objednávky
Typ
Referenčné číslo
Hrubá cena produktov
Poplatok za dopravu
Hrubá provízia
Celková suma nákupu
Celková suma znížená o províziu
Variabilný symbol
Internal ID

HTTP požiadavka

curl -X 'POST' 'https://ssl.heureka.sk/api/cart/:APIkľúč:/1/payout-report' -H 'accept: text/csv' -H 'Content-Type: application/json' -d '{"day": "2023-08-28"}'

Opoveď

"Číslo objednávky";"Dátum objednávky";Typ;"Referenčné číslo";"Hrubá cena produktov";"Poplatok za dopravu";"Hrubá provízia";"Celková suma nákupu";"Celková suma znížená o províziu";"Variabilný symbol";"Internal ID"
8311418522;"2023-07-17 16:10:18";Pripisovanie;;24;0;3,19;24;20,81;2023000007;2023000007

Aký je dátum pre výplaty?

Výplaty sú spracované vždy v pondelok, pokiaľ je na virtuálnom účte dostupná kladná čiastka na vyplatenie.

Odpovede pri chybe

Pri chybe alebo pri nejakej neočakávanej situácii je nutné vracať niektorý z chybových stavových kódov protokolu HTTP. Teda kódy rady 3xx, 4xx alebo 5xx.

Pri chybe je dobré poslať čo sa stalo v tvare:

{
    "id": 22, // identifikátor chyby
    "msg": "Produkt nie je možné objednať.",
}

Číselníky

Stav objednávky

id	krátky názov stavu	popis
0	Prebieha	objednávka vyexpedovaná (obchod odoslal objednávku zákazníkovi)
1	Nový	objednávka odoslaná do obchodu
3	Nový	objednávka potvrdená (obchod objednávku prijal a potvrdzuje, že ju začína spracovávať)
4	Zrušené	storno z pohľadu obchodu (obchod stornoval objednávku)
5	Zrušené	storno z pohľadu zákazníka (zákazník sa rozhodol stornovať objednávku)
6	Zrušené	storno - objednávka nebola zaplatená (zákazník nezaplatil za objednávku)
7	Vrátené	vrátené v 14 dňovej lehote (zákazník vrátil tovar v zákonnej 14 dňovej lehote)
8	Nový	objednávka bola dokončená na Heureke (objednávka bola správne dokončená na Heureke)
9	Dokončené	objednávka dokončená (zákazník zaplatil a prevzal objednávku)
10	Prebieha	objednávka pripravená na vyzdvihnutie (objednávka je pripravená na osobný odber na pobočke)
11	Prebieha	vyexpedované na externé výdajné miesto (napr. Zásielkovňa)

Zmena stavov je obmedzená na nasledujúce možnosti:

východiskový stav	povolená zmena
8 - Nový	1 - Nový
1 - Nový	3 - Nový, 0, 10, 11 - Prebieha, 9 - Dokončené, 4, 5, 6 - Zrušené, 7 - Vrátené
3 - Nový	0, 10, 11 - Prebieha, 9 - Dokončené, 4, 5, 6 - Zrušené, 7 - Vrátené
0, 10, 11 - Prebieha	9 - Dokončené, 4, 5, 6 - Zrušené, 7 - Vrátené

V prípade dokončenej objednávky (stav 9) prípadne stornovanej objednávky (stavy 4, 5, 6) už nie je možné stav zmeniť. V prípade potreby kontaktujte našu podporu, ktorá zmenu vykoná.

Ideálna schéma úspešného objednávkového procesu:

Stavy je možné preskakovať, musí však zachovať postup, viď vyššie.

Schéma objednávkového procesu

Stav platby

1	zaplatené
-1	nezaplatené

Skladová dostupnosť

0	skladom, expedované do 24 hodín
1	1 deň do expedície
2	2 dni do expedície
3	3 dni do expedície
	...
n	n dní do expedície
-1	tovar je nedostupný

Typ platby

1	dobierka
2	v hotovosti pri osobnom prevzatí
3	online platba (platobná karta, Google Pay, ...)
4	prevod na účet

Typ dopravy

1	osobný odber
2	Slovenská pošta
3	špedičná služba (DPD, DHL, ...)
4	expresné dodanie
5	špeciálna doprava
9	Dopravcovia poskytovaní cez DepotAPI

Typ pobočiek / výdajných miest

1	interná pobočka / výdajné miesto obchodu
3	Výdajné miesto dopravcu z DepotAPI

Seznam dopravců skrze DepotAPI

Zoznam dopravcov s ID je verejne cez API, ktoré nájdete na githubu:
https://api.heureka.sk/depot-api/v1/delivery-places/getshippers

Dátové typy

(unsigned) integer	kladné celé číslo (4 bajtové), rozsah: 0 až 4294967295 (napr. 1, 2, 20202)
signed integer	celé číslo (4 bajtové), rozsah: -2147483648 až 2147483647 (napr. 1, 2, -2, 20202)
(unsigned) big integer	kladné celé číslo (8 bajtové), rozsah 0 až 18446744073709551615 (napr. 1, 2, 9223372036854775807)
float	desatinné číslo s desatinnou bodkou (napr. 12.90, 999.99)
string	reťazec
bool	logický dátový typ (true alebo false)

Zabezpečenie komunikácie

prístup k API majú len zariadenia zo zvoleného IP rozsahu
pre zabezpečenie zo strany obchodu je možné omedziť prístup pre rozsahy serverov Heureky, ktoré nájdete v nasledujúcom Zozname IP adries.
API vyžaduje HTTPS
každý obchod má unikátnu URL adresu

Rýchlosť odozvy

Všeobecne platí, že čím kratšia odozva tým lepšie.

API na strane Heureky odpovedá do pár desiatok milisekúnd. Takúto odozvu požadujeme aj od obchodov.

Pamätajte, že na rýchlosti API záleží spokojnosť zákazníkov. Nikto nechce byť pri nákupe rušený čakaním. Rýchle odozvy znamenajú viac nákupov!

V súčasnej dobe sú pomalé odozvy API najčastejšou príčinou pozastavenia služby Heureka Marketplace.

Prosíme, myslite na to.

Podpora

V prípade, že máte problém s pripojením na API Marketplace, obráťte sa, prosím, na [email protected].