Heureka Marketplace – Technická specifikace API napojení

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

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": "Kryt na mobil Apple Silikonový kryt s MagSafe na iPhone 16 Pro černý",
      "price": 1272,
      "priceTotal": 1272
    },
    {
      "id": "ABC124",
      "available": true,
      "count": 1,
      "delivery": 0,
      "name": "Mobilní telefon APPLE iPhone 16 Pro 128GB černý titan",
      "price": 29882,
      "priceTotal": 29882
    }
  ],
  "priceSum": 31154
}

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

Platbu kartou zajišťuje Heureka pomocí služby Adyen. Tuto možnost nelze odstranit a zpoplatnit 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“.

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. Toto ID je zároveň používáno také v rámci XML Dostupnostního feedu (nepovinný). 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.

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

{
   "transport": [
   {
       "id": 1,
       "type": 3,
       "name": "PPL",
       "price": 120.00,
       "description": "Do 1 - 2 pracovních dní."
   },
   {
       "id": 2,
       "type": 9,
       "name": "Z-Box",
       "price": 100.00,
       "description": "Do 2 - 3 pracovních dní."
       "store": {
       "type": 3,
       "id": 10     
  },
   },
   {
       "id": 4,
       "type": 1,
       "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": 400,
       "type":4,
       "price": 0.00,
       "name": "Bankovní převod"
   },
   {
       "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": 400
   },
   {
       "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

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

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

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

{
    "status": true
}

Pokud zákazník požádá o storno objednávky tak tuto informaci nejdříve předáváme do obchodu. Storno objednávky provádíme až po vzájemné domluvě s obchodníkem. Aby nedocházelo k potížím s expedicí zboží. Samovolně objednávky nerušíme.

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

{
    "status": true
}

žádné dotazy

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

Url

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

Vstupní parametry

Struktura odpovědí

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

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
}

Je nějaké časové omezení pro změnu stavu objednávky?

Ano, objednávku byste měli označit do konečného stavu nejpozději do 20 dnů od jejího vytvoření. Objednávky starší 20 dnů náš systém automaticky označí jako dokončené. Máte-li s objednávkou problém a potřebujete jí nechat otevřenou déle tak kontaktujte podporu pro Marketplace.

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

žádné

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