XML Feed — Produkty

Hlavní produktový feed pro import produktů do UpSearch. Podporuje jednoduché produkty, master produkty s variantami, promo kódy (price_with_code), badge, parametry a další.

Struktura feedu

Kořenový element

<?xml version="1.0" encoding="utf-8"?>
<products>
    <title>Název e-shopu</title>
    <link>https://www.example.com/</link>
    <item>
        <!-- data produktu -->
    </item>
</products>

Obsahuje všechny produktové položky (<item>). Každý produkt — ať master, varianta, nebo samostatný — je samostatný <item> na stejné úrovni.

Element `<item>`

Reprezentuje jeden produkt (master, varianta, nebo samostatný produkt).

Základní identifikátory

Parametr	Typ	Povinný	Popis
`id`	integer	✅ Ano	Jedinečný identifikátor produktu
`code`	string	❌ Ne	Produktový kód / SKU
`ean`	string	❌ Ne	EAN kód produktu
`number`	string	❌ Ne	Katalogové číslo produktu
`master_id`	integer	❌ Ne	ID master produktu — propojuje varianty (u masteru = vlastní `id`)
`is_master`	boolean	❌ Ne	`true` = master produkt, `false` = varianta nebo samostatný produkt

Jak fungují varianty

Varianty nejsou vnořené uvnitř master produktu. Jsou to samostatné <item> elementy propojené přes <master_id>. Všechny varianty i master sdílejí stejnou hodnotu master_id (= ID master produktu).

Základní informace

Parametr	Typ	Povinný	Popis
`name`	string	✅ Ano	Název produktu
`url`	string (URL)	✅ Ano	URL adresa produktové stránky

Obrázky

Parametr	Typ	Povinný	Popis
`image`	string (URL)	✅ Ano	Obrázek produktu pro autocomplete (min. 50×50)
`image_2x_link`	string (URL)	✅ Ano	Hlavní obrázek produktu (min. 500×500)
`image_alternative`	string (URL)	❌ Ne	Alternativní obrázek (např. jiný úhel)

Brand a kategorie

Parametr	Typ	Povinný	Popis
`brand_id`	integer	❌ Ne	ID značky
`brand_name`	string	❌ Ne	Název značky
`category_id`	integer	❌ Ne	ID hlavní kategorie
`main_category`	string	❌ Ne	Název hlavní kategorie
`categories`	string	❌ Ne	Kategorie (může se opakovat pro více kategorií)
`root_category`	string	❌ Ne	Kořenová kategorie
`breadcrumb`	string	❌ Ne	Navigační cesta (oddělená `\|`)

Skladové informace

Parametr	Typ	Povinný	Popis
`store_count`	integer	❌ Ne	Počet kusů na skladě
`stock_info`	object	❌ Ne	Objekt s informacemi o stavu skladu
`stock_info/text`	string	❌ Ne	Textový popis skladu (např. "Skladem", "Na objednávku")
`stock_info/status`	string	❌ Ne	Status skladu (`in_stock`, `not_in_stock`, `out_of_stock`)
`in_stock`	boolean	❌ Ne	`true` pokud je skladem
`delivery_delay`	integer	❌ Ne	Doba dodání ve dnech (0 = skladem)

Ceny

Parametr	Typ	Povinný	Popis
`price`	number	✅ Ano	Cena s DPH v hlavní měně
`old_price`	number	❌ Ne	Původní cena před slevou
`discount_in_percent`	integer	❌ Ne	Výše slevy v procentech
`price_with_code`	object	❌ Ne	Cena s promo kódem (viz sekce níže)

Automatické formátování cen

Stačí poslat pouze číselnou hodnotu price (např. 1299). UpSearch automaticky vygeneruje formátovanou cenu (např. "1 299 Kč") podle nastavení měny a formátu v Nastavení projektu.

Pokud potřebujete vlastní formát zobrazení (např. "od 499 Kč" u master produktů), můžete použít volitelný element price_view.

Volitelné přepsání formátu ceny

