Export dat - XML feed

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

Úvod

Tento dokument popisuje systém exportu vypočtených prodejních z Cenového automatu do e‑shops/IS pomocí XML/CSV feedu. XML/CSV formát se používá pro export vypočtených cen do e‑shop 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 WooCommece, použijte tedy pro export cen již připravené propojení. V opačném případě použijte XML/CSV feed.

Exportní XML/CSV 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.

Systém exportu pomocí XML/CSV 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 exportní 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 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 parametr 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.

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í element PRICE_VAT prázdný.

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/xml?from=2023-07-12 15%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ší kontrolou 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í element PRICE_VAT prázdný.

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 ktrerých se nepodařilo cenu vypočítat nebo které nejsou aktuálně přeceňované.

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

Frekvence načítání feedu a Webhook

Aplikace přeceňuje produkty každou hodinu. Je tedy optimální imortovat 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 v 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 XML feedu

Obsah XML/CSV feedu je dynamicky generován při jejich načítání, je tedy vždy aktuální.

Poznámky

Na začátku feedu je uvedeno několik užitečných poznámek:

• čas vygenerování feedu
• typ exportu (rozdílový nebo plný)
• obsah url parametru "from"
• od jakého času se změny exportují (u rozdílového exportu)

SHOP

Kořenový element, v souboru je obsažen pouze jednou.

SHOPITEM

Element obsahuje informace o konkrétním produktu, v souboru je obsažen vícekrát.

ITEM_ID

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

PRICE_VAT

Prodejní cena produktu s DPH.
Formát: číslo ve float formátu s desetinnou tečkou
Při použití rozdílového exportu je obsah elementu prázdný u produktů, které po zadaném čase přestaly být přeceňované (nemají už vypočtenou prodejní cenu)

productNo

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

ean

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

Příklad exportního XML feedu

<!--
 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  -->
<?xml version="1.0" encoding="utf-8"?>
<SHOP>
  <SHOPITEM>
    <ITEM_ID>1</ITEM_ID>
    <PRICE_VAT>15990</PRICE_VAT>
  </SHOPITEM>
  <SHOPITEM>
    <ITEM_ID>12</ITEM_ID>
    <PRICE_VAT>12.90</PRICE_VAT>
  </SHOPITEM>
</SHOP>

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

<!--
 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  -->
<?xml version="1.0" encoding="utf-8"?>
<SHOP>
  <SHOPITEM>
    <ITEM_ID>1</ITEM_ID>
    <PRICE_VAT>15990</PRICE_VAT>
  </SHOPITEM>
  <SHOPITEM>
    <ITEM_ID>12</ITEM_ID>
    <PRICE_VAT></PRICE_VAT>
  </SHOPITEM>
</SHOP>

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

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

Pomocí extraFields lze do feedu přidat tyto elementy:

• ean (ean)
• produktové číslo (productNo)
• id produktu v e-shopu (shopProductUid)
• jméno produktu (productName)
• DPH u produktu (vat), zároveň přidá vypočtené ceny bez DPH do elementu PRICE;

Pro přidání ean použijte ?extraFields=ean. Pro přidání více elementů 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 elementů

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

Takto můžete přejmenovat i více elementů. Např. ean na EAN13, productNo na PRODUCT_NO a productName nechat nezměněné: ?extraFields=ean:EAN13,productNo:PRODUCT_NO,productName

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

<!--
 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  -->
<?xml version="1.0" encoding="utf-8"?>
<SHOP>
  <SHOPITEM>
    <ITEM_ID>1</ITEM_ID>
    <PRICE_VAT>15990</PRICE_VAT>
    <ean>190198783035</ean>
  </SHOPITEM>
  <SHOPITEM>
    <ITEM_ID>12</ITEM_ID>
    <PRICE_VAT>12.90</PRICE_VAT>
    <ean>190199113329</ean>
  </SHOPITEM>
</SHOP>

Vypočtené ceny uvedené i bez DPH

Pokud potřebujete ve feedu uvádět ceny bez DPH, přidejte v url feedu element vat (?extraFields=vat), viz. Přidání productNo, ean a dalších elementů. Tím budou do feedu také přidány ceny bez DPH do elementu PRICE.

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

<!--
 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  -->
<?xml version="1.0" encoding="utf-8"?>
<SHOP>
  <SHOPITEM>
    <ITEM_ID>1</ITEM_ID>
    <PRICE_VAT>15990</PRICE_VAT>
    <vat>20</vat>
    <PRICE>13325</PRICE>
  </SHOPITEM>
  <SHOPITEM>
    <ITEM_ID>12</ITEM_ID>
    <PRICE_VAT>12.90</PRICE_VAT>
    <vat>20</vat>
    <PRICE>10.75</PRICE>
  </SHOPITEM>
</SHOP>