Heureka Marketplace - API

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

URL

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

Vstupní parametry

Struktura odpovědi

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.

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".

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

Struktura odpovědi

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
	}]
}
            

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

URL

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

Vstupní parametry

Struktura odpovědi

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.

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:

    {
        "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": ...
    }
            

    {
        "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": ...
    }
            

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

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

Struktura odpovědi

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ě.

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

Struktura odpovědi

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

Url

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

Vstupní parametry

Struktura odpovědi

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

Url

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

Vstupní parametry

Struktura odpovědi

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

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

Struktura odpovědi

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

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

Struktura odpovědi

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

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

Struktura odpovědi

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

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

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

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

Struktura odpovědi

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

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

Struktura odpovědi

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

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

Struktura odpovědi

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