Parametr	Typ	Povinný	Popis
`price_view`	object	❌ Ne	Vlastní zobrazení ceny (přepíše automatický formát)
`price_view/value`	number	✅ Ano*	Číselná hodnota ceny
`price_view/view`	string	✅ Ano*	Formátovaný text ceny (např. "od 499 Kč")
`old_price_view`	object	❌ Ne	Vlastní zobrazení původní ceny
`old_price_view/value`	number	✅ Ano*	Číselná hodnota původní ceny
`old_price_view/view`	string	✅ Ano*	Formátovaný text původní ceny

*Povinné, pokud je daný element přítomen

Víceměnové ceny

Pro e-shopy s více měnami (např. CZK + EUR) přidejte cenové elementy s příponou měny:

Parametr	Typ	Popis
`price_EUR`	number	Cena v EUR
`price_view_EUR`	object	Formátované zobrazení v EUR
`old_price_EUR`	object	Původní cena v EUR

Cena s promo kódem (`price_with_code`)

Umožňuje zobrazit zvýhodněnou cenu po zadání promo kódu, včetně data expirace. Widget automaticky zobrazí promo kód a odpočet do konce platnosti.

Parametr	Typ	Povinný	Popis
`price_with_code/price`	object	✅ Ano	Cena po aplikaci promo kódu
`price_with_code/price/value`	float	✅ Ano	Číselná hodnota zvýhodněné ceny
`price_with_code/price/view`	string	❌ Ne	Formátovaný text ceny (např. "449 Kč")
`price_with_code/code`	string	✅ Ano	Promo kód pro získání slevy
`price_with_code/datetime`	string (ISO 8601)	✅ Ano	Datum a čas konce platnosti promo kódu

Podporované formáty datetime:

ISO 8601 s časovou zónou: 2026-06-30T23:59:59+02:00 (doporučeno)
ISO 8601 základní: 2026-06-30T23:59:59
SQL formát: 2026-06-30 23:59:59

Jak to funguje

Widget zobrazí vedle běžné ceny i zvýhodněnou cenu s promo kódem a odpočtem do konce platnosti. Pokud do expirace zbývá méně než 24 hodin, zobrazí se urgentní styl (červené pozadí).

Důležité

code nesmí být prázdný
datetime musí být platný ISO 8601 datum — nevalidní formát způsobí chybu při importu
Po vypršení datetime se price_with_code ve widgetu automaticky přestane zobrazovat

Hodnocení

Parametr	Typ	Povinný	Popis
`reviews_rating`	float	❌ Ne	Průměrné hodnocení (0–5, může být desetinné číslo)
`reviews_count`	integer	❌ Ne	Počet hodnocení

Dárky (gifts)

Parametr	Typ	Povinný	Popis
`gifts`	object	❌ Ne	Dárky/bonusy k produktu (může se opakovat pro více dárků)
`gifts/name`	string	✅ Ano*	Název dárku (např. "Pouzdro zdarma", "Paměťová karta 32 GB")
`gifts/image`	string (URL)	❌ Ne	Obrázek dárku

*Povinné, pokud je element gifts přítomen

Další pole

Parametr	Typ	Povinný	Popis
`sold_count`	integer	❌ Ne	Počet prodaných kusů (pro řazení)

Parametry produktu

Parametr	Typ	Povinný	Popis
`param`	object	❌ Ne	Technické parametry produktu (může se opakovat)
`param/name`	string	✅ Ano*	Název parametru (např. "Barva", "Materiál", "Velikost")
`param/value`	string	✅ Ano*	Hodnota parametru

*Povinné, pokud je element param přítomen

Badge (označení)

Parametr	Typ	Povinný	Popis
`badge`	object	❌ Ne	Vizuální badge/štítek produktu (může se opakovat)
`badge/front_text`	string	✅ Ano*	Text na badge (např. "Bestseller", "Novinka")
`badge/front_text_color`	string (HEX)	❌ Ne	Barva textu badge (např. "#ffffff")
`badge/front_background_color`	string (HEX)	✅ Ano*	Barva pozadí badge (např. "#10b981")

*Povinné, pokud je element badge přítomen

Master produkty a varianty

Varianty se v UpSearch XML feedu zapisují jako samostatné <item> elementy na stejné úrovni. Propojení master–varianta se řeší přes pole <master_id> a <is_master>.

Pravidla

