Klávesové zkratky na tomto webu Na obsah stránky
Seznam.cz

Zboží.cz

Specifikace XML pro internetové obchody

Specifikace XML pro internetové obchody

Co je XML feed?

Jedná se o speciální datový soubor ve formátu XML, který obsahuje informace o nabízených položkách (název, popis, cena, údaje o dostupnosti apod.).

Generované XML si vytvářejí ve spolupráci se svými webmastery samy internetové obchody synchronně s databází uvedenou na stránkách internetového obchodu.

V případě, že si XML soubor tvoříte ručně, otevřete např. Poznámkový blok a na první řádek vložte hlavičku:

<?xml version="1.0" encoding="windows-1250"?>
(kódování zadejte dle použitého typu)

na druhý řádek napište: <SHOP>
na čtvrtý řádek napište: </SHOP>
mezi řádky s <SHOP> a </SHOP> vložte produkt spolu s jeho popisem - např.:
<SHOPITEM>
<PRODUCT>Světélkující podložka pod myš</PRODUCT>
<DESCRIPTION>Fosforeskující okraj, nevyžaduje baterie.</DESCRIPTION>
<URL>http://obchod.cz/podlozky-pod-mys/fosfor</URL>
<ITEM_TYPE>new</ITEM_TYPE>
<DELIVERY_DATE>1</DELIVERY_DATE>
<IMGURL>http://obchod.cz/obrazky/podlozky-pod-mys/fosfor.jpg</IMGURL>
<PRICE>620</PRICE>
<PRICE_VAT>756</PRICE_VAT>
</SHOPITEM>

Výsledný soubor nahrajte na Vaše stránky tak, aby byl k dispozici pro pravidelné stahování naším robotem.

UPOZORNĚNÍ
Jestliže Váš XML feed obsahuje řádově desetitisíce položek, doporučujeme jej rozdělit na více částí, případně komprimovat do archivu ZIP či gzip (robot dokáže pracovat i s komprimovanými archivy).

Význam jednotlivých značek

<SHOP>

povinné

Kořenová značka, v jejímž rámci je vše ostatní.

<SHOPITEM>

povinné

V této značce jsou obsaženy informace týkající se 1 výrobku.

<PRODUCT>

nepovinné (pokud jsou uvedeny elementy PRODUCTNAME a PRODUCTNAMEEXT)

Hlavní název výrobku, který musí odpovídat jeho povaze. Musí obsahovat všechny potřebné údaje, aby byl výrobek pomocí názvu odlišitelný od ostatních položek. Může obsahovat informace, které jsou specifické pro daný obchod, např. "... + dárek zdarma". Název nesmí obsahovat:

  • reklamní slogany a superlativy (např. "nejlevnější obchod")
  • nadměrně se opakující klíčová slova či fráze (dvakrát či vícekrát za sebou)
  • nadměrnou interpunkci, smajlíky, tři tečky a vykřičníky
  • informace, které přímo nesouvisí s nabízeným produktem

Maximální zobrazovaná délka je 64 znaků, přičemž za tečkami a čárkami musejí být mezery, jak je běžné v českých textech. V názvu položky zboží smí být pouze jeden vykřičník. Před vykřičníkem nesmí být mezera.
Pokud element není uveden, tak se automaticky vytvoří z PRODUCTNAME a PRODUCTNAMEEXT.

<PRODUCTNAME>

nepovinné

Krátký název výrobku včetně značky, ale bez přívlastků a parametrů. Tento element se spolu s PRODUCTNAMEEXT používá při zakládání nových výrobků do produktové databáze. Nesmí obsahovat žádné prvky, které by byly specifické jen pro daný obchod – jde o obecné pojmenování výrobku z pohledu spotřebitele.

<DESCRIPTION>

povinné

Popis výrobku. Obsahuje výhradně informace o produktu v českém jazyce, nesmí obsahovat:

  • reklamní texty a slogany týkající se internetového obchodu
  • nadměrně se opakující klíčová slova nebo fráze (dvakrát či vícekrát za sebou)

