Import dat — XML

Specifikace XML formátu importního produktového feedu. JSONL varianta: Import dat — JSONL.

Importní 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í jejich API. Struktura a názvy tagů jsou velmi podobné s Heureka produktovým feedem.

Struktura souboru

Kořenový element je SHOP (v souboru jednou). Každý produkt je v elementu SHOPITEM.

Ve feedu uvádějte jen elementy, které chcete v aplikaci využívat. U primárního importu je povinný identifikátor produktu, vše ostatní je volitelné.

<?xml version="1.0" encoding="utf-8"?>
<SHOP>
  <SHOPITEM>
    <PRODUCT_ID>K-KU2M07F</PRODUCT_ID>
    <SHOP_PRODUCT_NAME><![CDATA[Apple iPhone 12 Pro]]></SHOP_PRODUCT_NAME>
    <VAT>21</VAT>
    <CURRENT_PRICE>26660</CURRENT_PRICE>
  </SHOPITEM>
</SHOP>

Identifikace produktů

Produkty se při importu identifikují pomocí PRODUCT_ID. Jde o jednoznačný identifikátor produktu v e-shopu. Ideálně jej také využíváte ve zbožových srovnávačích (vyjma Idealo).

Pokud pro srovnávače používáte jiný identifikátor, uveďte jej ve volitelném MERCHANT_PRODUCT_ID. Pokud element chybí, použije se PRODUCT_ID a hodnota se normalizuje: u e-shopů v CZ a SK se znaky mimo 0-9a-zA-Z_- nahradí _ (charset Heureka / Zboží ITEM_ID).

Popis polí

[1] Formát cena | číslo

Ceny a čísla uvádějte ve float formátu s desetinnou tečkou a bez mezer, např. 1234.56. Podporována jsou čísla až s 10 číslicemi, přičemž nejvýše 2 z nich mohou být za desetinnou tečkou. Ceny uvádějte standardně s DPH, ale lze i bez DPH, viz Ceny bez DPH.

[2] Zařazení v e-shop kategorii

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í. Více v Import e-shop kategorií.

Obdobně lze volitelně importovat katalog příznaků.

[3] Flexibilní číselný formát

• 1234.56 (desetinná tečka)
• 1234,56 (desetinná čárka)
• 1 234,56 (mezera jako oddělovač tisíců)
• 1234.56 Kč (měna, např. Kč, CZK, EUR, €)
• 2.5% nebo 2.5 % (procenta)

Příklad importního feedu

<?xml version="1.0" encoding="utf-8"?>
<SHOP>
  <SHOPITEM>
    <PRODUCT_ID>K-KU2M07F</PRODUCT_ID>
    <PRODUCTNO>KU2M07F-001</PRODUCTNO>
    <EAN>8592220013714</EAN>
    <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>
    <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>
    <SALES_VOUCHER_VALUE>1000</SALES_VOUCHER_VALUE>
    <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>
    <GIFT>GIFT-CASE</GIFT>
    <GIFT>GIFT-CABLE</GIFT>
    <CUSTOM_NUMERIC_1>123.45</CUSTOM_NUMERIC_1>
    <CUSTOM_TEXT_1>V letáku do 15.3.</CUSTOM_TEXT_1>
  </SHOPITEM>
</SHOP>

Ceny bez DPH

Standardně se očekávají ceny včetně DPH (atribut pricesIncludeVat chybí, případně je "1").

Ceny bez DPH se signalizují atributem pricesIncludeVat="0" u SHOPITEM — u každého produktu zvlášť. Při cenách bez DPH musí mít produkt uvedenou sazbu DPH (VAT), jinak se ceny nenaimportují.

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

Šifrování nákupních cen

Nákupní ceny lze ve feedu šifrovat. Šifrovací klíč je cryptoKey e-shopu (16 bajtů). Šifrování zapnete atributem encryption="1" na SHOP; inicializační vektor iv (16 B) je stejný pro všechny nákupní ceny ve feedu. Před každým generováním feedu doporučujeme iv znovu náhodně vygenerovat.

Algoritmus je aes-128-cbc (stejný výstup jako openssl_encrypt s options=0, tedy base64).

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

import { createCipheriv } from 'node:crypto'

const cipher = createCipheriv('aes-128-cbc', Buffer.from(cryptoKey), Buffer.from(iv))
const encrypted = Buffer.concat([cipher.update(price, 'utf8'), cipher.final()]).toString('base64')

from base64 import b64encode
from Crypto.Cipher import AES
from Crypto.Util.Padding import pad

cipher = AES.new(crypto_key.encode(), AES.MODE_CBC, iv.encode())
encrypted = b64encode(cipher.encrypt(pad(price.encode(), AES.block_size))).decode()

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

Slučování hodnot u sekundárních importů

U atributů LABEL a GIFT se při sekundárním importu hodnoty sloučí s primárním importem. Můžete tak dohrát další příznaky nebo dárky, aniž by se přepsaly už načtené hodnoty.