Dokumentácia XML - produkty

Základné pravidlá

• XML produktov sa používa pre import aj export z Upgates.
• Tu je k náhľadu prázdne vzorové XML.
• Na testovanie štruktúry XML je možné použiť naše XSD verzia 1.0, verzia 2.0.
• Tagy končiace na _YN> sú typu boolean a môžu nadobúdať hodnoty 0, 1, true, false.
• Dátum je zapísaný ako reťazec znakov vo formáte YYYY-MM-DD podľa ISO 8601. Y je rok, M je mesiac a D je deň. Príklad: 2020-12-30.
• Atribúty language označujúce jazykovú mutáciu používajú kódy podľa ISO 639-1 a sú povinné.

Import

• Neuvádzajte prázdne obalové tagy (napr. tag <IMAGES>, pokiaľ neobsahuje žiadne obrázky).
• V prípade editácie (pri importe) sa prázdny tag chápe ako vymazanie pôvodnej hodnoty v databáze.
• Produkty, varianty a kategórie sa pri importe párujú podľa kódu (tag <CODE>). Pokiaľ chcete produkty a varianty importom aktualizovať, musia byť tagy <CODE> vyplnené, inak sa budú zakladať pri každom importe nové produkty a varianty.
• Všetky tagy sú nepovinné, okrem koreňových tagov <PRODUCTS> a <PRODUCT>. Pri importe nových produktov (alebo pri založení ďalšej jazykovej mutácie produktu) je povinný tag <TITLE> (s celou nadradenou štruktúrou), pretože z názvu produktu sa tvorí URL adresa. Tento názov je potrebné zadať v aktívnom jazyku e-shopu. Vo variantoch sú potom povinné parametre, opäť len pri importe nových variantov. Pre aktualizáciu existujúcich variantov je potrebné zadať všetky ich parametre alebo v nastavení importu zvoliť, aby sa parametre variantov nespracovávali. Ďalej je všade povinný atribút language.
• Pri produktoch je potrebné v XML uviesť <DESCRIPTION> pre všetky jazykové mutácie. Pokiaľ niektorý z jazykov nebude uvedený, systém produkt v tejto jazykovej mutácii deaktivuje. Tomu sa je možné vyhnúť uvedením tagu <ACTIVE_YN> s hodnotou 1 pri všetkých jazykových mutáciách pre ktoré nezasielate údaje. Ale produkt má zostať v týchto jazykoch aktívny.
• Tagy, ktoré môžu obsahovať HTML formátovanie je možné zapísať buď ako prevedené do HTML entity alebo pomocou CDATA (<![CDATA[ ]]>).
• Číselné hodnoty sa uvádzajú nenaformátované bez znaku jednotky (napr. ceny, hmotnosť alebo DPH). Pre zápis môžete použiť buď desatinnú bodku alebo čiarku.
• Pokiaľ má systém novo vytvoreným produktom automaticky priradiť štítok novinka, potom je potrebné v nastavení importu povoliť spracovanie položky Štítky -> Novinka (do). To je potrebné vykonať aj keď tento štítok nenastavujete cez importný súbor.
• Ďalšie správanie importu môžete ovplyvniť nastavením v administrácii (viď nápoveda).

Malý import

• V malom importe sa spracovávajú len nasledujúce tagy (vrátane všetkých vnorených):
• <CODE>
• <PRODUCT_ID>
• <ACTIVE_YN>
• <ARCHIVED_YN>
• <REPLACEMENT_PRODUCT_CODE>
• <CAN_ADD_TO_BASKET_YN>
• <LABELS>
• <AVAILABILITY>
• <STOCK>
• <PRICES>
• <METAS>
• Vo variantoch:
• <CODE>
• <MAIN_YN>
• <ACTIVE_YN>
• <CAN_ADD_TO_BASKET_YN>
• <LABELS>
• <AVAILABILITY>
• <STOCK>
• <PRICES>

Export

• Exportujú sa všetky tagy s výnimkou tagov s prázdnou hodnotou. Tie môžu v exporte chýbať. Pri niektorých je uvedené, že sú len pre import alebo export.
• Export z jedného e-shopu Upgates je možné použiť pre import do iného e-shopu Upgates.

Malý export

