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ý atribut language.
• 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 hodnotou 1 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 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ý jazyk
        • language - 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 mutaci
        • language - 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 (pouze export, 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.
            • <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ří novou
          • language (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ří novou
          • language (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 hodnoty
            • language (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é mutace
            • operation - 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ří novou
              • language (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ří novou
              • language (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 (pouze export, 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.
                • <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ázi
        • quantity - 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