Export dat

Detailní popis systému exportu a struktury exportního feedu s vypočtenými cenami.

Úvod

Tento dokument popisuje systém exportu vypočtených prodejních cen z Cenového automatu do e‑shopu/IS pomocí feedu. Feed se používá u platforem a informačních systémů, pro které neexistuje připravené napojení pomocí API. Pokud je váš e‑shop systém typu Shoptet, UPgates, PrestaShop, Webareal nebo WooCommerce, použijte tedy pro export cen již připravené propojení. V opačném případě použijte feed.

Exportní feed je k dispozici vždy, i když máte nastavený jiný typ exportu (např. Shoptet API). Export pomocí feedu tak lze využívat současně s jiným typem exportu. Stáhnout ho lze v JSONL, XML nebo CSV.

INFO

Export příznaků, slev a dárků je nativně podporován přes Shoptet API, UPgates API a exportní feed. U ostatních typů exportu (PrestaShop, WooCommerce, …) lze tyto informace do e-shopu naimportovat z feedu — ten je k dispozici vždy, i při jiném zvoleném způsobu exportu.

Systém exportu pomocí feedu

Exportní feed je k dispozici ke stažení na definované url adrese, kterou najdete v aplikaci v Konfigurace - Export prodejních cen. E‑shop/IS si v pravidelných intervalech tento feed stahuje a aktualizuje si podle něj prodejní ceny produktů. Doporučené optimální řešení je používat rozdílový export s využitím webhooku.

Typy exportů

Rozdílový export (automatický)

Rozdílový export obsahuje jen produkty, u kterých došlo ke změně vypočtené ceny od předchozího načtení feedu, produkty s čekající změnou příznaků / slev / dárků a produkty, kde je třeba provést korekci ceny. Použitím tohoto exportu tak nedochází ke zbytečnému vytížení vašeho e‑shopu/IS a jde tedy o preferované řešení.

Rozdílový export získáte přidáním parametru from=auto k url adrese feedu. Při načtení feedu s tímto parametrem si aplikace uloží čas volání a při dalším načtení feedu s tímto parametrem použije uložený čas posledního volání a do feedu vloží jen produkty, u kterých došlo po tomto času ke změně vypočtené ceny. Nemusíte si tak sami ukládat na vašem serveru čas posledního načtení feedu.

Načtení s from=auto je oficiální odběr feedu: po úspěšném stažení se u produktů ve feedu zapíšou exportované příznaky a dárky jako odeslané. Manuální from= a plný export bez from=auto pending změny příznaků a dárků nemažou — můžete je tedy znovu stáhnout, pokud import do e-shopu selhal.

Pokud zavoláte exportní feed bez parametru from=auto nebo do parametru from zadáte čas (např. from=2023-07-12 15:30:00, viz níže rozdílový manuální export), aplikace to nepovažuje za načtení rozdílového (automatického) formátu a čas načtení si neuloží. Můžete tedy libovolně kombinovat načítání rozdílového (automatického) formátu se dalšími dvěma formáty, aniž by došlo k narušení řádného rozdílového exportu.

Při použití parametru from obsahuje feed také produkty, které po zadaném čase přestaly být přeceňované (nemají už vypočtenou prodejní cenu). Tyto produkty mají prázdné pole desiredPrice (JSONL null, XML prázdný PRICE_VAT, CSV prázdný 2. sloupec / desiredPrice).

Pokud chcete, aby feed neobsahoval tyto produkty bez vypočtené ceny, použijte v url parametr onlyWithDesPrice=1.

Rozdílový export (manuální)

U tohoto typu exportu si sami volíte čas, od kterého chcete export změn provést. Požadovaný čas se zadává do url parametru from ve formátu YYYY-MM-DD hh:mm:ss (odpovídá formátu MySQL DATETIME), tedy např. 2023-07-12 15:30:00 a následným použitím urlencode, kdy výsledný string je 2023-07-12%2015%3A30%3A00.

Celá url adresa feedu je tedy například https://api.cenovyautomat.cz/v1/shop/123456/app/123456/export/prices/AwSqTrXGgiSd250CFa1WDwGlM99ZSpGx/jsonl?from=2023-07-12%2015%3A30%3A00.

Použití manuálního rozdílového typu exportu je oproti automatickému sice náročnější na implementaci, musíte si sami ukládat čas posledního načtení, ale dává vám větší kontrolu nad procesem exportu. Pokud například dojde ve vašem e‑shopu/IS při importu feedu k chybě a je potřeba exportovaná data znovu načíst a import opakovat, pak to není u tohoto typu exportu problém.

