Informace o uživateli

Heureka Marketplace - API

API slouží k provázání nákupního rádce Heureka.cz s obchody zapojenými do služby Marketplace.

API má RESTful architekturu a snaží se využívat všech možností HTTP. Využívá plně metod GET, POST a PUT.
Odpovědi na HTTP požadavky jsou vraceny ve formátu JSON.

Jelikož komunikace mezi obchodem a Heurekou musí fungovat oboustraně, má API dvě části. Jedna část je na straně obchodu a druhá na straně Heureky. Jsou stejně důležité a je nutné mít implementované obě dvě části.

API na straně obchodu slouží k získávání aktuálních informací o nabízených produktech - dostupnosti, možnost dopravy apod. Druhá část slouží k tomu, aby obchod mohl posílat Heurece např. informace o stavu objednávky nebo si zjišťovat zda byla připsána platba.

API vyžaduje zabezpečené spojení pomocí SSL (https). Důležitá je také rychlost odezvy API.

Nově můžete využít HCAPI - nástroj vytvořený pro snadnější napojení na Marketplace API.

Changelog

== 30.11.2022 == - POST order/send - přidán parametr "originalId" do "deliveryAddress", obsahující unikátní ID pobočky podle oficiálního seznamu dopravce == 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 - byl přidán nepovinný parametr depotId do deliveryAddress obsahující ID pobočky. == 7.10.2016 == - POST order/send - přidána informace o dárcích k zakoupeným produktům == 10.5.2018 == - Zasílání výdejen od dopravců přes API - DepotAPI == 1.12.2015 == Nová platební metoda PayU - rozšířeny platební metody o UniCredit Bank == 27.5.2015 == API Obchodu - POST order/send - přidán parametr "heureka_id" - interní číslo objednávky v systému Heureky == 3.4.2015 == API Obchodu - POST order/send - přidán parametr "eLicence" - příznak pro elektronickou licenci v objednávce == od 1.1.2015 == - přibývá nový rozsah IP adres pro komunikaci s API obchodů == 3.12.2014 == - upřesnení datových typů integer a big integer (jsou implicitně unsigned) == od 10.11.2014 == - GET order/status - přidán parametr "heureka_id" - interní číslo objednávky v systému Heureka == od 5.12. 2013 == Nové platební metody PayU - rozšířeny platební metody o ČSOB, PaySec a ERA == od 1.3. 2013 == - PUT order/cancel - přidán parametr "reason" - důvod storna === 4. 2. 2013 === API Obchodu - POST order/send - přidán parametr "totalPrice" - cena produktu x počet kusů - POST order/send - přidán parametr "deliveryPrice" - cena dopravy - POST order/send - přidán parametr "paymentPrice" - cena za platbu === 19. 8. 2012 === API obchod - POST order/send - v parametru productsTotalPrice se posílá celková cena objednaného zboží API Heureka - GET stores - možnost získat ID's poboček vedených na Heurece === 2. 7. 2012 === API obchod - POST order/send - podpora pro typ dopravy: Česká Pošta - Balík Na poštu - GET payment/delivery - podpora pro typ dopravy: Česká Pošta - Balík Na poštu ==== 1. 6. 2012 ==== API Obchod - POST order/send - nové parametry variabilní symbol a interní ID objednávky. Nový parametr paymentOnlineType (od 11.6.). - GET payment/delivery - nový parametr store pro identifikaci poboček. API Heureka - GET order/status - nová metoda, která vrací interní informace o objednávce - POST order/note - zaslání procesních poznámek k objednávce - PUT order/status - informování o předpokládáném času doručení objednávky - POST order/invoice - zasílání zákaznických faktur Nové stavy objednávky - Byly rozšířené stavy objednávky. Datové typy -big integer - 8 bajtový integer, kvůli bankovnímu variabilnímu symbolu, který může mít až 10 číslic.

API Obchodu

Základní struktura volání požadavků

https://www.example.com/api/:verze_api:/:oblast:/:akce:/

verze_api - verze API, která je využívána (momentálně verze 1)
oblast - oblast volání
akce - příslušná akce k oblasti

Pro testování vašeho API můžete využít testovací prostředí, které naleznete v administraci obchodu v záložce Marketplace -> MP testing. Po přihlášení do správy e-shopu zde.

