Specifikace ASYMBO XML feedu Děkujeme, že máte zájem o mobilní e-shop ASYMBO! Aby vše fungovalo, jak má, připravili jsme pro vás detailní specifikaci XML souboru, kterým vzájemně komunikuje Váš e-shop s m-shopem ASYMBO. ASYMBO XML feed je kompatibilní s XML feedem od Heureky. Můžete tak použít stejný XML soubor, který používáte pro inzerci produktů na srovnávači zboží Heureka.cz. Pokud máte Heureka XML feed korektně zpracovaný podle specifikace od Heureky, nemusíte dělat žádné změny a váš m-shop bude správně fungovat. Doporučujeme vám však připravit samostatný feed pouze pro ASYMBO. ASYMBO XML feed totiž obsahuje oproti Heureka XML feedu pár užitečných věcí navíc. S jeho použitím tak například: zadáte libovolné názvy produktů bez jakýchkoliv omezení, vyplníte k produktům libovolně dlouhé popisky, jednodušeji a efektivněji zpracujete varianty produktů, popisky produktů vyšperkujete použitím HTML značek, máte možnost definovat vlastní dostupnost zboží pomocí delivery tagu, ASYMBO XML feed je několikanásobně menší a proto i stažení a parsování feedu je rychlejší a méně zatěžuje servery. ASYMBO XML feed je kompatibilní s Heureka XML feedem. Můžete jednoduše použít stejný XML soubor jako používáte pro inzerci produktů na zbožovém srovnávači Heureka.cz. 1
HLAVIČKA XML SOUBORU: <?xml version="1.0" encoding="utf-8"?> <SHOP> <SHOPITEM> Element, který označuje produkt. Nachází se na začátku a na konci každého produktu. <ITEM_ID> Unikátní označení produktu ve vašem e-shopu. Formát: 36 znaků [0-9a-zA-Z]. Každý produkt musí obsahovat <ITEM_ID>. <ITEM_ID>123456AB<ITEM_ID> <PRODUCT> A <PRODUCTNAME> Unikátní název produktu. Pokud máte vyplněny oba dva tagy, přednostně se bere tag <PRODUCT>. Pro ASYMBO m-shop nemusíte dodržovat žádná pravidla při pojmenovávání produktů. Jen doporučujeme nepřesahovat délku 25 znaků. <DESCRIPTION> Popis produktu může být libovolně dlouhý a může také obsahovat základní HTML značky: 2
<h1> - <h6> nadpisy <p> odstavec <a> odkaz s atributy href, name a target <strong> zvýrazněný text číslované a nečíslované seznamy <ul> <ol> <li> <img> obrázky s atributem src další HTML značky: blockquote, nl, b, i, strong, em, strike, code, hr, br, div, table, thead, caption, tbody, tr, th, td, pre Inline styly budou ignorovány, každý tag může mít nastaveno class nebo id a styly k tomu lze editovat v Asymbo administraci. Jiné HTML tagy, které jsou obsažené v popisku, se ignorují. Ve výpisu produktů v kategoriích se jako text anotace použije začátek popisku produktu. <DESCRIPTION> <h2>matrace Supragel Hard - popis</h2> <p>kvalitní <strong>matrace Supragel Hard</strong> střední tuhosti, která uspokojí široké spektrum uživatelů doporučujeme především pro mladé (do dětských pokojů pro mládež a dorost). Nosné jádro <strong>matrace Supragel Hard</strong> tvoří odolná pěna Flexifoam nové generace. Gelové výplně v bederní části jsou konstrukčně řešeny tak, aby dokázaly plně reflektovat i vyšší tělesnou hmotnost a usměrňovaly tento tlak tak, aby nedocházelo k narušení spánkového klidu vlivem přeležení.</p> <p>vyrábí se ve dvou tuhostech. Tzn. jedná se o dvě různé matrace:</p> <ul> <li><strong>matrace Supragel HARD</ strong> tužší pro muže</li> <li><strong>matrace Supragel SOFT</strong> měkčí pro ženy</li> </ul> </DESCRIPTION> <IMGURL> URL adresa hlavního obrázku. Doporučení pro obrázky je následující: 3
Optimální velikost obrázku je 1280px x 1280px V případě, že změníte obrázek je potřeba změnit jeho URL adresu Obrázek nesmí být s průhledným pozadím <IMGURL>http://www.nazev-domeny-eshopu.cz/img/nazev-obrazku.jpg</IMGURL> <IMGURL_ALTERNATIVE> URL adresa dalších obrázků k produktu. Můžete uvést tolikrát, kolik máte k produktu obrázků. <IMGURL_ALTERNATIVE>http://www.nazev-domeny-eshopu.cz/img/nazev-obrazku.jpg </IMGURL_ALTERNATIVE> <PRICE_VAT> Celková cena včetně DPH. Cenu můžete uvádět v těchto formátech: 32 000 32000 32000,50 32000.50 Posílaný formát ceny neovlivní zobrazení ceny v aplikaci. <PRICE_VAT>10990</PRICE_VAT> 4
<PRICE_COMMON_VAT> Původní cena před slevou. Formát může být stejný jako u <PRICE_VAT>. V aplikaci se zobrazí jako původní cena a vypočítá se z ní velikost slevy. <CATEGORYTEXT> Název kategorie včetně celkové cesty k produktu. <CATEGORYTEXT> Kateorie 1. úrovně Kategorie 2. úrovně Kategorie 3. úrovně</category- TEXT> Oddělovací znak mezi nadkategoriemi a podkategoriemi je mezera mezera. Úrovní kategorií může být neomezeně. Pokud máte produkt zařazen do více kategorií, stačí uvést tag <CATEGORYTEXT> vícekrát. <CATEGORYTEXT>Dům a zahrada Nábytek Matrace</CATEGORYTEXT> <CATEGORYTEXT>Matrace Pružinové matrace</categorytext> <CATEGORYTEXT>Matrace pro sportovce Pružinové metric</categorytext> <DELIVERY_DATE> A <DELIVERY> Dostupnost zboží lze vyjádřit dvěmi způsoby. Pomocí tagu <DELIVERY_DATE> nebo <DELIVERY>. Nepoužívejte oba tagy zároveň. <DELIVERY> <NAME>1-3 dní</name> <IS_STOCK>1</IS_STOCK> </DELIVERY> 5
V tagu name uvedete libovolný textový řetězec, který má vystihovat dostupnost zboží. Znění je naprosto na Vás. <IS_STOCK>1</IS_STOCK> je označení, že se jedná o položku skladem, v aplikaci bude nápis, který uvedete v tagu name zvýrazněn typicky zeleně nebo jinou barvou. <DELIVERY_DATE> V tagu delivery date uvádějte počet dní od přijetí objednávky do expedice zboží. Dostupnost se pak v m-shopu zobrazí dle uvedených dní: skladem 0 dní do 3 dnů - 1-3 dní do týdne 4-6 dní do 2 týdnů - 7-14 dní do měsíce - 14-30 dní více než měsíc - 31 a více dní <DELIVERY_DATE>5</DELIVERY_DATE> <MANUFACTURER> Název výrobce. <MANUFACTURER>Geltech</MANUFACTURER> 6
<PARAM> Prostor pro parametry produktů. Parametry se zobrazí přehledně v tabulce v detailech produktu v aplikaci. Nakupující také mohou podle parametrů filtrovat výpis produktů.. Těchto parametrů ve výchozím stavu můžete uvádět neomezeně. Parametry se používají také k označení variant produktů. Viz samostatná kapitola níže. TIP: Pořadí jednotlivých položek ve filtru ovlivníte pořadím parametrů. Který parametr u produktu vypís <PARAM> <NAME>Název parametru</name> <VAL>Hodnota prametru</val> </PARAM> <PARAM> <NAME>Velikost a rozlišení</name> <VAL>Malý do 13,4 </VAL> </PARAM> <PARAM> <NAME>Výbava</NAME> <VAL>WiFi</VAL> </PARAM> <PARAM> <NAME>Výbava</NAME> 7
<VAL>Bluetooth</VAL> </PARAM> <LABEL> K produktům je možnost přiřazovat štítky s ikonkami. Standardně nabízíme tuto sadu ikonek. Labely se zobrazují ve výpisu produktů a v detailu produktu. Ke každé ikonce lze přiřadit vlastní význam. <LABEL> <NAME>DOPRAVA ZDARMA</NAME> 8
</LABEL> <LABEL> <NAME>SKLADEM</NAME> </LABEL> <LABEL> <NAME>1+1 Zdarma</NAME> </LABEL> Postup: K produktům přiřaďte tag <LABEL> s názvy štítků dle svých potřeb Pošlete nám kterou ikonku ke kterému názvu byste chtěli zobrazit, na výběr je: Hvězda Štítek Procento Balík Dárek Vykřičník 9
Varianty produktů Pokud máte např. velikostní varianty produktů, existují dvě možnosti, jakým způsobem varianty do feedu zapracovat. ASYMBO způsob: K jednotlivým produktům přiřadíte varianty Heureka způsob: Každá varianta produktu je samostatný produkt Doporučujeme ASYMBO způsob, je zde menší pravděpodobnost chyb způsobených špatnými daty, feed je několikanásobně menší a tím je zpracování rychlejší. ASYMBO ZPŮSOB, TAG <VARIANT> Mezi tagy <shopitem> umístíte tag <variant>, ve kterém specifikujete vlastnosti varianty. Jednohodnotvé tagy (např. PRICE_VAT, PRODUCT, IMGURL) uvedené u varianty přepisují stejný tag bázového produktu. Skupinové tagy (např. IMGURL_ALTERNATIVE) bázový produkt rozšiřují. <VARIANT> <ITEM_ID>159743</ITEM_ID> <PRODUCT>boty STEEL - 10 dírkové černé ( 105/106 Black) 48</PRODUCT> <IMGURL>http://www.metalshop.cz/images/produkty/184_2.jpg</IMGURL> <IMGURL_ALTERNATIVE>http://www.metalshop.cz/images/produkty/184_2.jpg</ IMGURL_ALTERNATIVE> <IS_DEFAULT>1</IS_DEFAULT> <DELIVERY> <NAME>7-14 dni</name> </DELIVERY> <PARAM> <NAME>Velikost</NAME> <VAL>48</VAL> <IS_VARIANT>1</IS_VARIANT> </PARAM> <PARAM> <NAME>KOD</NAME> <VAL>12346</VAL> </PARAM> </VARIANT> 10
Pokud má jiný ITEM_ID, jiný stav skladu, parametry, obrázky, cena apod. lze tyto hodnoty přepsat. Lze použít takřka jakýkoliv tag kromě <CATEGORYTEXT>. Varianta nemůže být v jiných kateogorích než daný produkt. <IS_DEFAULT>1</IS_DEFAULT> Určuje variantu, která se má ve výchozím stavu uživateli otevřít pokud na výpisu produktů tapne na konkrétní produkt. <IS_VARIANT>1</IS_VARIANT> Určuje, který parametr se má brát jako varianta. V příkladu je tento tag určený u parametru velikost. Uživatelé si tedy budou na kartě produktu vybírat velikost. Každá varianta musí mít definováno své <ITEM_ID>. HEUREKA ZPŮSOB, KAŽDÁ VARIANTA JAKO SAMOSTATNÝ PRODUKT Aby varianty fungovalý správně, musí být korektně nastaveny tagy: <productname> <variant> <itemgroup_id> <PRODUCTNAME> V tagu productname je potřeba mít název produktu BEZ velikostního rozlišení. Všechny varianty se tedy budou tagu productname jmenovat stejně: <PRODUCTNAME>Název produktu</productname> 11
<VARIANT> V tomto tagu je nutné identifikovat alespoň jeden rozlišující parametr následujícím způsobem: <VARIANT> </VARIANT> <ITEM_ID>12345</ITEM_ID> <PARAM> <NAME>Rozměry</NAME> <VALUE>20m 3x1</VALUE> <IS_VARIANT>1</IS_VARIANT> </PARAM> Součástí tagu variant musí být <ITEM_ID> dané varianty. <ITEMGROUP_ID> Označení skupiny produktů které představují varianty. Každé variantě produktu přiřaďte stejné ITEMGROUP_ID. <ITEMGROUP_ID>2862</ITEMGROUP_ID> 12
XML FEED DEFINUJÍCÍ STRUKTURU KATEGORIÍ Jednoduchým samostatným XML feedem definujete strukturu kategorií. <SHOP> <CATEGORY> <NAME>Slevy</NAME> </CATEGORY> <CATEGORY> <NAME>Boty</NAME> <CATEGORY> <NAME>boty kožené</name> </CATEGORY> <CATEGORY> <NAME>boty street</name> </CATEGORY> </CATEGORY> <CATEGORY> <NAME>Doplňky na sebe</name> <CATEGORY> <NAME>kontaktní čočky</name> <CATEGORY> <NAME>čočky</NAME> </CATEGORY> <CATEGORY> <NAME>roztoky</NAME> </CATEGORY> </CATEGORY> </CATEGORY> </SHOP> 13
XML FEED AKTUALIZUJÍCÍ SKLADOVOST A CENY Pokud se ceny či dostupnost zboží mění každým okamžikem, posílejte nám tento aktualizační feed, který obsahuje tagy: <ITEM_ID> pro identifikaci produktu <PRICE_VAT> a <PRICE_COMMON_VAT> pro definici ceny <DELIVERY> pro definici dostupnosti <DELETE> pro stažení produktu z prodeje <?xml version="1.0" encoding="utf-8"?> <SHOP> <SHOPITEM> <ITEM_ID>186</ITEM_ID> <PRICE_VAT>1000</PRICE_VAT> </SHOPITEM> <SHOPITEM> <ITEM_ID>184</ITEM_ID> <PRICE_VAT>2000</PRICE_VAT> <PRICE_COMMON_VAT>2500</PRICE_COMMON_VAT> <DELIVERY> <NAME>1 den</name> <IS_STOCK>1</IS_STOCK> </DELIVERY> </SHOPITEM> <SHOPITEM> <ITEM_ID>185</ITEM_ID> <DELETE>1</DELETE> </SHOPITEM> <SHOPITEM> <ITEM_ID>185</ITEM_ID> <VARIANT> <ITEM_ID>60026</ITEM_ID> <PRICE_VAT>1500</PRICE_VAT> <PRICE_COMMON_VAT>1600</PRICE_COMMON_VAT> 14
<DELIVERY> <NAME>1 tyden</name> </DELIVERY> </VARIANT> <VARIANT> <ITEM_ID>60027</ITEM_ID> <DELETE>1</DELETE> </VARIANT> </SHOPITEM> </SHOP> DŮLEŽITÉ Posílat jen produkty/varianty u kterých došlo ke změně PRICE_VAT, PRICE_COMMON_VAT a nebo DELIVERY. Pokud je v SHOPITEM nebo VARIANT uveden <DELETE>1</DELETE>, dojde ke smazání produktu respektivě varianty. Není umožněno přidávat nové produkty nebo varianty, ale pouze mazat nebo měnit existující CENOVÉ HLADINY Přihlášeným uživatelům může aplikace zobrazovat cenu, kterou jim určíte pomocí cenové hladiny. Každý produkt nebo varianta produktu kromě tagů: <PRICE_VAT>2299</PRICE_VAT> <PRICE_COMMON_VAT>3000</PRICE_COMMON_VAT> Může obsahovat: <PRICE_GROUP> <ID>A1</ID> // vlastní identifikátor cenové hladiny které posíláte s údaji o přihlášeném uživateli <PRICE>1000</PRICE> // cena bez DPH <VAT>0.21</VAT> // DPH <PRICE_VAT>1210</PRICE_VAT> cena s DPH <PRICE_COMMON>2000</PRICE_COMMON> // běžná cena před slevou bez DPH <PRICE_COMMON_VAT>1420</PRICE_COMMON_VAT> // běžná cena před slevou s DPH </PRICE_GROUP> 15
Příklad zakomponování cenových hladin v XML feedu naleznete zde: https://gist.github.com/pjancarik/918a1c69fe6a353bf6a1 16