Při použití parametru from obsahuje feed také produkty, které po zadaném čase přestaly být přeceňované (nemají už vypočtenou prodejní cenu). Tyto produkty mají prázdné pole desiredPrice (JSONL null, XML prázdný PRICE_VAT, CSV prázdný 2. sloupec / desiredPrice).

Plný export

Plný export (bez uvedení url parametru from) obsahuje vždy všechny aktuálně přeceněné produkty s vypočtenou cenou. Feed neobsahuje produkty, u kterých se nepodařilo cenu vypočítat nebo které nejsou aktuálně přeceňované. Pokud máte aktivní doplněk Příznaky nebo Slevy a dárky, jsou v plném exportu i produkty bez vypočtené ceny, u kterých je k exportu výsledek pravidel (příznaky, slevy, dárky).

Korekce cen u produktů s nesprávnou cenou

U rozdílových exportů se provádí také inteligentní korekce cen u produktů, kde je to potřeba. Pokud aktuální prodejní cena produktu je jiná, než vypočtená Cenovým automatem, tak produkt bude součástí exportu, i když u něj ke změně vypočtené ceny za předchozí období nedošlo. Tím dojde k potřebné korekci cen u produktů, kde došlo k jejich změně v e-shopu nějakým externím zásahem (ruční úprava, import).

Pokud chcete, aby feed neobsahoval tyto produkty, u kterých se jen provádí korekce ceny, použijte v url parametr excludePriceMismatch=1.

Korekce platí jen pro ceny. Příznaky, slevy a dárky se v rozdílovém feedu neopravují podle stavu v e-shopu. Pokud e-shop feed jednou neaplikuje, obnovte stav plným importem feedu (bez parametru from).

Frekvence načítání feedu a Webhook

Aplikace přeceňuje produkty každou hodinu. Je tedy optimální importovat feed do e‑shopu/IS také každou hodinu. Nedá se však spolehlivě určit, kdy bude přecenění vašich produktů dokončeno a kdy je správný čas pro zahájení importu. Proto doporučujeme využít webhooku, který si v aplikaci můžete sami nastavit v Konfigurace - Export prodejních cen. Hned po dokončení přecenění produktů zavolá webhook vámi zadanou url adresu a tím signalizuje, že jsou k dispozici aktualizované ceny a je ideální čas spustit import.

Specifikace exportního feedu

Obsah feedu je dynamicky generován při načítání, je tedy vždy aktuální. Formát zvolíte v url (/jsonl, /xml, /csv). Query parametry (from, extraFields, …) jsou stejné.

Kanonické názvy polí (JSONL a budoucí uživatelské API) jsou camelCase a odpovídají polím v aplikaci. XML u starých elementů ponechává Heureka názvy (ITEM_ID, PRICE_VAT, PRICE). CSV záleží na tom, jestli má soubor hlavičku — viz CSV: hlavička (header=1).

Význam	JSONL	XML	CSV s header=1	CSV bez hlavičky
Id produktu	productId	productId + ITEM_ID	productId	1. sloupec
Vypočtená cena s DPH	desiredPrice	PRICE_VAT	desiredPrice	2. sloupec
DPH	vat	vat	vat	3. sloupec
Vypočtená cena bez DPH	desiredPriceWithoutVat	PRICE	desiredPriceWithoutVat	4. sloupec

Cena bez DPH i pole vat jsou ve feedu jen při extraFields=vat. V CSV bez dalších extraFields je vat 3. sloupec a desiredPriceWithoutVat 4. sloupec. Doplňková pole z extraFields mají v JSONL kanonický název klíče; v XML a CSV lze název změnit (viz níže).

JSONL má na každém řádku jeden JSON objekt. První řádek je metadata (stejné informace, jaké XML uvádí v komentářích na začátku feedu), další řádky jsou produkty. XML začíná deklarací <?xml version="1.0" encoding="utf-8"?> (musí být na 1. řádku), produkty jsou v kořenovém elementu SHOP a každý produkt v SHOPITEM. CSV používá oddělovač ; a metadata na začátku souboru nemá.

CSV: hlavička (header=1)

Ve výchozím stavu CSV nemá první řádek s názvy sloupců. Pořadí sloupců je pevné: productId;desiredPrice, za nimi pole z extraFields a na konci případně příznaky, slevy a dárky. Importér, který čte první dva sloupce podle pozice, tak zůstane funkční.

Hlavičku zapnete url parametrem header=1. V aplikaci v Konfigurace - Export prodejních cen k tomu slouží volba CSV s názvy sloupců, která parametr k url CSV feedu přidá.