Na stránce si lze vyzkoušet jak Heureka volá vaše API a zkontrolovat, zda vaše odpovědi jsou správné.

Metody API

GET products/availability

Metoda vrací aktuální data o požadovaných produktech.

URL

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

Vstupní parametry

products array	pole s produkty
id string	ID produktu (ITEM ID)
count integer	počet objednávaných kusů (vždy větší než 0)

Struktura odpovědi

products array	pole s produkty
id string	ID produktu (ITEM ID)
count integer	počet objednávaných kusů (vždy větší než 0)
available boolean	zda je produkt dostupný (false pokud produkt nelze v žádném případě objednat, jinak true)
delivery integer \| string	počet dní k odeslání (číselník), pokud obchod nedisponuje číselnou hodnotou, může uvést textovou variantu např. "na dotaz", "do 2 dnů".
name string	název produktu (max. 255 znaků)
price float	cena zboží za kus (vč. DPH a všech poplatků)
related array ^[nepovinné]	související položky k produktu (Jedná se o určitou přidanou hodnotu k produktu, která nemá vliv na cenu.)
title string	popis položky
priceTotal float	celková cena pro produkt (počet × cena)
priceSum float	celková cena (za všechny produkty)

HTTP požadavek

K volání URL je využito nástroje 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

Odpověď

{
    "products":[
    {
        "id": "ABC123",
        "available": true,
        "count": 1,
        "delivery": 0,
        "name": "Diesel Zero Plus Masculine",
        "price": 100.00,
        "related": [
        {
            "title": "Zdarma dárková taška"
        }
        ],
        "priceTotal": 100.00
        },
        {
            "id": "ABC124",
            "available": true,
            "count": 2,
            "delivery": "na dotaz",
            "name": "Mikrovlnná trouba Ariete-Scarlett 933 nerez",
            "price": 200.00,
            "related": [
            {
                "title": "Vynáška do 5. patra zdarma"
            },
            {
                "title": "Propiska zdarma."
            }
            ],
            "priceTotal": 400.00
        }
    ],
    "priceSum": 500.00
}

Zboží již obchod neprodává. Jak má vypadat odpověď?

Vraťte v available hodnotu false.

Zboží obchod prodává, ale neví za jak dlouho je schopen zboží dotat. Jak má vypadat odpověď?

V available musí být true a v delivery hodnota -1 nebo jiný vhodný textový popis. Obecně platí, že co je v XML feedu to musí obchod umožnit koupit i na Heurece.

Zákazník požaduje 3 kusy zboží, ale obchod má pouze dva. Jak má vypadat odpověď?

V count uveďte hodnotu 2. Zákazník na tuto skutečnost bude upozorněn.

Zákazník požaduje 3 kusy, obchod má 2 skladem a 1 dorazí až za 5 dní. Jak má vypadat hodnota delivery?

Hodnota delivery musí být nejhorší možná, tedy pokud je obchod schopen dodat všechny 3 kusy, bude hodnota 5.

Zákazník požaduje 1 kus zboží, ale obchod má k dispozici 10. V count tedy obchod uvede 10?

Ne. Hodnota count musí být max. počet kusů které zákazník požaduje.

GET payment/delivery

Vrátí možnosti dopravy a platby. Např. to, že zboží lze dodat pomocí České pošty nebo PPL s možností dobírky.

Každý zapojený obchod zašle prostřednictvím API jakým způsobem expeduje zboží zákazníkovi. Jeden z těchto způsobů si zákazník zvolí. Pokud zákazník zvolí platbu kartou, tak platbu zajišťuje Heureka pomocí služby Adyen. A nezáleží na tom, zda obchod takovou platbu podporuje či nikoliv.
U dobírky, kde je platba na straně obchodu, je situace jiná. Zde Heureka naprosto respektuje možnosti obchodu a zobrazí je tak zákazníkovi. To znamená, že pokud obchod nepodporuje dobírku, nebude zákazníkovi nabídnuta.

V parametru binding obchod určí jakým způsobem je daná platba vázána na způsob doručení. Např. že "platba hotově při převzetí" je vázána na způsob doručení "osobní odběr na pobočce v Praze".

Obchod nepodporuje platbu kartou nebo převod na účet

