Heureka Marketplace – API

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

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

URL

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

Vstupné parametre

Štruktúra odpovede

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.

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

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

Štruktúra odpovede

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

Vráti stav objednávky v obchode.

URL

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

Vstupné parametre

Štruktúra odpovede

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

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:

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

Štruktúra odpovede

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"

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.

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

Štruktúra odpovede

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

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

Štruktúra odpovede

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

Vrátí seznam objednávek v konkrétní výplatě.

Url

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

Vstupní parametry

V odpovědi naleznete text/csv. Data jsou oddělené středníkem (;). Soubor obsahuje následující sloupce:

• Číslo objednávky
• Datum objednávky
• Typ
• Referenční číslo
• Hrubá cena produktů
• Poplatek za dopravu
• Hrubá provize
• Celková cena objednávky
• Celková cena snížená o provizi
• Variabilní symbol
• Interní ID

HTTP požadavek

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

Odpověď

1. „Čí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“
   
2.  8311418522;“2023-07-17 16:10:18″;Pripisovanie;;24;0;3,19;24;20,81;2023000007;2023000007

Jaké je datum pro výplaty?

Výplaty jsou zpracovány vždy v pondělí, pokud je na virtuálním účtu dostupná kladná částka na vyplacení.

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

Štruktúra odpovede

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

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

Štruktúra odpovede

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

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

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

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

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