Není povolena nadměrná interpunkce, smajlíky nebo tři tečky. Za tečkami a čárkami musejí být mezery, jak je běžné v českých textech. Před vykřičníkem nesmí být mezera.

<URL>

povinné

Odkaz na stránku s nabídkou daného výrobku.

<IMGURL>

nepovinné

Odkaz na obrázek výrobku, který jej věrně zobrazuje. Součástí obrázku nesmí být vodoznaky ani jiné výrazné grafické prvky. Obrázek může být ve formátu JPEG nebo PNG, ostatní formáty nejsou podporovány.

<PRICE>

nepovinné (v případě, že je uvedena značka PRICE_VAT)

Cena v Kč bez DPH. Akceptována je pouze číselná hodnota bez mezer mezi řády, k oddělení haléřů slouží tečka.

Ceny nižší než 1,- Kč s DPH jsou zaokrouhlovány na setiny haléřů.
Ceny vyšší než 1,- Kč jsou standardně zaokrouhlovány na celé koruny.

Příklad:

<PRICE> 12345.50 </PRICE>

<VAT>

povinné v případě, že je uvedena značka PRICE

Procentní sazba DPH.

Příklad:

<VAT> 21 </VAT>
<VAT> 0.21 </VAT>
Oba výše uvedené zápisy jsou ekvivalentní a představují 21% sazbu DPH.

<PRICE_VAT>

nepovinné v případě, že jsou uvedeny značky PRICE a VAT

Cena v Kč včetně DPH.

<MAX_CPC>

nepovinné

Maximální cena za proklik v Kč. Akceptována je číselná hodnota bez mezer mezi řády, k oddělení haléřů slouží tečka. Přípustná hodnota je z intervalu 1 až 500 Kč. Pro odstranění předchozího nastavení slouží prázdná hodnota. Element je ignorován, pokud je pro stejnou nabídku uveden element <UNFEATURED> s hodnotou 1.

<MAX_CPC> 23.50 </MAX_CPC>

<DUES>

povinné (pokud se poplatky vztahují k nabízenému sortimentu a nejsou již obsaženy v ceně)

Součet veškerých poplatků, které je nutné zaplatit při zakoupení výrobku (cena uvedena včetně DPH, nezahrnuje dopravu a balné). Poplatek je připočten k ceně výrobku s DPH.

<DELIVERY_DATE>

povinné

Doba vyřízení objednávky - musí být uváděna jako doba od přijetí objednávky do expedice zboží. Číselná hodnota je poté systémem automaticky převáděna na textové vyjádření.

  • Zboží skladem se může uvést jako: 
    <DELIVERY_DATE> 0 </DELIVERY_DATE>
    <DELIVERY_DATE> ihned </DELIVERY_DATE>
  • Je možné uvádět dodací dobu ve dnech (pouze celočíselná hodnota): 
    <DELIVERY_DATE> 5 </DELIVERY_DATE>
  • Dostupnost uvedená datem - od tohoto data bude produkt dostupný: 
    <DELIVERY_DATE> 2013-04-26 </DELIVERY_DATE>
  • Zboží je nedostupné: 
    <DELIVERY_DATE> -1 </DELIVERY_DATE>
Dostupnost se pak zobrazuje jako jedna z možností:
  • skladem – 0 dní
  • do týdne – 1-6 dní
  • více jak týden – 7 a více dní

Hodnota DELIVERY_DATE Přípustná vyjádření na stránkách obchodu
Skladem
(hodnota 0)
  • skladem
  • skladem u dodavatele, expedice do 24 hodin
  • skladem v expedičním skladu, expedice do 24 hodin
  • skladem na prodejně
  • ihned (k odběru)
  • expedice do 24 hodin
  • počet kusů > 0
Do týdne v e-shopu
(hodnoty 1-6)
  • skladem, dodání do 2-5 pracovních dnů
  • do 2 dnů
  • skladem (expedice do 2 pracovních dnů)
  • obvykle skladem
  • obvykle expedujeme do 2 dnů
  • skladem u dodavatele
  • obvykle do 2 dnů
  • 3-4 dny
Více jak týden
(hodnota 7 a více)
  • 7 a více dní
  • na dotaz
  • na objednávku