• Do malého exportu sa dávajú len nasledujúce tagy (vrátane všetkých vnorených):
• <CODE>
• <PRODUCT_ID>
• <ACTIVE_YN>
• <ARCHIVED_YN>
• <REPLACEMENT_PRODUCT_CODE>
• <CAN_ADD_TO_BASKET_YN>
• <AVAILABILITY>
• <STOCK>
• <PRICES>
• Vo variantoch:
• <CODE>
• <MAIN_YN>
• <ACTIVE_YN>
• <CAN_ADD_TO_BASKET_YN>
• <AVAILABILITY>
• <STOCK>
• <PRICES>

Štruktúra XML

• <PRODUCTS>
• version - verzia formátu XML 1.0
• <PRODUCT>
• last_update_time - dátum poslednej aktualizácie produktu (len import) vo formáte Y-m-dTH:i:s (napr. 2017-03-07T13:35:08). Pokiaľ bude pri importe tento dátum starší ako dátum poslednej aktualizácie produktu v databáze, produkt sa preskočí.
• <CODE> - kód produktu, páruje sa podľa existujúcej hodnoty v databáze, alebo vytvorí nový produkt
• <PRODUCT_ID> - interné ID produktu (len export)
• <ACTIVE_YN> - zobraziť produkt na webe
• <ARCHIVED_YN> - archivovaný produkt
• <REPLACEMENT_PRODUCT_CODE> - kód náhradného produktu, len pokiaľ je produkt archivovaný
• <CAN_ADD_TO_BASKET_YN> - je možné vložiť do košíka
• <ADULT_YN> - len pre dospelých
• <NEW_YN> (len verzia 1.0) - zobrazenie príznaku Novinka
• <NEW_FROM> (len verzia 1.0) - dátum, od ktorého sa zobrazí príznak Novinka
• <NEW_TO> (len verzia 1.0) - dátum, do ktorého je zobrazený príznak Novinka
• <SPECIAL_YN> (len verzia 1.0) - zobrazenie príznaku Akcia
• <SPECIAL_FROM> (len verzia 1.0) - dátum, od ktorého sa zobrazí príznak Akcia
• <SPECIAL_TO> (len verzia 1.0) - dátum, do ktorého je zobrazený príznak Akcia
• <SELLOUT_YN> (len verzia 1.0) - zobrazenie príznaku Výpredaj
• <SELLOUT_FROM> (len verzia 1.0) - dátum, od ktorého sa zobrazí príznak Výpredaj
• <SELLOUT_TO> (len verzia 1.0) - dátum, do ktorého je zobrazený príznak Výpredaj
• <LABELS> - štítky
• <LABEL>
• <NAME> - názov štítku, páruje sa podľa existujúcej hodnoty v databáze, alebo vytvorí novú
• <ACTIVE_YN> - aktívny
• <ACTIVE_FROM> - dátum, od ktorého bude štítok aktívny
• <ACTIVE_TO> - dátum, do ktorého bude štítok aktívny
• <DESCRIPTIONS> - texty
• <DESCRIPTION>
• language - špecifikácie jazykovej mutácie
• <ACTIVE_YN> - aktívny v jazykovej mutácii, pokiaľ sa neuvedie tak sa berie ako aktívny. Použiteľné len pre deaktiváciu jazykovej mutácie (skrytie produktu v jazykovej mutácii)
• <URL> - URL produktu
• <TITLE> - názov (POVINNÝ v prípade vytvárania nového produktu). Pokiaľ nie je definovaný, nezaloží sa ani jazyková mutácia produktu (súvisiace údaje sa preskočia)
• <SHORT_DESCRIPTION> - krátky popis, bez HTML formátovania
• <LONG_DESCRIPTION> - dlhý popis, môže obsahovať formátovanie len pomocou HTML značiek
• <SEO_OPTIMALIZATION> - SEO
• <SEO>
• language - špecifikácie jazykovej mutácie
• <SEO_URL> - vlastná koncovka URL adresy
• <SEO_TITLE> - SEO titulok produktu
• <SEO_META_DESCRIPTION> - META popisok stránky produktu
• <MANUFACTURER> - názov výrobcu, páruje sa podľa existujúcej hodnoty v databáze, alebo vytvorí novú
• <MANUFACTURER_IMAGE_URL> - URL na obrázok výrobcu (len import)
• <MANUFACTURER_DESCRIPTIONS> - popisy výrobcu (len import)
• <DESCRIPTION>
• language - špecifikácie jazykovej mutácie
• <SUPPLIER_CODE> - kód dodávateľa
• <EAN> - čiarový kód
• <AVAILABILITY> - názov dostupnosti, páruje sa podľa existujúcej hodnoty v databáze, alebo vytvorí novú. Neimportuje sa pri položkách s nastavením dostupnosti podľa stavu zásob. Pokiaľ však v tomto prípade stav zásob nie je definovaný (tag <STOCK> musí byť prázdny alebo úplne chýbať), dostupnosť sa importuje
• <STOCK> - počet jednotiek na sklade
• <STOCK_POSITION> - pozícia na sklade
• <WEIGHT> - hmotnosť v gramoch
• <UNIT> - názov mernej jednotky, páruje sa podľa rovnakej hodnoty, alebo založí novú
• <SHIPMENT_GROUP> - skupina dopravy, páruje sa podľa rovnakej hodnoty, alebo založí novú
• <VATS> - DPH
• <VAT> - páruje sa podľa existujúcej hodnoty v databáze, alebo vytvorí novú. Pokiaľ nie je vyplnená berie sa východisková DPH pre daný jazyk
• language - špecifikácie jazykovej mutácie
• <LENGTH> - množstvo
• <ACTIVE_YN> - aktívne
• <LABELS> - popisky
• <LABEL>
• language - špecifikácie jazykovej mutácie
• <LENGTH_FROM> - minimálne množstvo
• <LENGTH_TO> - maximálne množstvo
• <UNIT> - názov mernej jednotky, páruje sa podľa rovnakej hodnoty, alebo založí novú
• <STEPS_TYPE> - typ krokovania metráže, možné hodnoty:
• neither - žiadne krokovanie, východiskové
• multiples - násobky
• select - výber z možností
• <STEPS> - hodnota podľa typu krokovania:
• neither - môže byť prázdne
• multiples - hodnota násobku
• select - každá hodnota na nový riadok
• <NOTE> - poznámka
• <PRIVATE_YN> - zobraziť produkt len prihláseným užívateľom
• <PRIVATE_CUSTOMERS_ONLY_YN> - zobraziť len užívateľom, ktorí môžu vidieť skryté stránky
• <GROUPS> - skupiny zákazníkov
• <GROUP> - názov skupiny
• <CATEGORIES> - kategória
• <CATEGORY>
• <CODE> - kód kategórie, do ktorej bude produkt zaradený. V prípade, že sa vyskytne viacero rovnakých kódov kategórie v jednom produkte, spracuje sa prvý v poradí. Páruje sa podľa existujúceho kódu kategórie
• <NAME> - názov kategórie, do ktorej je produkt zaradený (export)
• <PRIMARY_YN> - informácie, či je kategória primárna. V prípade, že sa vyskytne viacero primárnych kategórií v jednom produkte, berie sa prvá v poradí
• <POSITION> - pozícia produktu v kategórii
• <PRICES_FORMULAS> - cenové vzorce
• <NAME> - názov vzorca, páruje sa podľa existujúcej hodnoty v databáze, vzorec musí byť vytvorený
• <RECYCLING_FEE> (len verzia 2.0) - recyklačný poplatok
• <NAME> - interný názov, páruje sa podľa existujúcej hodnoty v databáze
• <VALUE> - hodnota poplatku pre jazykovú mutáciu
• language - špecifikácie jazykovej mutácie
• <PRICES> - ceny
• <PRICE>
• language - špecifikácie jazykovej mutácie
• <PRICELISTS> - cenníky
• <PRICELIST>
• <NAME> - názov cenníka, pokiaľ je pri importe prázdny, chápe sa ako východiskový cenník
• <PRICE_ORIGINAL> - základná cenníková cena, od ktorej sa odvodzujú ďalšie (cena pred zľavou) (neexportuje sa do odberateľského feedu)
• <PRODUCT_DISCOUNT> - zľava na produkt v percentách (neexportuje sa do odberateľského feedu)
• <PRODUCT_DISCOUNT_REAL> - reálna zľava na produkt použitá pre výpočet výslednej ceny (len export, neexportuje sa do odberateľského feedu), vypočítava sa takto:
• hodnota zľavy na produkt (<PRODUCT_DISCOUNT>) + zľava na výrobcu + zľava na kategóriu (berie sa zľava z hlavnej kategórie, v ktorej je produkt zaradený). Výsledná hodnota zľavy sa obmedzí na hodnotu z nastavenia Maximálne percento zľavy.
• <PRICE_SALE> - akčná cena, exportuje sa len vtedy, pokiaľ je produkt v akcii (štítok akcie) (neexportuje sa do odberateľského feedu)
• <PRICE_WITH_VAT> - výsledná cena po zľavách s DPH (len export, exportuje sa len do odberateľského feedu)
• <PRICE_WITHOUT_VAT> - výsledná cena po zľavách bez DPH (len export, exportuje sa len do odberateľského feedu)
• <PRICE_PURCHASE> - nákupná cena, interný údaj pre orientáciu administrátora (neexportuje sa do odberateľského feedu)
• <PRICE_COMMON> - bežná cena, pre orientáciu pri nákupe, môže to byť napr. cena v kamenných obchodoch (neexportuje sa do odberateľského feedu)
• <CURRENCY> - mena (len export)
• <IMAGES> - obrázky
• <IMAGE>
• <URL> - URL adresa obrázka
• <TITLES> - popisky obrázka
• <TITLE>
• language - špecifikácie jazykovej mutácie
• <MAIN_YN> - obrázok je hlavný, v prípade, že sa vyskytne viac hlavných obrázkov v jednom produkte, spracováva sa prvý v poradí
• <LIST_YN> - obrázok je zoznamový, v prípade, že sa vyskytne viac zoznamových obrázkov v jednom produkte, spracováva sa prvý v poradí
• <FILES> - súbory
• <FILE>
• <URL> - URL adresa súboru
• <TITLES> - popisky súboru
• <TITLE>
• language - špecifikácie jazykovej mutácie
• <BENEFITS> - benefity
• <BENEFIT>
• <NAME> - názov benefitu, páruje sa podľa existujúcej hodnoty v databáze (v hlavnom jazyku), alebo vytvorí novú
• <PARAMETERS> - parametre
• <PARAMETER>
• <NAME> - názov parametra, páruje sa podľa existujúcej hodnoty v databáze, alebo vytvorí novú
• language (len verzia 2.0) - špecifikácie jazykovej mutácie
• <VALUE> - hodnota parametra, v prípade, že sa vyskytne viac rovnakých hodnôt parametra v jednom produkte, spracováva sa prvý v poradí. Páruje sa podľa existujúcej hodnoty v databáze, alebo vytvorí novú
• language (len verzia 2.0) - špecifikácia jazykovej mutácie
• <IMAGE_URL> - URL obrázka, v prípade že bude uvedený, nastaví sa parameter ako obrázkový
• <CONFIGURATIONS> - konfigurácia
• <CONFIGURATION>
• type - typ konfigurácie:
• one_value - možné vybrať len jednu hodnotu (select)
• more_values - možné vybrať viac hodnôt (checkboxy)
• group - skupina konfigurácií, v tagu <NAME> musí byť názov skupiny, ktorý je uvedený v administrácii. Pokiaľ je typ konfigurácie group neuvádza sa hodnota <VALUE>
• text - ako hodnota je použité textové pole (textarea), nemá hodnotu <VALUE>
• separator - oddeľovač, nemá hodnotu <VALUE>
• <NAME> - názov parametra konfigurácie, páruje sa podľa existujúcej hodnoty v databáze, alebo vytvorí novú (neplatí pokiaľ je typ konfigurácie group)
• language (len verzia 2.0) - špecifikácie jazykovej mutácie
• <VALUE> - hodnota parametra konfigurácie, páruje sa podľa existujúcej hodnoty v databáze, alebo vytvorí novú (môže byť uvedené viackrát)
• <NAME> - názov hodnoty
• language (len verzia 2.0) - špecifikácie jazykovej mutácie
• <IMAGE_URL> - URL obrázka, v prípade že bude uvedená, nastaví sa parameter ako obrázkový
• <DEFAULT_YN> - východisková hodnota parametra konfigurácie
• <PRICE> - cena (nepovinné)
• language - špecifikácie jazykovej mutácie
• operation - operácia, ktorá sa vykoná s cenou produktu pri vybraní hodnoty, povolené hodnoty sú:
• + sčítanie (východiskové)
• - odčítanie
• * násobenie
• / delenie
• <VARIANTS> - varianty
• <VARIANT
• <CODE> - kód variantu, páruje sa podľa existujúcej hodnoty v databáze, alebo vytvorí novú
• <VARIANT_ID> - interné ID variantu (len export)
• <MAIN_YN> - hlavný variant. V prípade, že sa vyskytne viac hlavných variantov v jednom produkte, berie sa prvý v poradí
• <ACTIVE_YN> - zobraziť variant na webe
• <CAN_ADD_TO_BASKET_YN> - je možné vložiť do košíka
• <SUPPLIER_CODE> - kód dodávateľa
• <EAN> - čiarový kód
• <NEW_YN> (len verzia 1.0) - zobrazenie príznaku Novinka
• <NEW_FROM> (len verzia 1.0) - dátum, od ktorého sa zobrazí príznak Novinka
• <NEW_TO> (len verzia 1.0) - dátum, do ktorého je zobrazený príznak Novinka
• <SPECIAL_YN> (len verzia 1.0) - zobrazenie príznaku Akcia
• <SPECIAL_FROM> (len verzia 1.0) - dátum, od ktorého sa zobrazí príznak Akcia
• <SPECIAL_TO> (len verzia 1.0) - dátum, do ktorého je zobrazený príznak Akcia
• <SELLOUT_YN> (len verzia 1.0) - zobrazenie príznaku Výpredaj
• <SELLOUT_FROM> (len verzia 1.0) - dátum, od ktorého sa zobrazí príznak Výpredaj
• <SELLOUT_TO> (len verzia 1.0) - dátum, do ktorého je zobrazený príznak Výpredaj
• <LABELS> - štítky variantov
• <LABEL>
• <NAME> - názov štítka. Páruje sa podľa existujúce hodnoty v databáze, alebo vytvorí novú.
• <ACTIVE_YN> - aktívne
• <ACTIVE_FROM> - dátum, od ktorého bude štítok aktívny
• <ACTIVE_TO> - dátum, do ktorého bude štítok aktívny
• <AVAILABILITY_NOTES> - poznámky k dostupnosti
• <AVAILABILITY_NOTE>
• language - špecifikácie jazykovej mutácie
• <AVAILABILITY> - názov dostupnosti, páruje sa podľa existujúcej hodnoty v databáze, alebo vytvorí novú. Neimportuje sa pri položkách s nastavením dostupnosti podľa stavu zásob. Pokiaľ však v tomto prípade stav zásob nie je definovaný (tag <STOCK> musí byť prázdny alebo úplne chýbať), dostupnosť sa importuje
• <STOCK> - počet jednotiek na sklade
• <STOCK_POSITION> - pozícia na sklade
• <WEIGHT> - hmotnosť v gramoch (pre výber dopravy)
• <IMAGE_URL> - URL adresa obrázka
• <PARAMETERS> - parametre variantov
• <PARAMETER>
• <NAME> - názov parametra. V prípade, že sa vyskytne viac rovnakých názvov parametra v jednom produkte, berie sa prvý v poradí. Páruje sa podľa existujúcej hodnoty v databáze, alebo vytvorí novú
• language (len verzia 2.0) - špecifikácie jazykovej mutácie
• <VALUE> - hodnota parametra. V prípade, že sa vyskytne viac rovnakých hodnôt parametra v jednom produkte, spracováva sa prvá v poradí. Páruje sa podľa existujúcej hodnoty v databáze, alebo vytvorí novú
• language (len verzia 2.0) - špecifikácie jazykovej mutácie
• <IMAGE_URL> - URL obrázka, v prípade, že bude uvedená, nastaví sa parameter ako obrázkový
• <PRICES> - ceny
• <PRICE>
• language - špecifikácie jazykovej mutácie
• <PRICELISTS> - cenníky
• <PRICELIST>
• <NAME> - názov cenníka, pokiaľ je pri importe prázdny, chápe sa ako východiskový cenník
• <PRICE_ORIGINAL> - základná cenníková cena, od ktorej sa odvodzujú ďalšie (cena pred zľavou) (neexportuje sa do odberateľského feedu)
• <PRODUCT_DISCOUNT> - zľava na variant v percentách (neexportuje sa do odberateľského feedu)
• <PRODUCT_DISCOUNT_REAL> - reálna zľava na variant použitá pre výpočet výslednej ceny (len export, neexportuje sa do odberateľského feedu), vypočítava sa takto:
• hodnota zľavy na variant (<PRODUCT_DISCOUNT>) + zľava na výrobcu + zľava na kategóriu (berie sa zľava z hlavnej kategórie, v ktorej je produkt zaradený). Výsledná hodnota zľavy sa obmedzí na hodnotu z nastavenia Maximálne percento zľavy.
• <PRICE_SALE> - akčná cena, exportuje sa len vtedy, pokiaľ je variant v akcii (štítok akcie) (neexportuje sa do odberateľského feedu)
• <PRICE_WITH_VAT> - výsledná cena po zľavách s DPH (len export, exportuje sa len do odberateľského feedu)
• <PRICE_WITHOUT_VAT> - výsledná cena po zľavách bez DPH (len export, exportuje sa len do odberateľského feedu)
• <PRICE_PURCHASE> - nákupná cena, interný údaj pre orientáciu administrátora (neexportuje sa do odberateľského feedu)
• <PRICE_COMMON> - bežná cena, pre orientáciu pri nákupe, môže to byť napr. cena v kamenných obchodoch (neexportuje sa do odberateľského feedu)
• <CURRENCY> - mena (len export)
• <METAS> - vlastné pole variantov
• <META>
• type - typ vlastného poľa, možné hodnoty:
• radio - prepínač
• checkbox - zaškrtávacie políčko
• input - textové pole
• date - dátum
• email - e-mail
• number - číslo
• select - rozbaľovacia ponuka
• multiselect - multi rozbaľovacia ponuka
• textarea - viacriadkové textové pole
• formatted - viacriadkové textové pole formátované (WYSIWYG)
• <META_KEY> - Kľúč vlastného poľa - povolené znaky sú malé písmená, čísla (nesmú byť na prvej pozícii) a podtržítko
• <META_VALUE> - hodnota vlastného poľa, uvádza sa pokiaľ je rovnaká pre všetky jazykové mutácie
• <META_VALUES> - hodnoty vlastného poľa pre jednotlivé jazykové mutácie
• <META_VALUE>
• language - špecifikácie jazykovej mutácie
• <RELATED_PRODUCTS> - súvisiace produkty
• <CODE> - kód súvisiaceho produktu, páruje sa podľa existujúcej hodnoty v databáze
• <ALTERNATIVE_PRODUCTS> - alternatívne produkty
• <CODE> - kód alternatívneho produktu, páruje sa podľa existujúcej hodnoty v databáze
• <ACCESSORIES> - príslušenstvo
• <CODE> - kód produktu príslušenstva, páruje sa podľa existujúcej hodnoty v databáze
• <GIFTS> - darčeky
• <CODE> - kód darčeka k produktu, páruje sa podľa existujúcej hodnoty v databáze
• <SETS> - sada
• <CODE> - kód produktu, páruje sa podľa existujúcej hodnoty v databáze
• <METAS> - vlastné pole
• <META
• type - typ vlastného poľa, možné hodnoty:
• radio - prepínač
• checkbox - zaškrtávacie políčko
• input - textové pole
• date - dátum
• email - e-mail
• number - číslo
• select - rozbaľovacia ponuka
• multiselect - multi rozbaľovacia ponuka
• textarea - viacriadkové textové pole
• formatted - viacriadkové textové pole formátované (WYSIWYG)
• <META_KEY> - kľúč vlastného poľa - povolené znaky sú malé písmená, čísla (nesmú byť na prvej pozícii) a podtržítko
• <META_VALUE> - hodnota vlastného poľa, uvádza sa pokiaľ je rovnaká pre všetky jazykové mutácie
• <META_VALUES> - hodnoty vlastného poľa pre jednotlivé jazykové mutácie
• <META_VALUE>
• language - špecifikácie jazykovej mutácie