XML feed pro Heureku a Zboží.cz

Co je XML feed

Feed je XML soubor, který e-shop vystavuje na stálé adrese (například https://www.example.cz/feed/heureka.xml). Srovnávač si ho pravidelně stahuje a podle něj aktualizuje ceny, dostupnost a popisy zboží. Feed obvykle generuje e-shopová platforma nebo doplněk; ruční úpravy se dělají jen výjimečně.

Oba srovnávače používají podobnou strukturu: kořenový element <SHOP> a v něm jeden <SHOPITEM> pro každý produkt, respektive každou variantu produktu. Názvy elementů se píší velkými písmeny — XML rozlišuje velikost písmen, takže <shopitem> je pro srovnávač neznámý element.

Oficiální specifikace: Heureka.cz — XML feed a Seznam Nákupy (Zboží.cz) / Sklik — specifikace XML feedu.

Feed pro Heureka.cz

<?xml version="1.0" encoding="utf-8"?>
<SHOP>
  <SHOPITEM>
    <ITEM_ID>HRN-03-CERNY</ITEM_ID>
    <PRODUCTNAME>Keramický hrnek Kerano Crema 0,3 l černý</PRODUCTNAME>
    <DESCRIPTION>Hrnek z odolné keramiky, vhodný do myčky i mikrovlnné trouby.</DESCRIPTION>
    <URL>https://www.example.cz/hrnek-crema-03l-cerny/</URL>
    <IMGURL>https://www.example.cz/img/hrnek-crema-cerny.jpg</IMGURL>
    <PRICE_VAT>199</PRICE_VAT>
    <MANUFACTURER>Kerano</MANUFACTURER>
    <CATEGORYTEXT>Heureka.cz | Dům a zahrada | Kuchyně | Hrnky a šálky</CATEGORYTEXT>
    <EAN>8595028412345</EAN>
    <DELIVERY_DATE>0</DELIVERY_DATE>
    <PARAM>
      <PARAM_NAME>Barva</PARAM_NAME>
      <VAL>černá</VAL>
    </PARAM>
    <DELIVERY>
      <DELIVERY_ID>ZASILKOVNA</DELIVERY_ID>
      <DELIVERY_PRICE>79</DELIVERY_PRICE>
      <DELIVERY_PRICE_COD>99</DELIVERY_PRICE_COD>
    </DELIVERY>
  </SHOPITEM>
</SHOP>

• ITEM_ID je jedinečný kód produktu v e-shopu. Specifikace povoluje nejvýš 36 znaků z písmen bez diakritiky, číslic, podtržítka a pomlčky.
• PRODUCTNAME má obsahovat výrobce, produktovou řadu a rozlišující vlastnosti varianty (nejvýš 200 znaků).
• PRICE_VAT je konečná cena v Kč včetně DPH, nejvýš se dvěma desetinnými místy.
• CATEGORYTEXT je celá cesta ve stromu kategorií Heureky včetně úvodního Heureka.cz |, například Heureka.cz | Velké spotřebiče | Pračky a sušičky | Pračky. Cestu bez tohoto prefixu nápověda Heureky uvádí jako špatný příklad.
• DELIVERY_DATE je počet dní do expedice, nebo datum ve formátu RRRR-MM-DD, od kterého bude zboží dostupné (využívá se u předobjednávek nových produktů). Když dodací dobu neuvedete, Heureka zobrazí „info v obchodu“.
• DELIVERY se opakuje pro každý způsob dopravy; kódy dopravců (DELIVERY_ID) určuje specifikace.

Feed pro Zboží.cz

Seznam dnes tuto inzerci nazývá Seznam Nákupy a spravuje ji přes Sklik. Zboží.cz je jedním z míst, kde se nabídky zobrazují; stejný feed plní i reklamy ve vyhledávání Seznamu. Formát feedu se změnou názvu nezměnil.

<?xml version="1.0" encoding="utf-8"?>
<SHOP xmlns="http://www.zbozi.cz/ns/offer/1.0">
  <SHOPITEM>
    <ITEM_ID>HRN-03-CERNY</ITEM_ID>
    <PRODUCTNAME>Kerano Crema hrnek 0,3 l černý</PRODUCTNAME>
    <DESCRIPTION>Hrnek z odolné keramiky, vhodný do myčky i mikrovlnné trouby.</DESCRIPTION>
    <URL>https://www.example.cz/hrnek-crema-03l-cerny/</URL>
    <PRICE_VAT>199</PRICE_VAT>
    <DELIVERY_DATE>0</DELIVERY_DATE>
    <IMGURL>https://www.example.cz/img/hrnek-crema-cerny.jpg</IMGURL>
    <EAN>8595028412345</EAN>
    <PARAM>
      <PARAM_NAME>objem</PARAM_NAME>
      <VAL>0.3</VAL>
      <UNIT>l</UNIT>
    </PARAM>
  </SHOPITEM>
</SHOP>

Hlavní rozdíl je jmenný prostor http://www.zbozi.cz/ns/offer/1.0 na kořenovém elementu. Všechny elementy feedu v něm musí být; bez deklarace ho Zboží.cz nerozpozná. Víc o tom, jak výchozí jmenný prostor funguje, v kapitole Jmenné prostory.

• DESCRIPTION, IMGURL a DELIVERY_DATE jsou pro Zboží.cz povinné. Popis má být prostý text bez reklamních sloganů.
• CATEGORYTEXT musí odpovídat kategorii ze stromu Zboží.cz; jednotlivé úrovně se oddělují svislou čarou |.
• EPREL_ID je povinný u výrobků s energetickým štítkem EU. Jde o unikátní identifikátor výrobku z evropské databáze EPREL.
• PARAM může kromě názvu a hodnoty obsahovat i jednotku (UNIT).
• Zboží.cz zná řadu dalších elementů, například PRICE_BEFORE_DISCOUNT, CONDITION pro použité zboží nebo MAX_CPC pro nastavení ceny za proklik.

Kódování: Heureka pracuje s UTF-8. Specifikace Zboží.cz připouští i jiné kódování (například windows-1250), musí ho ale uvádět XML deklarace. Nejbezpečnější volbou pro oba srovnávače je UTF-8.

Feed pro Google Merchant Center

Google Nákupy čtou produkty z Merchant Center. XML feed tam má jinou stavbu než u českých srovnávačů: je to kanál RSS 2.0 (Google popisuje i variantu Atom 1.0) a údaje o produktu jsou elementy ve jmenném prostoru http://base.google.com/ns/1.0 s prefixem g:.

<?xml version="1.0" encoding="UTF-8"?>
<rss xmlns:g="http://base.google.com/ns/1.0" version="2.0">
  <channel>
    <title>Obchod s hrnky</title>
    <link>https://www.example.cz/</link>
    <description>Produkty obchodu</description>
    <item>
      <g:id>HRN-03-CERNY</g:id>
      <title>Keramický hrnek Kerano Crema 0,3 l černý</title>
      <link>https://www.example.cz/hrnek-crema-03l-cerny/</link>
      <description>Hrnek z odolné keramiky, vhodný do myčky i mikrovlnné trouby.</description>
      <g:image_link>https://www.example.cz/img/hrnek-crema-cerny.jpg</g:image_link>
      <g:condition>new</g:condition>
      <g:availability>in stock</g:availability>
      <g:price>199.00 CZK</g:price>
      <g:brand>Kerano</g:brand>
      <g:gtin>8595028412345</g:gtin>
    </item>
  </channel>
</rss>

• Každá položka item musí mít RSS elementy title, link a description, i když jsou v RSS 2.0 jinak nepovinné.
• Produktové údaje (g:id, g:price, g:availability, g:condition …) bez prefixu g: Google ignoruje. Prefix musí být deklarovaný na kořeni, jinak parser feed odmítne (viz nedeklarovaný prefix).
• Cena obsahuje kód měny (199.00 CZK), na rozdíl od Heureky, kde je PRICE_VAT jen číslo.
• Povolené hodnoty a další atributy (kategorie, doprava, varianty) určuje specifikace produktových dat Merchant Center. Ověř je tam, nepřebírej hodnoty z feedu pro Heureku.

Rozdíly v přehledu

Hodnota DELIVERY_DATE vyjadřuje dostupnost ve dnech, ale škály se liší:

Kvůli jmennému prostoru a rozdílným povinným elementům je nejjednodušší generovat pro každý srovnávač samostatný feed.

Nejčastější chyby ve feedu

1. Neescapované speciální znaky. Znak & nebo < v názvu či popisu udělá z feedu neplatné XML a srovnávač zpracování ukončí:

<!-- chybně: znak & ukončí zpracování feedu -->
<PRODUCTNAME>Pepř & sůl mlýnek</PRODUCTNAME>

<!-- správně: entita, nebo sekce CDATA -->
<PRODUCTNAME>Pepř &amp; sůl mlýnek</PRODUCTNAME>
<DESCRIPTION><![CDATA[Sada 2 mlýnků na pepř & sůl, výška 18 cm]]></DESCRIPTION>

2. Neuzavřené elementy — často vzniknou, když se generování feedu v půlce přeruší.
3. Malá písmena v názvech elementů (<price_vat> místo <PRICE_VAT>).
4. Neplatné URL — mezery, chybějící https:// nebo relativní adresy.
5. Chybějící jmenný prostor ve feedu pro Zboží.cz.
6. Nesoulad s webem — cena nebo dostupnost ve feedu jiná než na stránce produktu.

Chyby 1–3 odhalí každý XML parser; co znamenají jednotlivé hlášky, vysvětluje kapitola Jak funguje XML. Chyby 3–5 a další porušení specifikace (formát ceny a dostupnosti, EAN, kódy dopravců, duplicitní ITEM_ID) najde náš validátor XML feedu pro Heureku a Zboží.cz, který u každé chyby ukáže položku a řádek. Feed se přitom nikam neodesílá, zpracuje se jen v prohlížeči.