Neznámá dostupnost
(hodnota "-1")
  • neuvedená dostupnost v detailu produktu
  • neznámá

<SHOP_DEPOTS>

nepovinné

Tzv. identifikátor výdejního místa, ve kterých je položka skladem k okamžitému osobnímu odběru. Na výdejním místě musí být možné výrobek prohlédnout, vyzkoušet a případně reklamovat.

O přidělení identifikátoru je potřeba požádat na e-mailové adrese zbozi@firma.seznam.cz. V e-mailu uveďte IČ, název společnosti a adresu kamenné prodejny či výdejního místa. Přidělený identifikátor se vztahuje pouze k jednomu IČ obchodu a jeho provozovnám. Jednotlivé identifikátory je možno oddělit středníkem. Po přidělení identifikátoru je obchod zařazen do filtru "Kraj".

<ITEM_TYPE>

nepovinné v případě, že je zboží nové

Udává, zda se jedná o nové či bazarové (použité, renovované, repasované) zboží.

Nová položka: 
<ITEM_TYPE> new </ITEM_TYPE>
Bazarová položka: 
<ITEM_TYPE> bazaar </ITEM_TYPE>

<UNFEATURED>

nepovinné

Slouží k označení nabídek, které nemají být upřednostňovány. Výchozí hodnota je 0 – veškeré nabídky tedy budou upřednostněny.

Element UNFEATURED nahrazuje původní TOLLFREE, který je nadále podporován.

Nabídka bude upřednostněna: 
<UNFEATURED> 0 </UNFEATURED>
Nabídka nebude upřednostněna: 
<UNFEATURED> 1 </UNFEATURED>

<EXTRA_MESSAGE>

nepovinné

Slouží k uvedení doplňkových informací o nabídce. U 1 položky lze použít pouze 1 hodnotu z níže uvedené tabulky.

Text se zobrazuje u ceny položky v produktovém detailu:

Hodnota EXTRA_MESSAGE Text zobrazovaný na Zboží.cz
extended_warranty Prodloužená záruka
free_accessories Příslušenství zdarma
free_case Pouzdro zdarma
free_delivery Doprava zdarma
free_gift Dárek zdarma
free_installation Montáž zdarma
free_store_pickup Osobní odběr zdarma

<FIRMY_CZ>

nepovinné

Internetový obchod, který má placený zápis na službě Firmy.cz si může určit až 5 položek, které se budou zobrazovat v detailu zápisu v sekci "Aktuální nabídka".

Položka se bude zobrazovat ve firemním zápise: 
<FIRMY_CZ> 1 </FIRMY_CZ>
Položka se nebude zobrazovat ve firemním zápise: 
<FIRMY_CZ> 0 </FIRMY_CZ>

V případě, že se tento tag v XML feedu nenachází nebo je hodnotou 1 označeno více jak 5 položek, systém zobrazí náhodně vybrané položky.

<MANUFACTURER>

nepovinné

Název výrobce produktu.

<CATEGORYTEXT>

nepovinné

Uvedený CATEGORYTEXT napomáhá správnému zařazení produktu do kategorie. Uvádějte vždy celou cestu k produktu. Pokud je výrobek v několika kategoriích, můžete element zopakovat. Preferovaný oddělovač je znak " | ". Lze použít i znaky " - " nebo " > " (je třeba použít entitu &gt;). Např.:

<CATEGORYTEXT>Foto | Paměťové karty | Compact Flash</CATEGORYTEXT>
<CATEGORYTEXT>MP3 | Paměťové karty | Compact Flash</CATEGORYTEXT>

<EAN>

nepovinné (doporučujeme jej ale uvádět)

Kód výrobku EAN13 – musí se jednat o validní kód včetně kontrolní číslice. EAN kód výrazně napomáhá správnému napárování do skupin výrobků. Element je možné opakovat.

<PRODUCTNO>

nepovinné

Kód výrobku udávaný výrobcem, u knih např. ISBN. Neuvádějte zde vlastní kódy výrobků.

Tvorba variant produktů

<VARIANT>

nepovinné