Master produkt: <is_master>true</is_master>, <master_id> = vlastní <id>
Varianta: <is_master>false</is_master>, <master_id> = ID master produktu
Samostatný produkt (bez variant): <is_master>false</is_master> nebo neuvedeno, bez <master_id>

Jak to funguje

Master slouží jako zástupný produkt, který se zobrazí ve výsledcích vyhledávání
Varianty jsou propojeny přes sdílené master_id a UpSearch je seskupí
Master produkt typicky obsahuje annotation, souhrnný popis a cenu "od X Kč"
Varianty mají konkrétní atributy (barva, velikost) v názvu nebo v <param>

Feed:
┌─────────────────────────────────────┐
│ <item> id=1001 master_id=1001  │ ← Master (is_master=true)
│ <item> id=1002 master_id=1001  │ ← Varianta — černá
│ <item> id=1003 master_id=1001  │ ← Varianta — bílá
│ <item> id=2001 (bez master_id) │ ← Samostatný produkt
└─────────────────────────────────────┘

Datové typy

Typ	Popis	Příklad
`integer`	Celé číslo	`6654`, `145`, `0`
`float`	Desetinné číslo	`4.3`, `4.7`, `5`
`number`	Celé nebo desetinné číslo	`499`, `28.89`
`string`	Textový řetězec	`"Modrá"`, `"XL"`
`boolean`	Pravdivostní hodnota	`true`, `false`
`URL`	URL adresa	`https://example.com/...`
`object`	Vnořený element s další strukturou	`<price_view>...</price_view>`

Příklady XML struktur

Master produkt s variantami (barva)

Tři samostatné <item> elementy propojené přes master_id:

<!-- Master produkt -->
<item>
    <id>1001</id>
    <name>Designové křeslo</name>
    <annotation>Pohodlné designové křeslo dostupné v několika barvách.</annotation>
    <url>https://www.example.com/designove-kreslo/</url>
    <image>https://www.example.com/images/kreslo-50.jpg</image>
    <image_2x_link>https://www.example.com/images/kreslo-500.jpg</image_2x_link>
    <brand_id>10</brand_id>
    <brand_name>HomeDesign</brand_name>
    <category_id>25</category_id>
    <main_category>Křesla</main_category>
    <categories>Křesla</categories>
    <categories>Obývací pokoj</categories>
    <root_category>Nábytek</root_category>
    <breadcrumb>Nábytek | Křesla</breadcrumb>
    <master_id>1001</master_id>
    <is_master>true</is_master>
    <store_count>8</store_count>
    <delivery_delay>0</delivery_delay>
    <price>4990</price>
    <price_view>
        <value>4990</value>
        <view>od 4 990 Kč</view>
    </price_view>
    <stock_info>
        <text>Skladem</text>
        <status>in_stock</status>
    </stock_info>
    <in_stock>true</in_stock>
    <param>
        <name>Materiál</name>
        <value>Polyester</value>
    </param>
    <badge>
        <front_text>Bestseller</front_text>
        <front_text_color>#ffffff</front_text_color>
        <front_background_color>#10b981</front_background_color>
    </badge>
</item>

<!-- Varianta — šedá (price_view se generuje automaticky z price) -->
<item>
    <id>1002</id>
    <name>Designové křeslo šedé</name>
    <code>DK-GREY</code>
    <ean>8590000000001</ean>
    <url>https://www.example.com/designove-kreslo-sede/</url>
    <image>https://www.example.com/images/kreslo-sede-50.jpg</image>
    <image_2x_link>https://www.example.com/images/kreslo-sede-500.jpg</image_2x_link>
    <brand_id>10</brand_id>
    <brand_name>HomeDesign</brand_name>
    <category_id>25</category_id>
    <main_category>Křesla</main_category>
    <categories>Křesla</categories>
    <root_category>Nábytek</root_category>
    <breadcrumb>Nábytek | Křesla</breadcrumb>
    <master_id>1001</master_id>
    <is_master>false</is_master>
    <store_count>5</store_count>
    <delivery_delay>0</delivery_delay>
    <param>
        <name>Barva</name>
        <value>šedá</value>
    </param>
    <price>4990</price>
    <stock_info>
        <text>Skladem</text>
        <status>in_stock</status>
    </stock_info>
    <in_stock>true</in_stock>