S header=1 je na prvním řádku názvy sloupců (productId, desiredPrice, …). Příklady CSV na této stránce jsou s hlavičkou.

Metadata

Na začátku feedu (JSONL první řádek, XML komentáře) jsou uvedeny:

• čas vygenerování feedu (generated)
• typ exportu — rozdílový nebo plný (type)
• obsah url parametru from (from)
• od jakého času se změny exportují (changesAfter, jen u rozdílového exportu)
• zda feed obsahuje i produkty pro korekci ceny (includesPriceCorrection, jen u rozdílového exportu)

productId

Jednoznačný primární identifikátor produktu, který využíváte pro jeho identifikaci v Heureka produktovém feedu (v tagu ITEM_ID).
Formát: text

ITEM_ID

Alias k poli productId se stejnou hodnotou. Uvádí se jen v XML kvůli zpětné kompatibilitě. V JSONL a CSV se neuvádí.

desiredPrice

Vypočtená prodejní cena produktu s DPH (stejné pole jako v aplikaci).
Formát: číslo ve float formátu s desetinnou tečkou.
V XML je hodnota v elementu PRICE_VAT, v CSV s header=1 ve sloupci desiredPrice, bez hlavičky ve 2. sloupci.
Při použití rozdílového exportu je pole prázdné (JSONL null) u produktů, které po zadaném čase přestaly být přeceňované.

PRICE_VAT

Alias k poli desiredPrice se stejnou hodnotou. Uvádí se jen v XML kvůli zpětné kompatibilitě. V JSONL a CSV se neuvádí.

desiredPriceWithoutVat

Vypočtená prodejní cena bez DPH (desiredPrice / (1 + vat/100)), zaokrouhlená na max. 6 desetinných míst. Ve feedu jen při extraFields=vat. V XML je stejná hodnota v elementu PRICE.
Formát: číslo

productNo

Produktové číslo (volitelné)
Můžete použít k alternativní identifikaci produktů místo productId.
Formát: text

ean

EAN kód (volitelné) Můžete použít k alternativní identifikaci produktů místo productId.
Formát: ean

label

Příznaky, které se mají u produktu v e-shopu nastavit (set) nebo odebrat (remove).
JSONL: objekt, prázdné pole set / remove se vynechá; prázdný objekt label se neuvádí.
XML: element label s opakovanými potomky set / remove (jeden prvek = jeden tag).
CSV: sloupce label.set a label.remove, více hodnot oddělených čárkou.
Hodnota je identifikátor příznaku (UID z katalogu příznaků nebo jméno příznaku).
Ve feedu je jen pokud máte aktivní doplněk Příznaky a u produktu došlo ke změně.
Formát: text

gift

Dárky, které se mají u produktu v e-shopu nastavit (set) nebo odebrat (remove). Hodnota je productId dárku.
Stejné formátování jako u label.
Ve feedu je jen pokud máte aktivní doplněk Slevy a dárky a u produktu došlo ke změně.
Formát: text

sales

Nastavení slev. JSONL a XML: objekt; CSV: sloupce s tečkou (sales.minPriceRatio, …). Prázdné větve se v JSONL/XML vynechají. CSV má pro neaktivní slevy prázdný sloupec.

• minPriceRatio — maximální povolená sleva v procentech (stejná hodnota jako v aplikaci, např. 15 = 15 %). Ve feedu je jen pokud je sleva aktivní. Formát: číslo
• loyaltyDiscount, volumeDiscount, quantityDiscount, discountCoupon, freeShipping, freeBilling — povolení jednotlivých typů slev. JSONL: true / false. XML a CSV: 1 = povolit, 0 = zakázat. Ve feedu jsou jen klíče, které se mají nastavit (volba „Neřešit“ se neuvádí).

Příklad exportního feedu

JSONL

{"meta":{"generated":"2024-12-24 13:44:07","type":"rozdílový","from":"auto","changesAfter":"2024-12-24 12:42:56","includesPriceCorrection":true}}
{"productId":"1","desiredPrice":15990}
{"productId":"12","desiredPrice":12.90}

XML

<?xml version="1.0" encoding="utf-8"?>
<!-- Exportní feed vygenerovaný službou cenovyautomat.cz v čase 2024-12-24 13:44:07 -->
<!-- Typ exportu: rozdílový -->
<!-- Obsah url parametru "from": auto -->
<!-- Export změn cen po čase: 2024-12-24 12:42:56 -->
<!-- Export obsahuje i produkty, u kterých je potřeba provést v e-shopu korekci ceny (prodejní cena je jiná než vypočtená) -->
<SHOP>
  <SHOPITEM>
    <productId>1</productId>
    <ITEM_ID>1</ITEM_ID>
    <PRICE_VAT>15990</PRICE_VAT>
  </SHOPITEM>
  <SHOPITEM>
    <productId>12</productId>
    <ITEM_ID>12</ITEM_ID>
    <PRICE_VAT>12.90</PRICE_VAT>
  </SHOPITEM>