Varianty produktů (např. různé barvy mobilních telefonů nebo velikosti oblečení). Element je uvnitř elementu SHOPITEM a zároveň může obsahovat stejné elementy jako SHOPITEM (všechny jsou nepovinné). Varianta produktu se chápe jako samostatný produkt, potřebná data se načtou nejprve ze samotného elementu VARIANT, pokud tam nejsou, tak se načtou (zdědí) z vnějšího elementu SHOPITEM. V okamžiku, kdy je uveden jeden element VARIANT, tak je výsledkem jeden produkt. U samotných variant není vyžadována jedinečná hodnota elementu URL, je ale nutné zajistit jedinečnost kombinace URL, PRODUCTNAME a PRODUCTNAMEEXT. Příklad elementu SHOPITEM s variantami:

<SHOPITEM>
     <PRODUCTNAME>Nokia Lumia 800</PRODUCTNAME>
     <MANUFACTURER>Nokia</MANUFACTURER>
     <URL> ... </URL>
     <IMGURL> ... </IMGURL>
     <VARIANT>
          <PRODUCTNAMEEXT>Black</PRODUCTNAMEEXT>
          <IMGURL> ... </IMGURL>
          <PRICE_VAT> ... </PRICE_VAT>
          <EAN> ... </EAN>
          <PRODUCTNO> ... </PRODUCTNO>
     </VARIANT>
     <VARIANT>
          <PRODUCTNAMEEXT>Red</PRODUCTNAMEEXT>
          <IMGURL> ... </IMGURL>
          <PRICE_VAT> ... </PRICE_VAT>
          <EAN> ... </EAN>
          <PRODUCTNO> ... </PRODUCTNO>
     </VARIANT>
</SHOPITEM>

<PRODUCTNAMEEXT>

nepovinné

Jedná se o hodnotu parametru tvořícího variantu. Popis výrobku se nadále uvádí v elementu DESCRIPTION. Element má stejné použití jako PRODUCTNAME a platí pro něj stejná pravidla

Příklad feedu

<? xml version="1.0" encoding="windows-1250" ?>
<SHOP>

<SHOPITEM>
<PRODUCT>ACER P225HQ</PRODUCT>
<DESCRIPTION>LCD monitor s Full HD rozlišením</DESCRIPTION>
<URL>http://www.obchod.cz/acer-p225hq/</URL>
<ITEM_TYPE>new</ITEM_TYPE>
<DELIVERY_DATE>1</DELIVERY_DATE>
<IMGURL>http://obchod.cz/obrazky/acer-p225hq.jpg</IMGURL>
<PRICE>2500</PRICE>
<PRICE_VAT>3000</PRICE_VAT>
</SHOPITEM>

<SHOPITEM>
<PRODUCT>Podložka pod myš - kočka</PRODUCT>
<DESCRIPTION>Ergonomická podložka pod myš, potisk s .</DESCRIPTION> 
<DUES>20</DUES>
<ITEM_TYPE>bazaar</ITEM_TYPE>
<DELIVERY_DATE>0</DELIVERY_DATE>
<SHOP_DEPOTS>111</SHOP_DEPOTS>
<IMGURL>http://obchod.cz/obrazky/podlozky-pod-mys/kocka.jpg</IMGURL>
<PRICE>420</PRICE>
<PRICE_VAT>512</PRICE_VAT>
<UNFEATURED>1</UNFEATURED>
</SHOPITEM>

</SHOP>

V případě, že se v XML feedu vyskytují jiné značky než výše uvedené, nebudou systémem zpracovány.

Nejčastější chyby v XML feedech

Chyba parsování (pars-error)

Chyba vzniká použitím neplatných či nestandardních znaků (diakritika, mezera apod.).

Příklad chyby:

<PRODUCT>Světélkující podložka pod myš, rozměry < 20x20cm </PRODUCT>
<IMGURL>http://obchod.cz/obrazky/podložky pod myš/fosfor.jpg</IMGURL>

Řešení:

Tyto znaky je potřeba nahradit alternativou.

Překřížení XML značek

Při tvorbě XML feedu je třeba dodržovat posloupnost "otevírání" a "zavírání" tagů.

Příklad chyby:

