Export dat - XML feed
Detailní popis systému exportu a struktury exportního XML feedu s vypočtenými cenami
Aktualizováno 24.9.2024
Obsah
1. Systém exportu pomocí XML/CSV feedu
2. Typy exportů
3. Korekce cen u produktů s nesprávnou cenou
4. Frekvence načítání feedu a Webhook
5. Specifikace exportního XML feedu
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ý (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ý (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%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ší 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ý
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
Příklad rozdílového exportního XML feedu s produktem, který přestal být přeceňovaný (PRICE_VAT je druhého produktu prázdný)
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í 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 použitím ean pro identifikaci produktů
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ředchozí odstavec. Tím budou do feedu také přidány ceny bez DPH do elementu <PRICE>.