</SHOP>

CSV

productId;desiredPrice
1;15990
12;12.90

Příklad s příznaky, dárky a slevami

JSONL

{"meta":{"generated":"2024-12-24 13:44:07","type":"rozdílový","from":"auto","changesAfter":"2024-12-24 12:42:56","includesPriceCorrection":true}}
{"productId":"1","desiredPrice":15990,"label":{"set":["akce","sleva"],"remove":["novinka"]},"gift":{"set":["GIFT-CASE","GIFT-BAG"],"remove":["GIFT-CABLE"]},"sales":{"minPriceRatio":15,"loyaltyDiscount":true,"freeShipping":true}}

XML

<?xml version="1.0" encoding="utf-8"?>
<!-- Exportní feed vygenerovaný službou cenovyautomat.cz v čase 2024-12-24 13:44:07 -->
<!-- Typ exportu: rozdílový -->
<!-- Obsah url parametru "from": auto -->
<!-- Export změn cen po čase: 2024-12-24 12:42:56 -->
<!-- Export obsahuje i produkty, u kterých je potřeba provést v e-shopu korekci ceny (prodejní cena je jiná než vypočtená) -->
<SHOP>
  <SHOPITEM>
    <productId>1</productId>
    <ITEM_ID>1</ITEM_ID>
    <PRICE_VAT>15990</PRICE_VAT>
    <label>
      <set>akce</set>
      <set>sleva</set>
      <remove>novinka</remove>
    </label>
    <gift>
      <set>GIFT-CASE</set>
      <set>GIFT-BAG</set>
      <remove>GIFT-CABLE</remove>
    </gift>
    <sales>
      <minPriceRatio>15</minPriceRatio>
      <loyaltyDiscount>1</loyaltyDiscount>
      <freeShipping>1</freeShipping>
    </sales>
  </SHOPITEM>
</SHOP>

CSV

productId;desiredPrice;label.set;label.remove;gift.set;gift.remove;sales.minPriceRatio;sales.loyaltyDiscount;sales.volumeDiscount;sales.quantityDiscount;sales.discountCoupon;sales.freeShipping;sales.freeBilling
1;15990;akce,sleva;novinka;GIFT-CASE,GIFT-BAG;GIFT-CABLE;15;1;;;;1;

Příklad rozdílového feedu s produktem, který přestal být přeceňovaný (desiredPrice je u druhého produktu prázdné):

JSONL

{"meta":{"generated":"2024-12-24 13:44:07","type":"rozdílový","from":"auto","changesAfter":"2024-12-24 12:42:56","includesPriceCorrection":true}}
{"productId":"1","desiredPrice":15990}
{"productId":"12","desiredPrice":null}

XML

<?xml version="1.0" encoding="utf-8"?>
<!-- Exportní feed vygenerovaný službou cenovyautomat.cz v čase 2024-12-24 13:44:07 -->
<!-- Typ exportu: rozdílový -->
<!-- Obsah url parametru "from": auto -->
<!-- Export změn cen po čase: 2024-12-24 12:42:56 -->
<!-- Export obsahuje i produkty, u kterých je potřeba provést v e-shopu korekci ceny (prodejní cena je jiná než vypočtená) -->
<SHOP>
  <SHOPITEM>
    <productId>1</productId>
    <ITEM_ID>1</ITEM_ID>
    <PRICE_VAT>15990</PRICE_VAT>
  </SHOPITEM>
  <SHOPITEM>
    <productId>12</productId>
    <ITEM_ID>12</ITEM_ID>
    <PRICE_VAT></PRICE_VAT>
  </SHOPITEM>
</SHOP>

CSV

productId;desiredPrice
1;15990
12;

Přidání productNo, ean a dalších polí

Pokud nemůžete pro identifikaci produktů použít productId, například při napojení na informační systém, který tento identifikátor nezná, lze pro identifikaci produktů využít jejich produktová čísla, EAN kódy nebo jiné identifikátory. Přidání těchto polí do exportního feedu se provádí pomocí url parametru extraFields.

Pomocí extraFields lze do feedu přidat:

• ean (ean)
• produktové číslo (productNo)
• id produktu v e-shopu (shopProductId)
• jméno produktu (productName)
• DPH u produktu (vat); zároveň přidá vypočtenou cenu bez DPH (desiredPriceWithoutVat v JSONL a CSV, PRICE v XML)