<SHOP>
<SHOPITEM>
<PRODUCT>Světélkující podložka pod myš</PRODUCT>
<DESCRIPTION>Fosforeskující okraj, nevyžaduje baterie.</DESCRIPTION>
<URL>http://obchod.cz/podlozky-pod-mys/fosfor</URL>
<IMGURL>http://obchod.cz/obrazky/podlozky-pod-mys/fosfor.jpg</IMGURL>
<PRICE>620</PRICE>
<PRICE_VAT>756</PRICE_VAT>
</SHOP>
</SHOPITEM>

Absence XML značky

XML tagy jsou párové, tzn. je třeba je otevřít a následně také uzavřít:

<SHOP> ... </SHOP>

Příklad chyby:

<SHOP>
<SHOPITEM>
<PRODUCT>Světélkující podložka pod myš</PRODUCT>
<DESCRIPTION>Fosforeskující okraj, nevyžaduje baterie.</DESCRIPTION>
<URL>http://obchod.cz/podlozky-pod-mys/fosfor</URL>
<IMGURL>http://obchod.cz/obrazky/podlozky-pod-mys/fosfor.jpg</IMGURL>
<PRICE>620</PRICE>
<PRICE_VAT>756</PRICE_VAT>
</SHOPITEM>     (chybí)
</SHOP>

Umístění tagu mimo povolený tag

Je potřeba dodržovat umístění jednotlivých tagů v XML feedu.

Příklad chyby:

<SHOP>
<DESCRIPTION>Obchod se vším možným</DESCRIPTION>
<SHOPITEM>
<PRODUCT>Světélkující podložka pod myš</PRODUCT>
<DESCRIPTION>Fosforeskující okraj, nevyžaduje baterie.</DESCRIPTION>
<URL>http://obchod.cz/podlozky-pod-mys/fosfor</URL>
<IMGURL>http://obchod.cz/obrazky/podlozky-pod-mys/fosfor.jpg</IMGURL>
<PRICE>620</PRICE>
<PRICE_VAT>756</PRICE_VAT>
</SHOPITEM>
</SHOP>

Zkomolení XML tagu

Příklad chyby:

<SCHOP>
<SHOPITEM>
<PRODUCT>Světélkující podložka pod myš</PRODUCT>
<DESCRIPTION>Fosforeskující okraj, nevyžaduje baterie.</DESCRIPTION>
<URL>http://obchod.cz/podlozky-pod-mys/fosfor</URL>
<IMGURL>http://obchod.cz/obrazky/podlozky-pod-mys/fosfor.jpg</IMGURL>
<PRICE>620</PRICE>
<PRICE_VAT>756</PRICE_VAT>
</SHOPITEM>
</SHOP>

Chybný Content-Type

Nejčastěji je v nastavení serveru je XML feed deklarován místo text/xml jako text/html.

Náprava:

Provést přenastavení serveru.

Chyba stahování (false-download)

Feed není dostupný, pravděpodobně jste zadali špatnou URL XML feedu.

Náprava:

Zaslat nám e-mailem adresu umístění feedu

Nezobrazují se obrázky jednotlivých produktů

Pokud robot při zpracování XML feedu narazí na URL adresu obrázku, čeká na jeho stažení maximálně 5 vteřin. V případě, že se mu obrázek do 5 vteřin nepodaří stáhnout tak jej přeskočí a pokračuje dále ve zpracování feedu. Nastane-li tato chyba během zpracování 100x, nejsou již další obrázky stahovány. Pokud tedy nemáte dostatečně rychlý hosting nebo byl v průběhu stahování obrázků příliš vytížen, je možné že se nestáhly všechny obrázky.

Chybný formát ceny

Cena musí být zadána v následujícím formátu:

<PRICE> 12345.50 </PRICE>

Příklady chybného zadání:

<PRICE>12345.50 Kč</PRICE>
<PRICE>12 345.50</PRICE>
<PRICE>-12345.50</PRICE>
<PRICE>0</PRICE>

Požadavky na XML feedy pro rozšiřování produktové databáze