</item>

<!-- Varianta — modrá (price_view se generuje automaticky z price) -->
<item>
    <id>1003</id>
    <name>Designové křeslo modré</name>
    <code>DK-BLUE</code>
    <ean>8590000000002</ean>
    <url>https://www.example.com/designove-kreslo-modre/</url>
    <image>https://www.example.com/images/kreslo-modre-50.jpg</image>
    <image_2x_link>https://www.example.com/images/kreslo-modre-500.jpg</image_2x_link>
    <brand_id>10</brand_id>
    <brand_name>HomeDesign</brand_name>
    <category_id>25</category_id>
    <main_category>Křesla</main_category>
    <categories>Křesla</categories>
    <root_category>Nábytek</root_category>
    <breadcrumb>Nábytek | Křesla</breadcrumb>
    <master_id>1001</master_id>
    <is_master>false</is_master>
    <store_count>3</store_count>
    <delivery_delay>0</delivery_delay>
    <param>
        <name>Barva</name>
        <value>tmavě modrá</value>
    </param>
    <badge>
        <front_text>Doprava zdarma</front_text>
        <front_text_color>#ffffff</front_text_color>
        <front_background_color>#000000</front_background_color>
    </badge>
    <price>5490</price>
    <stock_info>
        <text>Skladem</text>
        <status>in_stock</status>
    </stock_info>
    <in_stock>true</in_stock>
</item>

Samostatný produkt bez variant

<item>
    <id>3001</id>
    <name>LED stolní lampa</name>
    <code>LED-001</code>
    <ean>8590000000010</ean>
    <url>https://www.example.com/led-stolni-lampa/</url>
    <image>https://www.example.com/images/lampa-50.jpg</image>
    <image_2x_link>https://www.example.com/images/lampa-500.jpg</image_2x_link>
    <brand_name>LightCo</brand_name>
    <main_category>Stolní lampy</main_category>
    <categories>Stolní lampy</categories>
    <categories>Kancelář</categories>
    <root_category>Svítidla</root_category>
    <breadcrumb>Svítidla | Stolní lampy</breadcrumb>
    <is_master>false</is_master>
    <store_count>23</store_count>
    <delivery_delay>0</delivery_delay>
    <param>
        <name>Příkon</name>
        <value>12 W</value>
    </param>
    <param>
        <name>Materiál</name>
        <value>Hliník</value>
    </param>
    <price>1299</price>
    <stock_info>
        <text>Skladem 23 ks</text>
        <status>in_stock</status>
    </stock_info>
    <in_stock>true</in_stock>
    <reviews_rating>4.7</reviews_rating>
    <reviews_count>42</reviews_count>
    <badge>
        <front_text>Novinka</front_text>
        <front_text_color>#ffffff</front_text_color>
        <front_background_color>#2563eb</front_background_color>
    </badge>
</item>

<item>
    <id>4001</id>
    <name>Běžecké boty ProRun</name>
    <url>https://www.example.com/bezecke-boty/</url>
    <image>https://www.example.com/images/boty-50.jpg</image>
    <image_2x_link>https://www.example.com/images/boty-500.jpg</image_2x_link>
    <is_master>false</is_master>
    <price>2499</price>
    <old_price>2999</old_price>
    <discount_in_percent>17</discount_in_percent>
    <price_with_code>
        <price>
            <value>1999</value>
            <view>1 999 Kč</view>
        </price>
        <code>SPORT20</code>
        <datetime>2026-06-30T23:59:59+02:00</datetime>
    </price_with_code>
    <stock_info>
        <text>Skladem 8 ks</text>
        <status>in_stock</status>
    </stock_info>
    <in_stock>true</in_stock>
    <badge>
        <front_text>Akce</front_text>
        <front_text_color>#ffffff</front_text_color>
        <front_background_color>#dc2626</front_background_color>
    </badge>
</item>

Produkt s víceměnovými cenami (CZK + EUR)

