Import dat - XML feed | Cenový automat

Import dat - XML feed

Detailní popis struktury importního XML feedu

20.9.2023

Obsah
1. Jaká data lze importovat
2. Atributy produktů
3. Ceny včetně nebo bez DPH
4. Použití šifrování u nákupních cen ‍
5. Přidání příznaků k produktům

‍

Importní XML feed slouží jako primární zdroj produktů pro jejich import do Cenového automatu. Využívá se u e-shop systémů, ze kterých nelze tato data načítat s pomocí API. Struktura a názvy tagů jsou velmi podobné s Heureka produktovým feedem.

Jaká data lze importovat

Do Cenového automatu lze k produktům importovat celou řadu informací, které je pak možno využít při zadávání přeceňovacích pravidel:

Identifikátory produktů
Jména produktů
Výrobce
Nákupní, doporučené, běžné a akční ceny
Minimální a maximální povolené ceny
Stavy skladu
Další doplňkové informace

Identifikace produktů

Produkty se při importu identifikují pomocí SHOP_PRODUCT_CODE nebo ITEM_ID. Pokud jsou ve feedu uvedeny oba, SHOP_PRODUCT_CODE má prioritu.

Atributy produktů

SHOP
Kořenový element, v souboru je obsažen pouze jednou.
Element může mít volitelně uvedeny tyto atributy:
encryption, iv - využívá se při Použití šifrování u nákupních cen
‍mergeLabels - využívá se pro Přidání příznaků k produktům v sekundárním importu
‍

SHOPITEM
‍Element obsahuje informace o konkrétním produktu, v souboru je obsažen tolikrát, kolik máte produktů.

‍ 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

‍SHOP_PRODUCT_UID
‍Identifikátor produktu v e-shopu
Formát: text

‍SHOP_PRODUCT_CODE
‍Kód produktu v e-shopu
Formát: text

‍PRODUCTNO
‍Produktové číslo (většinou identifikátor definovaný výrobcem).
Formát: text

‍EAN
‍EAN kód.
Formát: ean

‍PRODUCTNAME
‍Název produktu, jak jej odesíláte do Heureky.
Formát: text

‍SHOP_PRODUCT_NAME
‍Název produktu v e-shopu.
Formát: text

‍MANUFACTURER
‍Název výrobce.
Formát: text

‍SUPPLIER
Název dodavatele.
Formát: text

‍URL
‍Url produktu v e-shopu.
Formát: url

‍IMGURL
‍Url obrázku produktu.
Formát: url

‍GIFT
‍Popis dárku k produktu (pro Heureku).
Formát: text

‍DELIVERY_DATE
‍Dostupnost produktu.
Formát: dle Heureka specifikace

‍STOCK_QTY
‍Stav skladu, počet kusů skladem.
Formát: celé číslo

‍WEIGHT
‍Hmotnost produktu v kg.
Formát: číslo [1]

‍ACTIVE_IN_SHOP
‍Indikátor, jestli je produkt v e-shopu aktivní (není skrytý, deaktivovaný, smazaný, apod.).
Formát: 0|1

‍SHOP_DEFAULT_CATEGORY_UID
‍Jednoznačný identifikátor výchozí kategorie e-shopu, kde je produkt primárně zařazený.
Formát: text [2]

‍SHOP_CATEGORY_UID
‍Jednoznačný identifikátor kategorie e-shopu, kde je produkt zařazený.
Element je ve feedu obsažen tolikrát, v kolika kategorích je produkt zařazený.
Formát: text [2]

‍VAT
‍Sazba DPH.
Formát: s desetinou tečkou (0.21), jako celé číslo (21) nebo procenta (21%) [1]

‍CURRENT_PRICE
‍Aktuální cena v e-shopu.
Formát: cena [1]

‍MOC_PRICE
‍Doporučná koncová cena.
Formát: cena [1]

‍COMMON_PRICE
‍Běžná cena.
Formát: cena [1]

‍ACTION_PRICE
‍Akční cena.
Formát: cena [1]

‍PURCHASE_PRICE
‍Nákupní cena.
Formát: cena [1]

‍MIN_ALLOWED_PRICE
‍Minimální povolená cena.
Formát: cena [1]