Do databáze výrobků zakládáme nové položky podle vlastního uvážení, avšak nebráníme se jejímu rozšiřování. Předpokladem je, aby tyto výrobky byly dostatečně známé nebo prodávané více obchody. Pokud Váš obchod dostatečně pokrývá nějaký segment trhu, který zatím v databázi chybí, a dokážete implementovat nový formát feedu, tak nám prosím dejte vědět URL na nový feed. My ověříme vhodnost dat a případně se pokusíme položky zařadit do databáze výrobků. XML feedy pro vyhledávání ve výrobcích budeme vybírat dle následujících kritérií:

  • názvy výrobků budou pokud možno rozdělené na dvě části, tak aby ty zásadní identifikační údaje pro daný výrobek byly oddělené od doplňujících údajů, např. „ACER K10“ bude v elementu PRODUCTNAME a „LED, SVGA (858 x 600), 100Lm, 1000:1“ v elementu PRODUCTNAMEEXT.
  • vyplněný element MANUFACTURER (výrobce)
  • kvalitní doplňující popisek v tagu DESCRIPTION bez reklamních textů
  • kvalitní obrázky (element IMGURL) bez vodoznaků či jiných grafických prvků v dostatečném rozlišení (minimální rozměr je 320x200 px)
  • vyplněné tagy PRODUCTNO a EAN (pokud je to možné a má v daném segmentu výrobků význam)
  • implementovaný element VARIANT (pokud má význam; např. barvy, velikosti apod.)
  • vyplněné kategorie – podle klasifikace eshopu (element CATEGORYTEXT)
Kompletní specifikace XML »

V případě, že máte XML feed odpovídající výše uvedeným požadavkům, kontaktujte nás prostřednictvím e-mailové adresy zbozi@firma.seznam.cz.

Párování položek

V detailech výrobků se zobrazují pouze nabídky obchodů využívající placené služby Zboží Standard. Párování nabídek obchodů do skupin probíhá automaticky podle:

  • názvu produktu
  • EAN kódu
  • jména výrobce
  • produktového čísla (kódu výrobce)
  • zařazení produktu do kategorie
  • popisu produktu
  • ceny položky *
* Cena Vaší položky je při zpracování porovnávána s cenovým rozpětím napárovaných nabídek k danému produktu. Jestliže je cena Vaší položky mimo tento cenový rozsah (systém pracuje vždy s určitou tolerancí), k napárování nedojde. Cílem je zamezit párování nesouvisejících položek nebo neoriginálních položek k originálním.

Nabídky se spolehlivě párují v případě, kdy je EAN kód a název produktu shodný s názvem a kódem produktu uvedeným na Zboží.cz. Zkontrolujte si tedy, prosím, zda Vámi uváděné názvy odpovídají běžným zvyklostem (např. oficiálním názvům výrobce). Pokud Vaše nabídka nebude obsahovat všechny výše zmíněné údaje ve správném a úplném formátu, může stát, že se produkt správně nenapáruje a nezobrazí se na Zboží.cz.

Nabídka se napárovala k jinému produktu

1) produkt existuje
– stačí upravit název (tagy PRODUCTNAME A PRODUCTNAMEEXT) dle produktu, který je již na Zboží.cz "založen"; název musí být zcela totožný

2) produkt neexistuje
– v tom případě kontaktujte administrátory služby

Nabídka se nenapárovala vůbec

1) máte chybu ve Vašem XML feedu
– respektive Vaše názvy se podstatně liší od těch, které odpovídají běžným zvyklostem a nezbývá než opravit tagy v XML a počkat na export dat na službu Zboží.cz, který probíhá 2x denně (Vaše nabídka se napáruje do jednoho až dvou dnů)

2) nejedná se o totožný druh zboží
– výsledek bude zobrazen ve fulltextovém vyhledávání do doby, než bude totožných nabídek dostatečné množství, aby je bylo možné spárovat

Seznam naimportovaných položek včetně informaci o jejich spárování či nespárování si můžete nechat zaslat na kontaktní e-mailovou adresu ve formátu .CSV prostřednictvím administračního rozhraní (kliknutím na tlačítko "Párování položek" v záložce Položka).

Pomohl Vám tento článek? Ne