<item>
    <id>5001</id>
    <name>Venkovní svítidlo</name>
    <url>https://www.example.com/venkovni-svitidlo/</url>
    <image>https://www.example.com/images/svitidlo-50.jpg</image>
    <image_2x_link>https://www.example.com/images/svitidlo-500.jpg</image_2x_link>
    <is_master>false</is_master>
    <price>2225</price>
    <price_EUR>89</price_EUR>
    <stock_info>
        <text>Skladem</text>
        <status>in_stock</status>
    </stock_info>
    <in_stock>true</in_stock>
    <sold_count>15</sold_count>
</item>

Poznámky k implementaci

Master produkty vs. varianty

Master produkt a jeho varianty jsou samostatné <item> elementy propojené přes <master_id>
Master produkt má <is_master>true</is_master> a <master_id> rovné vlastnímu <id>
Varianty mají <is_master>false</is_master> a <master_id> odkazující na master
Rozdíly mezi variantami jsou typicky v názvu a v <param> (Barva, Velikost apod.)

Ceny

Stačí poslat <price> jako číslo — formátování se provede automaticky podle nastavení měny v Sales Channelu
U master produktů: pokud chcete prefix "od" (např. "od 4 990 Kč"), použijte volitelný <price_view> s vlastním textem
<old_price>: původní cena před slevou — old_price_view se vygeneruje automaticky
price_with_code: volitelná zvýhodněná cena s promo kódem a expirací

Obrázky

image — menší rozlišení pro autocomplete/náhledy (min. 50×50 px)
image_2x_link — plné rozlišení pro detail (min. 500×500 px)
image_alternative — volitelný druhý obrázek
Doporučené minimální rozlišení: 50×50 px (autocomplete), 500×500 px (detail)

Kategorie

Element <categories> se může opakovat (produkt ve více kategoriích)
breadcrumb obsahuje hierarchickou cestu oddělenou |

Badge styly

Důležité

Barvy pro badge musí být zadány ve formátu HEX (#RRGGBB), ne jako CSS třídy. Barvy se aplikují jako inline CSS styly.

Doporučené barvy pro badge:

Typ badge	Barva pozadí	Barva textu	Použití
Bestseller	`#10b981` (zelená)	`#ffffff` (bílá)	Nejprodávanější produkty
Novinka	`#2563eb` (modrá)	`#ffffff` (bílá)	Nové produkty
Sleva / Akce	`#dc2626` (červená)	`#ffffff` (bílá)	Produkty v akci
Limitovaná edice	`#FFCF00` (žlutá)	`#26237b` (tmavá)	Omezené edice
Doprava zdarma	`#64a81b` (tmavě zelená)	`#ffffff` (bílá)	Produkty s dopravou zdarma

Validátor feedu

Ověřte strukturu vašeho produktového feedu pomocí XML Feed Validátoru — zkontroluje povinná pole, datové typy a vnořené struktury.

Struktura feedu​

Kořenový element​

Element <item>​

Základní identifikátory​

Základní informace​

Obrázky​

Brand a kategorie​

Skladové informace​

Ceny​

Volitelné přepsání formátu ceny​

Víceměnové ceny​

Cena s promo kódem (price_with_code)​

Hodnocení​

Dárky (gifts)​

Další pole​

Parametry produktu​

Badge (označení)​

Master produkty a varianty​

Pravidla​

Jak to funguje​

Datové typy​

Příklady XML struktur​

Master produkt s variantami (barva)​

Samostatný produkt bez variant​

Produkt ve slevě s promo kódem​

Produkt s víceměnovými cenami (CZK + EUR)​

Poznámky k implementaci​

Master produkty vs. varianty​

Ceny​

Obrázky​

Kategorie​

Badge styly​

Struktura feedu

Kořenový element

Element `<item>`

Základní identifikátory

Základní informace

Obrázky

Brand a kategorie

Skladové informace

Ceny

Volitelné přepsání formátu ceny

Víceměnové ceny

Cena s promo kódem (`price_with_code`)

Hodnocení

Dárky (gifts)

Další pole

Parametry produktu

Badge (označení)

Master produkty a varianty

Pravidla

Jak to funguje

Datové typy

Příklady XML struktur

Master produkt s variantami (barva)

Samostatný produkt bez variant

Produkt ve slevě s promo kódem

Produkt s víceměnovými cenami (CZK + EUR)

Poznámky k implementaci

Master produkty vs. varianty

Ceny

Obrázky

Kategorie

Badge styly