Pokud si zákazník zvolí platbu kartou nebo platbu převodem na účet a obchod ani jednu z těchto variant nepodporuje, tak jsou zákazníkovi zobrazeny všechny způsoby dopravy nezávisle na vazbách uvedených v binding.

Předpokládá se, že obchod je po zaplacení zboží schopen zákazníkovi doručit zboží všemi nabídnutými možnostmi.

Identifikace poboček

Parametr store slouží k jasné identifikaci pobočky, kde si lze vyzvednout objednávku. Rozlišují se dva typy a to vlastní pobočky / výdejní místa obchodu.

Vlastní pobočky musí mít správné ID, které je používáno také v rámci XML Dostupnostního feedu. Najdete ho v administraci poboček. Pro vlastní pobočky se jedná o Depot ID pro dostupnostní XML soubor.

Parametr store má význam pouze u osobních odběrů na pobočkách či výdejních místech. U ostatních možností jej neposílejte.

Česká Pošta - Balík Na poštu

Při odeslání objednávky je obchodu zasláno v adrese doručení PSČ vybrané pošty. Obchod tedy expeduje na adresu vybrané pošty.

URL

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

Vstupní parametry

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

Struktura odpovědi

transport array	doprava
id integer	ID dopravy
type integer	typ dopravy (číselník)
name string	název dopravy
price float	cena
description string	popis
store	identifikace pobočky
type integer	typ pobočky / výdejního místa (číselník)
id integer	ID pobočky pro Osobní odběr (z feedu nebo administrace) nebo ID obchodu ("shopId") / ID dopravce ("shipperId") pro DepotAPI.
payment array	platba
id integer	ID platby
type integer	typ platby (číselník)
name string	název platby
price float	cena
binding array	pole vazeb mezi dopravou a platbou
id integer	ID vazby
transportId integer	ID dopravy
paymentId integer	ID platby

HTTP požadavek

K volání URL je využito nástroje 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

Odpověď

{
    "transport": [
    {
        "id": 1,
        "type": 1,
        "name": "PPL",
        "price": 120.00,
        "description": "Do 1 - 2 pracovních dní."
    },
    {
        "id": 2,
        "type": 1,
        "name": "Česká pošta - obchodní balík",
        "price": 100.00,
        "description": "Do 2 - 3 pracovních dní."
    },
    {
        "id": 4,
        "type": 2,
        "name": "Osobní odběr Ostrava",
        "price": 0.00,
        "description": "O tom, že je zboží připraveno k odběru Vás bu...",
        "store":
         {
            "id": 2020,
            "type": 1
         }
    }],
    "payment":[
    {
        "id": 123,
        "type":1,
        "price": 30.00,
        "name": "Dobírka Česká pošta"
    },
    {
        "id": 200,
        "type":1,
        "price": 33.00,
        "name": "Dobírka PPL"
    },
    {
        "id": 300,
        "type": 3,
        "price": 0.00,
        "name": "Platba kartou"
    },
    {
        "id": 100,
        "type": 2,
        "price": 10.00,
        "name": "Platba při převzetí"
    }],
    "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
    }]
}

K čemu slouží vazby?

Vazby jsou důležité k tomu, abychom mohli zákazníkovi správně zobrazit k vybrané platbě dostupné dopravy.

Musí obchod posílat platby kartou a k nim vazby na dopravu, když jsou ve vaší režii?

Platbu kartou (a další online platby) zajišťuje Heureka pomocí Adyen, takže by se mohlo zdát, že není informace od vás o platbě kartou potřeba. To do jisté míry není. Pokud ji nepošlete nic se neděje, my příslušné vazby vygenerujeme sami. Ale pokud je posíláte, tak my vám při objednávce pošleme konkrétní ID platby a dopravy, které si nakupující vybral. Může si je tedy obchod správně spárovat ve svém shopsystému.

Dva kusy zboží má obchod na skladě a může je dodat hned, ale zákazník chce kusy tři, ale ten třetí bude obchod mít až za pět dní. Jak má vypadat hodnota v delivery?

V hodnotě delivery musí být taková hodnota, za kterou je obchod schopný dodat kompletní objednávku. V tomto případě tedy pět.

Jak posílat Českou poštu s dobírkou a bez dobírky?

