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

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

INFO

Kvůli kompatibilitě se starší specifikací (před 2.4.2026) lze identifikátor uvést také v SHOP_PRODUCT_CODE nebo ITEM_ID. Pokud je ve feedu více těchto elementů, použijí se v pořadí: PRODUCT_ID, SHOP_PRODUCT_CODE, ITEM_ID.

Popis polí

`SHOP`

Kořenový element, v souboru jednou.
Volitelné atributy encryption a iv — viz Šifrování nákupních cen.

`SHOPITEM`

Informace o jednom produktu. V souboru tolikrát, kolik máte produktů.
Volitelný atribut pricesIncludeVat — viz Ceny bez DPH.

`PRODUCT_ID`

Jednoznačný primární identifikátor produktu v e-shopu.
Formát: text

`MERCHANT_PRODUCT_ID`

Jednoznačný identifikátor produktu ve zbožových srovnávačích (vyjma Idealo).
Pokud element chybí, použije se PRODUCT_ID a hodnota se normalizuje (u CZ/SK se znaky mimo 0-9a-zA-Z_- nahradí _). Uvádějte ho jen tehdy, když se identifikátor pro e-shop a srovnávače liší.
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

`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ý. [2]
Formát: text

`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 kategoriích je produkt zařazený. [2]
Formát: text

`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čená 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]

`SALES_VOUCHER_VALUE`

Hodnota slevového kupónu. Uvedena včetně DPH.
Formát: číselný [3]

`MIN_ALLOWED_PRICE`

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

`MAX_ALLOWED_PRICE`

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

`LABEL`

Příznak produktu. Element je ve feedu obsažen tolikrát, kolik má produkt příznaků.
Volitelný katalog všech příznaků e-shopu (i nepoužitých) lze importovat zvlášť.

`LABEL_NAME`

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

`LABEL_DATE_FROM`

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

`LABEL_DATE_TO`

Datum, do kdy je příznak platný.
Volitelné. Pokud chybí, 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 (zboží.cz, Google Merchant).

`GIFT`

Identifikátor produktu (PRODUCT_ID), který je k tomuto produktu v e-shopu nastavený jako dárek.
Element je ve feedu obsažen tolikrát, kolik má produkt dárků.
Formát: text

`CUSTOM_NUMERIC_1`, `CUSTOM_NUMERIC_2`…`CUSTOM_NUMERIC_5`

Uživatelská numerická pole.
Formát: číslo [1]

`CUSTOM_TEXT_1`, `CUSTOM_TEXT_2`…`CUSTOM_TEXT_5`

Uživatelská textová pole.
Formát: text

[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

<?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

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

PHPNode.jsPython

php

$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')

python

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

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

Import dat — XML ​

Struktura souboru ​

Identifikace produktů ​

Popis polí ​

SHOP ​

SHOPITEM ​

PRODUCT_ID ​

MERCHANT_PRODUCT_ID ​

PRODUCTNO ​

EAN ​

PRODUCTNAME ​

SHOP_PRODUCT_NAME ​

MANUFACTURER ​

SUPPLIER ​

URL ​

IMGURL ​

DELIVERY_DATE ​

STOCK_QTY ​

WEIGHT ​

ACTIVE_IN_SHOP ​

SHOP_DEFAULT_CATEGORY_UID ​

SHOP_CATEGORY_UID ​

VAT ​

CURRENT_PRICE ​

MOC_PRICE ​

COMMON_PRICE ​

ACTION_PRICE ​

PURCHASE_PRICE ​

SALES_VOUCHER_VALUE ​

MIN_ALLOWED_PRICE ​

MAX_ALLOWED_PRICE ​

LABEL ​

LABEL_NAME ​

LABEL_DATE_FROM ​

LABEL_DATE_TO ​

CUSTOM_LABEL_0, CUSTOM_LABEL_1, CUSTOM_LABEL_2…CUSTOM_LABEL_9 ​

GIFT ​

CUSTOM_NUMERIC_1, CUSTOM_NUMERIC_2…CUSTOM_NUMERIC_5 ​

CUSTOM_TEXT_1, CUSTOM_TEXT_2…CUSTOM_TEXT_5 ​

[1] Formát cena | číslo ​

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

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

Příklad importního feedu ​

Ceny bez DPH ​

Šifrování nákupních cen ​

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