‍MAX_ALLOWED_PRICE
‍Maximální povolená cena.
Formát: cena [1]

‍LABEL
‍Element obsahující informace o příznaku produktu.
Element je ve feedu obsažen tolikrát, kolik má produkt příznaků.

LABEL_NAME
‍Jméno příznaku.
Formát: text

‍LABEL_DATE_FROM
‍Datum, od kdy je příznak platný.
Volitelné. Pokud není uvedeno, je příznak aktuálně platný.
Formát: datum (YYYY-MM-DD)

‍LABEL_DATE_TO
‍Datum, od kdy je příznak platný.
Volitelné. Pokud není uvedeno, je příznak aktuálně platný.
Formát: datum (YYYY-MM-DD)

‍CUSTOM_LABEL_0
CUSTOM_LABEL_1
CUSTOM_LABEL_2
...
CUSTOM_LABEL_9
‍Jména příznaků produktu.
Alternativní formát uvádění příznaků. Tento formát využívá zboží.cz nebo Google Merchant.text

[1] Ceny a čísla uvádějte ve float formátu s desetinou tečkou a bez mezer, např. 1234.123456. Ceny uvádějte standardně s DPH, ale lze i bez DPH, viz sekce Ceny včetně nebo bez DPH.
[2]Pokud chcete v aplikaci v podmínkách pravidel používat výběr produktů dle jejich zařazení v e-shop kategorii, je třeba do aplikace importovat seznam všech kategorií. Viz. Import e-shop kategorií - XML feed.

Příklad importního XML feedu