Je nutné zde rozlišovat dvě věci. Česká pošta je možnost dopravy a dobírka je platba, tyto dvě věci je nutné spojit pomocí vazeb. Chybou by bylo kdyby se možnost platby dobírkou nebo předem rozlišovalo v transport.

Ukázka správného postupu:

{
	"transport": [
	{
	    "id": 1,
	    "type": 1,
	    "name": "Česká pošta",
	    "price": 100.00,
	    "description": "Do 1 - 2 pracovních dní."
	}],
	"payment": [
	{
		"id": 1,
		"type": 1,
		"name": "Dobírka"
		"price": 30.00
	},
	{
		"id": 2,
		"type": 3,
		"name": "Platební karta",
		"price": 0.00
	}],
	"binding": [
	{
		"id": 1,
		"transportId": 1,
		"paymentId": 1
	},
	{
		"id": 2,
		"transportId": 1,
		"paymentId": 2
	}]
}

GET order/status

Vrátí stav objednávky v obchodě.

URL

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

Vstupní parametry

order_id integer	ID objednávky

Struktura odpovědi

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

HTTP požadavek

K volání URL je využito nástroje cURL.

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

Odpověď

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

Jak často se využívá tento požadavek?

Na stav objednávky se automaticky dotazujeme několikrát denně. Obvykle to bývá ráno, okolo poledne a odpolene.

POST order/send

Odeslání objednávky do obchodu.

Po odeslání by mělo dojít v obchodě k rezervaci zboží a začít proces expedice (pokud je objednávka zaplacena nebo je na dobírku).

V případě osobního odběru od zákazníka povinně vyžadujeme pouze pole jméno, příjmení, e-mail a telefonní číslo. Zákazník má možnost vyplnit svou fakturační adresu, pokud to ale neudělá, zasíláme přes API ve fakturačních údajích následující adresu:

Osobní odběr
Ulice č. p.: Osobní odběr 1
Město: Praha
PSČ: 11000
Stát: Česká republika

Poznámka – význam deliveryId a paymentId

Aby mohl obchod rozeznat jakou platbu a dopravu si zákazník vybral jsou zaslaná jejich ID, které byly předány obchodem v metodě payment/delivery.

Může se stát, že obchod v metodě payment/delivery neposílá (obchod jí nepodporuje) např. platbu pomocí platební karty, přesto si jej uživatel může vybrat, protože tato varianta platby je nezávislá na obchodu (zajišťuje ji Heureka). V tomto případě není k dispozici hodnota pro paymentId. Heureka se pokusí tuto hodnotu nahradit ID pro bankovní převod, pokud by ani tento typ platby obchod nepodporoval, tak v paymentId bude zaslána hodnota 0. Pokud však již platba s paymentId 0 existuje, bude použito nejvyšší dostupné paymentId zvýšené o 1.

Příklad:

Příklad odpovědi	paymentId pro bankovní převod	paymentId pro 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

Příklad odpovědi

paymentId pro bankovní převod

paymentId pro 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

Pobočky poskytované skrz DepotAPI

Pokud zákazník zvolí dopravu na pobočku zaslanou skrze DepotAPI je v dodací adrese vyplněna adresa vybrané pobočky.

Poznámka k významu parametru eLicence

Parametr eLicence označuje, že objednávka obsahuje produkt s elektronickou licenci - tyto produkty využívají elektronickou distribuci, tedy ne klasické dopravy. V případě, že objednávka neobsahuje produkt s klasickou dopravou, je deliveryId zvoleno z nejvyššího deliveryId z metody GET payment/delivery, které inkrementujeme o 1 (např. pokud je nejvyšší deliveryId 5, pro eLicenci bude 6).

Url

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

Vstupní parametry

