Dokumentace XML - produkty
Základní pravidla
- XML produktů se používá pro import i export z Upgates.
- Zde je k náhledu prázdne vzorové XML.
- K testování struktury XML je možno použít naše XSD verze 1.0, verze 2.0.
- Tagy končící na
_YN>
jsou typu boolean a mohou nabývat hodnoty 0, 1, true, false. - Datum je zapsané jako řeťezec znaků ve formátu YYYY-MM-DD dle ISO 8601. Y je rok, M je měsíc a D je den. Příklad: 2020-12-30.
- Atributy
language
označující jazykovou mutaci používají kódy podle ISO 639-1 a jsou povinné.
Import
- Neuvádějte prázdné obalové tagy (např. tag
<IMAGES>
, pokud neobsahuje žádné obrázky). - V případě editace (při importu) se prázdný tag chápe jako vymazání původní hodnoty v databázi kromě všech typů cen, souvisejících produktů včetně dárků. Smazání cen v e-shopu nelze provést importem, je potřeba využít např. hromadné úpravy produktů.
- Produkty, varianty a kategorie se při importu párují podle kódu (tag
<CODE>
). Pokud chcete produkty a varianty importem aktualizovat, musí být tagy<CODE>
vyplněny, jinak se budou zakládat při každém importu nové produkty a varianty. - Všechny tagy jsou nepovinné, kromě kořenových tagů
<PRODUCTS>
a<PRODUCT>
. Při importu nových produktů (nebo při založení další jazykové mutace produktu) je povinný tag<TITLE>
(s celou nadřezenou strukturou), protože z názvu produktu se tvoří URL adresa. Tento název je potřeba zadat v aktivním jazyku e-shopu. Ve variantách jsou pak povinné parametry, opět pouze při importu nových variant. Pro aktualizaci existujících variant je potřeba zadat všechny jejich parametry nebo v nastavení importu zvolit, aby se parametry variant nezpracovávaly. Dále je všude povinný atributlanguage
. - U produktu je potřeba v XML uvést
<DESCRIPTION>
pro všechny jazykové mutace. Pokud některý z jazyků nebude uveden, systém produkt v této jazykové mutaci deaktivuje. Tomu se lze vyhnout uvedením tagu<ACTIVE_YN>
s hodnotou1
u všech jazykových mutací, pro které nezasíláte data. Ale produkt má zůstat v těchto jazycích aktivní. - Tagy, které mohou obsahovat HTML formátování je možno zapsat buď jako převedeno do HTML entit nebo pomocí CDATA (
<![CDATA[ ]]>
). - Číselné hodnoty se uvádí nezformátované bez znaku jednotky (např. ceny, hmotnost nebo DPH). Pro zápis desetinného místa můžete použít buď desetinnou tečku nebo čárku.
- Pokud má systém nově vytvořeným produktům automaticky přiřadit štítek novinka, pak je potřeba v nastavení importu povolit zpracování položky Štítky -> Novinka (do). To je potřeba provést i když tento štítek nenastavujete přes importní soubor.
- Další chování importu můžete ovlivnit nastavením v administraci (viz. nápověda).
Malý import
- V malém importu se zpracovávají pouze následující tagy (včetně všech vnořených):
<CODE>
<PRODUCT_ID>
<ACTIVE_YN>
<ARCHIVED_YN>
<REPLACEMENT_PRODUCT_CODE>
<CAN_ADD_TO_BASKET_YN>
<LABELS>
<AVAILABILITY>
<STOCK>
<PRICES>
<METAS>
- Ve variantách:
<CODE>
<MAIN_YN>
<ACTIVE_YN>
<CAN_ADD_TO_BASKET_YN>
<LABELS>
<AVAILABILITY>
<STOCK>
<PRICES>
Export
- Exportují se všechny tagy s výjimkou tagů s prázdnou hodnotou. Ty mohou v exportu chybět. U některých je uvedeno, že jsou pouze pro import nebo export.
- Export z jednoho e-shopu Upgates je možno použít pro import do jiného e-shopu Upgates.
Malý export
- Do malého exportu se dávají pouze následující tagy (včetně všech vnořených):
<CODE>
<PRODUCT_ID>
<ACTIVE_YN>
<ARCHIVED_YN>
<REPLACEMENT_PRODUCT_CODE>
<CAN_ADD_TO_BASKET_YN>
<AVAILABILITY>
<STOCK>
<PRICES>
- Ve variantách:
<CODE>
<MAIN_YN>
<ACTIVE_YN>
<CAN_ADD_TO_BASKET_YN>
<AVAILABILITY>
<STOCK>
<PRICES>
Struktura XML
<PRODUCTS>
version
- verze formátu XML 1.0<PRODUCT>
last_update_time
- datum poslední aktualizace produktu (pouze import) ve formátu Y-m-dTH:i:s (např. 2017-03-07T13:35:08). Pokud bude při importu toto datum starší než datum poslední aktualizace produktu v databázi, produkt se přeskočí.<CODE>
- kód produktu, páruje se podle existující hodnoty v databázi, nebo vytvoří nový produkt<PRODUCT_ID>
- interní ID produktu (pouze export)<ACTIVE_YN>
- zobrazit produkt na webu<ARCHIVED_YN>
- archivovaný produkt<REPLACEMENT_PRODUCT_CODE>
- kód náhradního produktu, pouze pokud je produkt archivovaný<CAN_ADD_TO_BASKET_YN>
- lze vložit do košíku<ADULT_YN>
- pouze pro dospělé<NEW_YN>
(pouze verze 1.0) - zobrazení příznaku Novinka<NEW_FROM>
(pouze verze 1.0) - datum, od kterého se zobrazí příznak Novinka<NEW_TO>
(pouze verze 1.0) - datum, do kterého je zobrazen příznak Novinka<SPECIAL_YN>
(pouze verze 1.0) - zobrazení příznaku Akce<SPECIAL_FROM>
(pouze verze 1.0) - datum, od kterého se zobrazí příznak Akce<SPECIAL_TO>
(pouze verze 1.0) - datum, do kterého je zobrazen příznak Akce<SELLOUT_YN>
(pouze verze 1.0) - zobrazení příznaku Výprodej<SELLOUT_FROM>
(pouze verze 1.0) - datum, od kterého se zobrazí příznak Výprodej<SELLOUT_TO>
(pouze verze 1.0) - datum, do kterého je zobrazen příznak Výprodej<LABELS>
- štítky<LABEL>
<NAME>
- název štítku, páruje se podle existující hodnoty v databázi, nebo vytvoří novou<ACTIVE_YN>
- aktivní<ACTIVE_FROM>
- datum, od kterého bude štítek aktivní<ACTIVE_TO>
- datum, do kterého bude štítek aktivní
<DESCRIPTIONS>
- texty<DESCRIPTION>
language
- specifikace jazykové mutace<ACTIVE_YN>
- aktivní v jazykové mutaci, pokud se neuvede tak se bere jako aktivní. Použitelné pouze pro deaktivaci jazykové mutace (skrytí produktu v jazykove mutaci)<URL>
- URL produktu<TITLE>
- název (POVINNÝ v případě vytváření nového produktu). Pokud není definovaný, nezaloží se ani jazyková mutace produktu (související data se přeskočí)<SHORT_DESCRIPTION>
- krátký popis, bez HTML formátování<LONG_DESCRIPTION>
- dlouhý popis, může obsahovat formátování pouze pomocí HTML značek
<SEO_OPTIMALIZATION>
- SEO<SEO>
language
- specifikace jazykové mutace<SEO_URL>
- vlastní koncovka URL adresy<SEO_TITLE>
- SEO titulek produktu<SEO_META_DESCRIPTION>
- META popisek stránky produktu
<MANUFACTURER>
- název výrobce, páruje se podle existující hodnoty v databázi, nebo vytvoří novou<MANUFACTURER_IMAGE_URL>
- URL na obrázek výrobce (pouze import)<MANUFACTURER_DESCRIPTIONS>
- popisy výrobce (pouze import)<DESCRIPTION>
language
- specifikace jazykové mutace
<SUPPLIER_CODE>
- kód dodavatele<EAN>
- čárkový kód<AVAILABILITY>
- název dostupnosti, páruje se podle existující hodnoty v databázi, nebo vytvoří novou. Neimportuje se u položek s nastavením dostupnosti dle stavu zásob. Pokud však v tomto případě stav zásob není definován (tag<STOCK>
musí být prázdný nebo úplně chybět), dostupnost se importuje<STOCK>
- počet jednotek na skladě<STOCK_POSITION>
- pozice na skladě<LIMIT_ORDERS>
- Omezení objednání- 1 - Omezení je zapnuté
- 0 - Omezení je vypnuté
- sale - Když je produkt ve výprodeji
- *Pokud je pole prázdné dědí hodnotu z nastavení e-shopu
<WEIGHT>
- hmotnost v gramech<UNIT>
- název měrné jednotky, páruje se podle stejné hodnoty, nebo založí novou<SHIPMENT_GROUP>
- skupina doprav, páruje se podle stejné hodnoty, nebo založí novou<VATS>
- DPH<VAT>
- páruje se podle existující hodnoty v databázi, nebo vytvoří novou. Pokud není vyplněno bere se výchozí DPH pro daný jazyklanguage
- specifikace jazykové mutace
<LENGTH>
- množtví<ACTIVE_YN>
- aktivní<LABELS>
- popisky<LABEL>
language
- specifikace jazykové mutace
<LENGTH_FROM>
- minimální množství<LENGTH_TO>
- maximální množství<UNIT>
- název měrné jednotky, páruje se podle stejné hodnoty, nebo založí novou<STEPS_TYPE>
- typ krokování metráže, možné hodnoty:- neither - žádné krokování, výchozí
- multiples - násobky
- select - výběr z možností
<STEPS>
- hodnota podle typu krokování:- neither - může být prázdné
- multiples - hodnota násobku
- select - každá hodnota na nový řádek
<NOTE>
- poznámka
<PRIVATE_YN>
- zobrazit produkt pouze přihlášeným uživatelům<PRIVATE_CUSTOMERS_ONLY_YN>
- zobrazit pouze uživatelům, kteří mohou vidět skryté stránky<EXCLUDE_FROM_SEARCH_YN>
- vyřazeno z vyhledávání (pouze export verze 2.0)<GROUPS>
- skupiny zákazníků<GROUP>
- název skupiny
<CATEGORIES>
- kategorie<CATEGORY>
<CODE>
- kód kategorie, do které bude produkt zařazen. V případě, že se vyskytne více stejných kódů kategorie v jednom produktu, zpracuje se první v pořadí. Páruje se podle existujícího kódu kategorie<NAME>
- název kategorie, do které je produkt zařazen (export)<PRIMARY_YN>
- informace, zda je kategorie primární. V případě, že se vyskytne více primárních kategorií v jednom produktu, bere se první v pořadí<POSITION>
- pozice produktu v kategorii
<PRICES_FORMULAS>
- cenové vzorce<NAME>
- název vzorce, páruje se podle existující hodnoty v databázi, vzorec musí být vytvořen
<RECYCLING_FEE>
(pouze verze 2.0) - recyklační poplatek<NAME>
- interní název, páruje se podle existující hodnoty v databázi<VALUE>
- hodnota poplatku pro jazykovou mutacilanguage
- specifikace jazykové mutace
<PRICES>
- ceny<PRICE>
language
- specifikace jazykové mutace<PRICELISTS>
- ceníky<PRICELIST>
<NAME>
- název ceníku, pokud je při importu prázdné, chápe se jako výchozí ceník<PRICE_ORIGINAL>
- základní ceníková cena, od které se odvozují další (cena před slevou) (neexportuje se do odběratelského feedu)<PRODUCT_DISCOUNT>
- sleva na produkt v procentech (neexportuje se do odběratelského feedu)<PRODUCT_DISCOUNT_REAL>
- reálná sleva na produkt použitá pro výpočet výsledné ceny (pouze export, neexportuje se do odběratelského feedu), vypočítává se takto:- hodnota slevy na produkt (
<PRODUCT_DISCOUNT>
) + sleva na výrobce + sleva na kategorii (bere se sleva z hlavní kategorie ve které je produkt zařazen). Výsledná hodnota slevy se omezí na hodnotu z nastavení Maximální procento slevy.
- hodnota slevy na produkt (
<PRICE_SALE>
- akční cena, exportuje se pouze tehdy, pokud je produkt v akci (štítek akce) (neexportuje se do odběratelského feedu)<PRICE_WITH_VAT>
- výsledná cena po slevách s DPH (pouze export, exportuje se pouze do odběratelského feedu)<PRICE_WITHOUT_VAT>
- výsledná cena po slevách bez DPH (pouze export, exportuje se pouze do odběratelského feedu)
<PRICE_PURCHASE>
- nákupní cena, interní údaj pro orientaci administrátora (neexportuje se do odběratelského feedu)<PRICE_COMMON>
- běžná cena, pro orientaci při nákupu. Může to být např. cena v kamenných obchodech (neexportuje se do odběratelského feedu)<CURRENCY>
- měna (pouze export)
<IMAGES>
- obrázky<IMAGE>
<URL>
- URL adresa obrázku<TITLES>
- popisky obrázku<TITLE>
language
- specifikace jazykové mutace
<MAIN_YN>
- obrázek je hlavní, v případě, že se vyskytne více hlavních obrázků v jednom produktu, zpracovává se první v pořadí<LIST_YN>
- obrázek je seznamový, v případě, že se vyskytne více seznamových obrázků v jednom produktu, zpracovává se první v pořadí
<FILES>
- soubory<FILE>
<URL>
- URL adresa souboru<TITLES>
- popisky souboru<TITLE>
language
- specifikace jazykové mutace
<BENEFITS>
- benefity<BENEFIT>
<NAME>
- název benefitu, páruje se podle existující hodnoty v databázi (v hlavním jazyku), nebo vytvoří novou
<PARAMETERS>
- parametry<PARAMETER>
<NAME>
- název parametru, páruje se podle existující hodnoty v databázi, nebo vytvoří novoulanguage
(pouze verze 2.0) - specifikace jazykové mutace
<VALUE>
- hodnota parametru, v případě, že se vyskytne více stejných hodnot parametru v jednom produktu, zpracovává se první v pořadí. Páruje se podle existující hodnoty v databázi, nebo vytvoří novoulanguage
(pouze verze 2.0) - specifikace jazykové mutace
<IMAGE_URL>
- URL obrázku. V případě že bude uveden, nastaví se parametr jako obrázkový
<CONFIGURATIONS>
- konfigurace<CONFIGURATION>
type
- typ konfigurace:- one_value - možno vybrat pouze jednu hodnotu (select)
- more_values - možno vybrat více hodnot (checkboxy)
- group - skupina konfigurací, v tagu
<NAME>
musí být název skupiny který je uveden v administraci. Pokud je typ konfigurace group neuvádí se hodnota<VALUE>
- text - jako hodnota je použito textové pole (textarea), nemá hodnotu
<VALUE>
- separator - oddělovač, nemá hodnotu
<VALUE>
<NAME>
- název parametru konfigurace, páruje se podle existující hodnoty v databázi, nebo vytvoří novou (neplatí pokud je typ konfigurace group)language
(pouze verze 2.0) - specifikace jazykové mutace
<VALUE>
- hodnota parametru konfigurace, páruje se podle existující hodnoty v databázi, nebo vytvoří novou (může být uvedeno vícekrát)<NAME>
- název hodnotylanguage
(pouze verze 2.0) - specifikace jazykové mutace
<IMAGE_URL>
- URL obrázku. V případě, že bude uveden, nastaví se parametr jako obrázkový<DEFAULT_YN>
- výchozí hodnota parametru konfigurace<PRICE>
- cena (nepovinné)language
- specifikace jazykové mutaceoperation
- operace, která se provede s cenou poduktu při vybrání hodnoty. Povolené hodnoty jsou:- + sčítání (výchozí)
- - odčítání
- * násobení
- / dělení
<VARIANTS>
- varianty<VARIANT
<CODE>
- kód varianty, páruje se podle existující hodnoty v databázi, nebo vytvoří novou<VARIANT_ID>
- interní ID varianty (pouze export)<MAIN_YN>
- hlavní varianta. V případě, že se vyskytne více hlavních variant v jednom produktu, bere se první v pořadí<ACTIVE_YN>
- zobrazit variantu na webu<CAN_ADD_TO_BASKET_YN>
- lze vložit do košíku<SUPPLIER_CODE>
- kód dodavatele<EAN>
- čárkový kód<NEW_YN>
(pouze verze 1.0) - zobrazení příznaku Novinka<NEW_FROM>
(pouze verze 1.0) - datum, od kterého se zobrazí příznak Novinka<NEW_TO>
(pouze verze 1.0) - datum, do kterého je zobrazen příznak Novinka<SPECIAL_YN>
(pouze verze 1.0) - zobrazení příznaku Akce<SPECIAL_FROM>
(pouze verze 1.0) - datum, od kterého se zobrazí příznak Akce<SPECIAL_TO>
(pouze verze 1.0) - datum, do kterého je zobrazen příznak Akce<SELLOUT_YN>
(pouze verze 1.0) - zobrazení příznaku Výprodej<SELLOUT_FROM>
(pouze verze 1.0) - datum, od kterého se zobrazí příznak Výprodej<SELLOUT_TO>
(pouze verze 1.0) - datum, do kterého je zobrazen příznak Výprodej<LABELS>
- štítky variant<LABEL>
<NAME>
- název štítku. Páruje se podle existující hodnoty v databázi, nebo vytvoří novou.<ACTIVE_YN>
- aktivní<ACTIVE_FROM>
- datum od kterého bude štítek aktivní<ACTIVE_TO>
- datum do kterého bude štítek aktivní
<AVAILABILITY_NOTES>
- poznámky k dostupnosti<AVAILABILITY_NOTE>
language
- specifikace jazykové mutace
<AVAILABILITY>
- název dostupnosti, páruje se podle existující hodnoty v databázi, nebo vytvoří novou. Neimportuje se u položek s nastavením dostupnosti dle stavu zásob. Pokud však v tomto případě stav zásob není definován (tag<STOCK>
musí být prázdný nebo úplně chybět), dostupnost se importuje<STOCK>
- počet jednotek na skladě<STOCK_POSITION>
- pozice na skladě<WEIGHT>
- hmotnost v gramech (pro výběr dopravy)<IMAGE_URL>
- URL adresa obrázku<PARAMETERS>
- parametry variant<PARAMETER>
<NAME>
- název parametru. V případě, že se vyskytne více stejných názvů parametru v jednom produktu, bere se první v pořadí. Páruje se podle existující hodnoty v databázi, nebo vytvoří novoulanguage
(pouze verze 2.0) - specifikace jazykové mutace
<VALUE>
- hodnota parametru. V případě, že se vyskytne více stejných hodnot parametru v jednom produktu, zpracovává se první v pořadí. Páruje se podle existující hodnoty v databázi, nebo vytvoří novoulanguage
(pouze verze 2.0) - specifikace jazykové mutace
<IMAGE_URL>
- URL obrázku. V případě, že bude uveden, nastaví se parametr jako obrázkový
<PRICES>
- ceny<PRICE>
language
- specifikace jazykové mutace<PRICELISTS>
- ceníky<PRICELIST>
<NAME>
- název ceníku. Pokud je při importu prázdné, chápe se jako výchozí ceník<PRICE_ORIGINAL>
- základní ceníková cena, od které se odvozují další (cena před slevou) (neexportuje se do odběratelského feedu)<PRODUCT_DISCOUNT>
- sleva na variantu v procentech (neexportuje se do odběratelského feedu)<PRODUCT_DISCOUNT_REAL>
- reálná sleva na variantu použitá pro výpočet výsledné ceny (pouze export, neexportuje se do odběratelského feedu), vypočítává se takto:- hodnota slevy na variantu (
<PRODUCT_DISCOUNT>
) + sleva na výrobce + sleva na kategorii (bere se sleva z hlavní kategorie ve které je produkt zařazen). Výsledná hodnota slevy se omezí na hodnotu z nastavení Maximální procento slevy.
- hodnota slevy na variantu (
<PRICE_SALE>
- akční cena. Exportuje se pouze tehdy, pokud je varianta v akci (štítek akce) (neexportuje se do odběratelského feedu)<PRICE_WITH_VAT>
- výsledná cena po slevách s DPH (pouze export, exportuje se pouze do odběratelského feedu)<PRICE_WITHOUT_VAT>
- výsledná cena po slevách bez DPH (pouze export, exportuje se pouze do odběratelského feedu)
<PRICE_PURCHASE>
- nákupní cena, interní údaj pro orientaci administrátora (neexportuje se do odběratelského feedu)<PRICE_COMMON>
- běžná cena, pro orientaci při nákupu. Může to být např. cena v kamenných obchodech (neexportuje se do odběratelského feedu)<CURRENCY>
- měna (pouze export)
<METAS>
- vlastní pole variant<META>
type
- typ vlastního pole, možné hodnoty:- radio - přepínač
- checkbox - zaškrtávací políčko
- input - textové pole
- date - datum
- email - email
- number - číslo
- select - rozbalovací nabídka
- multiselect - multi rozbalovací nabídka
- textarea - víceřádkové textové pole
- formatted - víceřádkové textové pole formátované (WYSIWYG)
<META_KEY>
- Klíč vlastního pole - povolené znaky jsou malá písmena, čísla (nesmí být na první pozici) a podtržítko<META_VALUE>
- hodnota vlastního pole. Uvádí se, pokud je stejná pro všechny jazykové mutace<META_VALUES>
- hodnoty vlastního pole pro jednotlivé jazykové mutace<META_VALUE>
language
- specifikace jazykové mutace
<RELATED_PRODUCTS>
- související produkty<CODE>
- kód souvisejícího produktu, páruje se podle existující hodnoty v databázi
<ALTERNATIVE_PRODUCTS>
- alternativní produkty<CODE>
- kód alternativního produktu, páruje se podle existující hodnoty v databázi
<ACCESSORIES>
- příslušenství<CODE>
- kód produktu příslušenství, páruje se podle existující hodnoty v databázi
<GIFTS>
- dárky<CODE>
- kód varianty nebo produktu dárku, páruje se podle existující hodnoty v databázi. Pokud je vyplněna vymyšlená hodnota, dárky se od daného produktu promažou.type
- typ varianty- highest_stock_variant - varianta s nejvyšším skladem (při importu, pokud atribut chybí je toto výchozí hodnota)
- random_stock_variant - náhodná varianta
- variant - vybraná varianta
<SETS>
- sada<CODE>
- kód varianty nebo produktu, páruje se podle existující hodnoty v databáziquantity
- počet jednotek produktu v sadě (při importu. Pokud atribut chybí, je výchozí hodnota 1)
<METAS>
- vlastní pole<META
type
- typ vlastního pole, možné hodnoty:- radio - přepínač
- checkbox - zaškrtávací políčko
- input - textové pole
- date - datum
- email - email
- number - číslo
- select - rozbalovací nabídka
- multiselect - multi rozbalovací nabídka
- textarea - víceřádkové textové pole
- formatted - víceřádkové textové pole formátované (WYSIWYG)
<META_KEY>
- klíč vlastního pole - povolené znaky jsou malá písmena, čísla (nesmí být na první pozici) a podtržítko<META_VALUE>
- hodnota vlastního pole. Uvádí se, pokud je stejná pro všechny jazykové mutace<META_VALUES>
- hodnoty vlastního pole pro jednotlivé jazykové mutace<META_VALUE>
language
- specifikace jazykové mutace