<?xml version="1.0" encoding="utf-8"?>
<SHOP>
  <SHOPITEM>
    <ITEM_ID>1</ITEM_ID>
    <SHOP_PRODUCT_UID>d35320f2-1033-11ea-82c9-9e442da4cfe7</SHOP_PRODUCT_UID>
    <SHOP_PRODUCT_CODE>K-KU2M07F</SHOP_PRODUCT_CODE>
    <PRODUCTNO>KU2M07F-001</PRODUCTNO>
    <EAN>8592220013714</EAN>
    <PRODUCTNAME><![CDATA[Apple iPhone 12 Pro 128GB]]></PRODUCTNAME>
    <SHOP_PRODUCT_NAME><![CDATA[Apple iPhone 12 Pro (128GB, Gold)]]></SHOP_PRODUCT_NAME>
    <MANUFACTURER><![CDATA[Apple]]></MANUFACTURER>
    <SUPPLIER><![CDATA[Apcom Czech]]></SUPPLIER>
    <URL><![CDATA[https://www.shop.cz/mobilni-telefony/apple/iphone-12-pro]]></URL>
    <IMGURL><![CDATA[https://images.shop.cz/apple-iphone-12-pro.jpg]]></IMGURL>
    <GIFT><![CDATA[Sleva 500 Kč na příslušenství]]></GIFT>
    <DELIVERY_DATE>0</DELIVERY_DATE>
    <STOCK_QTY>55</STOCK_QTY>
    <WEIGHT>0.55</WEIGHT>
    <ACTIVE_IN_SHOP>1</ACTIVE_IN_SHOP>
    <SHOP_CATEGORY_UID>358</SHOP_CATEGORY_UID>
    <SHOP_CATEGORY_UID>132</SHOP_CATEGORY_UID>
    <SHOP_DEFAULT_CATEGORY_UID>358</SHOP_DEFAULT_CATEGORY_UID>
    <VAT>21</VAT>
    <CURRENT_PRICE>26660.00</CURRENT_PRICE>
    <MOC_PRICE>29990.00</MOC_PRICE>
    <COMMON_PRICE>27990.00</COMMON_PRICE>
    <PURCHASE_PRICE>24575.94</PURCHASE_PRICE>
    <MIN_ALLOWED_PRICE>25444.78</MIN_ALLOWED_PRICE>
    <MAX_ALLOWED_PRICE>29990.00</MAX_ALLOWED_PRICE>
    <LABEL>
       <LABEL_NAME><![CDATA[Novinka]]></LABEL_NAME>
       <LABEL_FROM>2020-04-15</LABEL_FROM>
       <LABEL_TO>2020-04-30</LABEL_TO>
     </LABEL>
     <LABEL>
         <LABEL_NAME><![CDATA[Akce]]></LABEL_NAME>
     </LABEL>
  </SHOPITEM>
</SHOP>

Ceny včetně nebo bez DPH

Standardně se očekává zadání všech cen včetně DPH. Volitelně je možno zadat ceny bez DPH.

Použití cen bez DPH se signalizuje atributem pricesIncludeVat="0" v elementu SHOPITEM. U každého produktu tak můžete specifikovat, jestli jsou ceny
uvedeny bez nebo včetně DPH. Při použití cen bez DPH musí mít produkt uvedenou sazbu DPH (tag VAT), jinak dojde k chybě ceny se nenaimportují.

Pokud je atribut pricesIncludeVat=“1" nebo není uvedený, jsou ceny uvedeny včetně DPH.

Příklad importního XML feedu s cenami bez DPH:


<?xml version="1.0" encoding="utf-8"?>
<SHOP>
  <SHOPITEM pricesIncludeVat="0">
    <ITEM_ID>1</ITEM_ID>
    <PURCHASE_PRICE>20310.69421</PURCHASE_PRICE>
    <VAT>0.21</VAT>
    ...
  </SHOPITEM>

Použití šifrování u nákupních cen

Pro zajištění maximální bezpečnosti dat je možno v importním feedu šifrovat nákupní ceny produktů, aby tak nemohlo dojít k nežádoucímu úniku těchto citlivých informací.

Použití šifrování se signalizuje atributem encryption="1" v kořenovém elementu SHOP.

Pro šifrování je třeba použít příkaz openssl_encrypt se šifrovací metodou aes-128-cbc, šifrovacím klíčem zadaným v konfiguraci API a inicializačním vektorem (iv), který je poté uvedený jako atribut kořenového elementu SHOP. Inicializační vektor (iv) se používá stejný pro zašifrování všech nákupních cen ve feedu. Pro zvýšení bezpečnosti se ale doporučuje před každým vytvářením feedu vygenerovat nový náhodný inicializační vektor.

V PHP se zašifrování nákupní ceny provede tímto kódem:

$zasifrovane = openssl_encrypt($cena, 'aes-128-cbc', $cryptoKey, 0, $iv);

Cenový automat provádí dešifrování tímto kódem:

$cena = openssl_decrypt($zasifrovane, 'aes-128-cbc', $cryptoKey, 0, $iv);

Příklad importního XML feedu se šifrováním nákupních cen:


<?xml version="1.0" encoding="utf-8"?>
<SHOP encryption="1" iv="1234567890123456">
  <SHOPITEM>
    <ITEM_ID>1</ITEM_ID>
    <PURCHASE_PRICE>qIGYBlxEdDqEj5kskOX80g==</PURCHASE_PRICE>
    ...
  </SHOPITEM>
</SHOP>

‍

Přidání příznaků k produktům

Pokud potřebujete k produktům importovat další příznaky z jiného zdroje, např. z informačního systému, můžete toho dosáhnout pomocí sekundárního importu a importního feedu tohoto formátu. Aby však nedocházelo k přepsání stávajících příznaků, které jsou u produktů nastaveny pomocí primárního importu, je třeba k XML elementu SHOP přidat atribut mergeLabels = "1". Nastavení tohoto atributu na hodnotu "1" aplikaci signalizujete, že chcete příznaky uvedené v tomto feedu přidat k již stávajícím, a ne je přepsat.

Příklad sekundárního importního XML feedu pro přidání příznaků k produktů.:


<?xml version="1.0" encoding="utf-8"?>
<SHOP mergeLabels="1">
  <SHOPITEM>
    <ITEM_ID>1</ITEM_ID>
    <LABEL>
       <LABEL_NAME><![CDATA[V_letaku]]></LABEL_NAME>
       <LABEL_FROM>2023-06-15</LABEL_FROM>
       <LABEL_TO>2023-06-30</LABEL_TO>
     </LABEL>
     <LABEL>
         <LABEL_NAME><![CDATA[Bez_prodeje_90_dni]]></LABEL_NAME>
     </LABEL>
  </SHOPITEM>
</SHOP>

‍