products array	objednané produkty
id string	ID produktu (ITEM ID)
count integer	počet kusů
price float	cena za kterou zákazník produkt objednal (za kus)
totalPrice float	celková cena (počet kusů x cena)
params array	vybrané parametry
id integer	ID parametru
value string	hodnota parametru
gifts array	Dárky nabízené k produktu (z XML)
name string	název dárku
shopGiftId string\|null	ID dárku dodané obchodem v XML
productsTotalPrice float	celková cena za všechny produkty (bez poplatků za dopravu a platbu!)
heureka_id integer	interní číslo objednávky v systému Heureky - pomocí něho můžete identifikovat duplicitně zasílané objednávky
deliveryId integer	ID vybrané dopravy
paymentId integer	ID vybrané platby
deliveryPrice float	cena vybrané dopravy
paymentPrice float	cena vybrané platby
eLicence bool	příznak jestli objednávka obsahuje elektronickou licenci (a tudíž el. distribuci)
note string	poznámka k objednávce
paymentOnlineType array	typ online platby, v případě "offline" platby se parametr neposílá
title string	název platby
id integer	ID platby
customer array	nakupující (fakturační adresa)
firstname string	jméno
lastname string	příjmení
email string	e-mail
phone string	telefon
street string	ulice a číslo popisné
city string	město
postCode string	PSČ
state string	stát
company string	název firmy
ic integer	IČ
dic string	DiČ
deliveryAddress array	nakupující (dodací adresa)
firstname string	jméno
lastname string	příjmení
street string	ulice a číslo popisné
city string	město
postCode string	PSČ
state string	stát
company string	název firmy
depotId integer ^[deprecated]	ID pobočky - Heureka neručí za to, že ID depotu, které od nás přes API obdržíte, je totožné s tím, které dopravce zasílá přímo obchodu.
originalId string	Unikátní ID pobočky podle oficiálního seznamu dopravce.

Struktura odpovědi

order_id integer	číslo objednávky - s tímto číslem dále komunikujeme skrz API
internal_id string	interní číslo objednávky v obchodu (typicky to které uvádíte zákazníkovi na faktuře)
variableSymbol big integer	variabilní symbol (bez nevyýznamných nul, max. 10 čísel), bude sloužit ke spárování plateb při vybíjení kreditu

HTTP požadavek

K volání URL je využito nástroje 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

Odpověd

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

Co se stane, když se nepodaří odeslat objednávku?

Objednávky jsou odesílány přes frontu. To znamená, že po vytvoření zákazníkem se data uloží do databáze do fronty a objednávka se odešle. Pokud není vráceno číslo objednávky, tak je to považováno za neúspěšný pokus a objednání se po chvilce opakuje. Celkem se to zkouší 5 krát, po té jsou neodeslané objednávky řešeny individuálně.

Může obchod objednávku odmítnout?

Nemělo by se to stávat, protože vše co Heureka nabízí má obchod uvedeno v XML feedu a tedy prodává to. Samozřejmě může se stát, že dojde k prodlevě mezi zjištěním dostupnosti a odesláním objednávky, ale i v tomto případě by měl obchod objednávku přijmout a poté se zákazníkem vyřešit tuto skutečnost individuálně.

PUT order/cancel

Nastavení objednávky na storno

Storno objednávky je prováděno jen výjimečně, tak aby nedocházelo k problémům při expedici.

Url

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

Vstupní parametry

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

Struktura odpovědi

status boolean	true došlo ke stornu, jinak false

HTTP požadavek

K volání URL je využito nástroje cURL.

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

Odpověď

{
    "status": true
}

žádné dotazy

PUT payment/status

Url

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

Vstupní parametry

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

Struktura odpovědi

status boolean	zda se povedlo nastavit stav

HTTP požadavek

K volání URL je využito nástroje cURL.

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

Odpověď

{
    "status": true
}

žádné dotazy

API Heureka

Základní tvar URL

https://ssl.heureka.cz/api/cart/:API_ID_obchodu:/:verze_api:/:metoda:/:funkce:

Možnost testování

U každé metody je uveden příklad použití API. Příkaz pomocí cURL lze ihned provést. A lze používat pro své interní testování.

API vrací vygenerovaná data (často náhodně). Cílem testování by měla být struktura nikoliv samotná data.

Upozornění: URL adresa v příkladu má trochu jiný tvar než základní tvar.

Metody API

GET payment/status

Url

https://ssl.heureka.cz/api/cart/API_ID/1/payment/status/

Vstupní parametry

order_id integer	ID objednávky

Struktura odpovědi

order_id integer	číslo objednávky
status signed integer	stav platby (číselník)
date string	datum poslední změny stavu (YYYY-MM-DD)

HTTP požadavek

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

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

žádné dotazy

PUT order/status

Nastavení stavu objednávky na Heurece.