Pro přidání ean použijte ?extraFields=ean. Pro přidání více polí je v parametru extraFields oddělte čárkou. Např. ean a productNo přidáte pomocí ?extraFields=productNo,ean. Url s parametry lze také generovat v aplikaci v Konfigurace - Export prodejních cen.

Přejmenování přidaných polí

V XML a CSV můžete standardní názvy doplňkových polí změnit na jiné. Nastavuje se v url parametru extraFields: za kanonické jméno pole přidáte dvojtečku a požadovaný název. Např. když místo ean potřebujete EAN13, použijete ?extraFields=ean:EAN13.

Takto můžete přejmenovat i více polí. Např. ean na EAN13, productNo na PRODUCT_NO a productName nechat nezměněné: ?extraFields=ean:EAN13,productNo:PRODUCT_NO,productName. V JSONL zůstávají kanonické názvy klíčů.

Příklad exportního feedu s přidaným ean

JSONL

{"meta":{"generated":"2024-12-24 13:44:07","type":"rozdílový","from":"auto","changesAfter":"2024-12-24 12:42:56","includesPriceCorrection":true}}
{"productId":"1","desiredPrice":15990,"ean":"190198783035"}
{"productId":"12","desiredPrice":12.90,"ean":"190199113329"}

XML

<?xml version="1.0" encoding="utf-8"?>
<!-- Exportní feed vygenerovaný službou cenovyautomat.cz v čase 2024-12-24 13:44:07 -->
<!-- Typ exportu: rozdílový -->
<!-- Obsah url parametru "from": auto -->
<!-- Export změn cen po čase: 2024-12-24 12:42:56 -->
<!-- Export obsahuje i produkty, u kterých je potřeba provést v e-shopu korekci ceny (prodejní cena je jiná než vypočtená) -->
<SHOP>
  <SHOPITEM>
    <productId>1</productId>
    <ITEM_ID>1</ITEM_ID>
    <PRICE_VAT>15990</PRICE_VAT>
    <ean>190198783035</ean>
  </SHOPITEM>
  <SHOPITEM>
    <productId>12</productId>
    <ITEM_ID>12</ITEM_ID>
    <PRICE_VAT>12.90</PRICE_VAT>
    <ean>190199113329</ean>
  </SHOPITEM>
</SHOP>

CSV

productId;desiredPrice;ean
1;15990;190198783035
12;12.90;190199113329

Vypočtené ceny uvedené i bez DPH

Pokud potřebujete ve feedu uvádět ceny bez DPH, přidejte v url feedu pole vat (?extraFields=vat), viz Přidání productNo, ean a dalších polí. Tím se do feedu přidá vat a dopočtená cena bez DPH: v JSONL a CSV pole desiredPriceWithoutVat, v XML element PRICE (Heureka konvence, stejná hodnota).

Příklad exportního feedu i s cenami bez DPH

JSONL

{"meta":{"generated":"2024-12-24 13:44:07","type":"rozdílový","from":"auto","changesAfter":"2024-12-24 12:42:56","includesPriceCorrection":true}}
{"productId":"1","desiredPrice":15990,"vat":20,"desiredPriceWithoutVat":13325}
{"productId":"12","desiredPrice":12.90,"vat":20,"desiredPriceWithoutVat":10.75}

XML

<?xml version="1.0" encoding="utf-8"?>
<!-- Exportní feed vygenerovaný službou cenovyautomat.cz v čase 2024-12-24 13:44:07 -->
<!-- Typ exportu: rozdílový -->
<!-- Obsah url parametru "from": auto -->
<!-- Export změn cen po čase: 2024-12-24 12:42:56 -->
<!-- Export obsahuje i produkty, u kterých je potřeba provést v e-shopu korekci ceny (prodejní cena je jiná než vypočtená) -->
<SHOP>
  <SHOPITEM>
    <productId>1</productId>
    <ITEM_ID>1</ITEM_ID>
    <PRICE_VAT>15990</PRICE_VAT>
    <vat>20</vat>
    <PRICE>13325</PRICE>
  </SHOPITEM>
  <SHOPITEM>
    <productId>12</productId>
    <ITEM_ID>12</ITEM_ID>
    <PRICE_VAT>12.90</PRICE_VAT>
    <vat>20</vat>
    <PRICE>10.75</PRICE>
  </SHOPITEM>
</SHOP>

CSV

productId;desiredPrice;vat;desiredPriceWithoutVat
1;15990;20;13325
12;12.90;20;10.75