Je důležité, aby každá změna objednávky byla přenesena zpět do Heureky. Jenom tak je možné zákazníkům zobrazit v jakém stavu se nachází jejich objednávka.

Url

https://ssl.heureka.cz/api/cart/API_ID/1/order/status/

Vstupní parametry

order_id integer	ID objednávky
status integer	stav objednávky (číselník)
transport array ^[nepovinné]	informace o expedici - v případě, že jsou k dispozici
tracking_url string	web kde je možné sledovat zásilku směřující k zákazníkovi
note string	poznámka k expedici
expectDelivery string	předpokládaný datum expedice (YYYY-MM-DD)

Struktura odpovědi

status boolean	true pokud bylo vše správně nastaveno

HTTP požadavek

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.cz/cart/validate/1/order/status

Odpověď

{
    "status": true
}

žádné dotazy

PUT payment/status

Nastavení stavu platby na Heurece.

Tato metoda slouží k nastavení platby při dobírce nebo platbě v hotovosti na pobočce obchodu.

Url

https://ssl.heureka.cz/api/cart/API_ID/1/payment/status/

Vstupní parametry

order_id integer	ID objednávky
status signed integer	stav platby (číselník)
date string	datum změny stavu

Struktura odpovědi

status boolean	true - pokud bylo vše správně nastaveno

HTTP požadavek

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

Odpověď

{
    "status": true
}

žádné dotazy

GET order/status

Informace o stavu objednávky a interním čísle objednávky na Heurece.

Url

https://ssl.heureka.cz/api/cart/API_ID/1/order/status/

Vstupní parametry

order_id integer	ID objednávky

Struktura odpovědi

order_id integer	ID objednávky
status integer	stav objednávky (číselník)
internal_id string	interní číslo objednávky v obchodu (typicky to, které uvádíte zákazníkovi na faktuře)
heureka_id integer	interní číslo objednávky v systému Heureky (s tímto číslem komunikujeme se zákazníkem)

HTTP požadavek

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

Odpověď

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

žádné dotazy

GET stores

Informace o pobočkách / výdejních místech, které má obchod uložené na Heurece.

Slouží k nastavení store v GET payment/delivery.

Url

https://ssl.heureka.cz/api/cart/API_ID/1/stores/

Vstupní parametry

žádné

Struktura odpovědi

id integer	ID pobočky / výdejního místa
type integer	typ pobočky / výdejního místa (číselník)
name string	název
city string	umístění

HTTP požadavek

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

Odpověď

[
    {
        "id": 390,
        "type": 1,
        "name": "Pobočka na náměstí",
        "city": "Brno"
    },
    {
        "id": 40,
        "type": 2,
        "name": "WeDo Praha",
        "city": "Praha 3"
    }
]

žádné dotazy

GET shop/status

Informace o aktivaci obchodu v Marketplace.

Slouží k zjištění zda je obchod spuštěn v Marketplace či nikoliv. Pokud je Marketplace vypnutý z důvodu chyby v API nebo nějaké procesní chyby, je o tom napsáno v parametru message.

Informace o aktivaci / deaktivaci jsou vždy na 30 minut uložené ve vyrovnávací paměti (cache). Pokud testujete stav obchodu pomocí cronu zvolte interval 30 minut a více.

Url

https://ssl.heureka.cz/api/cart/API_ID/1/shop/status/

Vstupní parametry

žádné

Struktura odpovědi

status boolean	true pokud je obchod zapnutý
error array	informace o případné chybě, pokud je obchod aktivní je pole prázdné
message string	text chyby
created string	čas kdy byl obchod deaktivován (ve formátu YYYY-MM-DD HH:MM:SS)

HTTP požadavek

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

Odpověď

{
    "status": false,
    "error": {
        "message": "Odezva api je větší než 5 sekund.",
        "created": "2012-09-21 19:11:01"
    }
}

žádné dotazy

POST order/note

Zaslání poznámky, které obchod vytvořil při procesu vyřizování objednávky.

Tyto poznámky se zobrazují zákazníkovi u objednávky v jeho profilu.

Url

https://ssl.heureka.cz/api/cart/API_ID/1/order/note

Vstupní parametry

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

Struktura odpovědi

status boolean	true - zda se poznámka uložila

HTTP požadavek

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

Odpověď

{
    "status": true
}

žádné dotazy

POST order/invoice

Zaslaní faktury (dokladu) k objednávce.

Obchody, které posílají faktury zákazníkům v elektronické podobě, ji musí zaslat také Heurece, tak aby je bylo možné opětovně poslat nebo umožnit jejich stažení v přehledu objednávek.

Maximální velikost souboru s fakturou je 3 MB a soubor musí být v PDF.

Tato metoda předpokládá multipart data u parametru file. POST požadavek by měl mít nastaven Content-type na multipart / form-data.

Url

https://ssl.heureka.cz/api/cart/API_ID/1/order/invoice

Vstupní parametry

order_id integer	ID objednávky
invoice multipart data	faktura

Struktura odpovědi

status boolean	true faktura se uložila

HTTP požadavek

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

Opověď

{
    "status": true
}

žádné dotazy

Odpovědi při chybě

Při chybě nebo při nějaké neočekávané situaci je nutné vracet některý z chybových stavových kódu protokolu HTTP. Tedy kódy řady 3xx, 4xx nebo 5xx.

Při chybě je dobré poslat co se stalo ve tvaru:

{
    "id": 22, // identifikátor chyby
    "msg": "Produkt není možné objednat.",
}

Číselníky

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ě (počítá se s tím, že bude v budoucnu doručena kompletní)
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 na Heurece (objednávka byla správně dokončena na Heurece)
9	objednávka dokončena (zákazník zaplatil a převzal objednávku)
10	objednávka připravena k vyzvednutí (objednávka je připravena pro osobní odběr na pobočce)
11	vyexpedováno na externí výdejní místo (např. WeDo)

Schéma objednávkového procesu

Stav platby

1	zaplaceno
-1	nezaplaceno

Skladová dostupnost

0	skladem, expedováno do 24 hodin
1	1 den do expedice
2	2 dny do expedice
3	3 dny do expedice
	...
n	n dnů do expedice
-1	zboží je nedostupné

Typ platby

1	dobírka
2	hotově při osobním převzetí
3	platební karta
4	převod na účet

Typ dopravy

1	osobní odběr
2	Česká pošta
3	spediční služba (PPL, DPD, ...)
4	expresní dodání
5	speciální doprava
6	Česká Pošta - Balík Na poštu
9	Dopravci poskytovaní skrze DepotAPI

Typ poboček / výdejních míst

1	interní pobočka / výdejní místo obchodu
3	Výdejní místo dopravce z DepotAPI

Seznam dopravců skrze DepotAPI

Seznam dopravců s ID je veřejně přes API, které najdete na GitHubu:
https://api.heureka.cz/depot-api/v1/delivery-places/getshippers

Datové typy

(unsigned) integer	kladné celé číslo (4 bajtové), rozsah: 0 až 4294967295 (např. 1, 2, 20202)
signed integer	celé číslo (4 bajtové), rozsah: -2147483648 až 2147483647 (např. 1, 2, -2, 20202)
(unsigned) big integer	kladné celé číslo (8 bajtové), rozsah 0 až 18446744073709551615 (např. 1, 2, 9223372036854775807)
float	desetinné číslo s desetinnou tečkou (např. 12.90, 999.99)
string	řetězec
bool	logický datový typ (true nebo false)

Zabezpečení komunikace

přístup k API mají pouze stroje ze zvoleného IP rozsahu
pro zabezpečení ze strany obchodu lze omezit přístup pro rozsahy serverů Heureky, které jsou:
- IPv4: 95.173.213.160/27, 95.168.214.64/27, 193.85.239.160/28, 185.68.68.0/22
- IPv6: 2a03:2a60::/32
API vyžaduje HTTPS
každý obchod má unikátní URL adresu

Rychlost odezvy

Obecně platí, že čím kratší odezva tím lépe.

API na straně Heureky odpovídá do několika desítek milisekund. Tuto odezvu požadujeme i od obchodů.

Pamatujte, že na rychlosti API záleží spokojenost zákazníků. Nikdo nechce být při nákupu rušen čekáním. Rychlé odezvy znamenají více nákupů!

V současné době jsou pomalé odezvy API nejčastější příčinou pozastavení služby Heureka Marketplace.

Prosíme, myslete na to.

Podpora

V případě, že máte problém s napojením API Marketplace, obraťte se prosím na [email protected].