Dokumentácia XML - zákazníci

Základné pravidlá

• XML sa používa pre import do Upgates aj export z Upgates
• Môžete sa pozrieť na prázdne vzorové XML
• k testování struktury XML je možno použít naše XSD
• Tagy končící 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 <ADDRESSES>, pokiaľ neobsahuje žiadne adresy)
• V prípade editácie (pri importe) sa prázdny tag chápe ako vymazanie pôvodnej hodnoty v databáze
• Zákazníci sa pri importe párujú podľa e-mailu
• Všetky tagy sú nepovinné, okrem koreňových tagov <CONTACTS> a <CONTACT>. Pri importe nových zákazníkov je povinný tag <EMAIL> (s celou nadradenou štruktúrou). Ďalej je všade povinný atribút language.
• Systém eviduje 3 druhy zákazníkov:
  • kontakt - <CUSTOMER_YN> = 0 a <COMPANY_YN> = 0
  • zákazník osoba - <CUSTOMER_YN> = 1 a <COMPANY_YN> = 0
  • zákazník firma - <CUSTOMER_YN> = 1 a <COMPANY_YN> = 1
• Tagy, ktoré môžu obsahovať HTML formátovanie, je možné zapísať buď prevedené do HTML entity, alebo pomocou CDATA (<![CDATA[ ]]>)
• Číselné hodnoty sa uvádzajú nenaformátované bez znaku jednotky (napr. ceny, hmotnosti alebo DPH). Ako oddeľovač desatinných miest použite bodku alebo čiarku.
• Ďalšie správanie importu môžete ovplyvniť nastavením v administrácii
• Viac informácií o importe nájdete v článku Import údajov do e-shopu

Export

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

Štruktúra XML

• <CONTACTS>
  • version - verzia formátu XML, aktuálne je to 1.0
  • <CONTACT>
    • <CUSTOMER_ID> - ID zákazníka (pouze export)
    • <CUSTOMER_YN>
      • 1 = zákazník (registrovaný; má zákaznícky účet)
      • 0 = kontakt (neregistrovaný)
    • <COMPANY_YN>
      • 1 = firemný zákazník (má vyplnené firemné údaje)
      • 0 = osoba zákazník
    • <DEGREE> - titul
    • <FIRSTNAME> - krstné meno
    • <SURNAME> - priezvisko
    • <NICKNAME> - prezývka
    • <CODE> - zákaznícke číslo. Pokiaľ nie je uvedené, vyplní sa automaticky podľa číselného radu
    • <LANGUAGE> - dvojmiestny kód jazyka, pod ktorým bol kontakt vytvorený. Jazyk musí byť založený v administrácii. Pokiaľ nie je uvedený, automaticky sa berie východiskový jazyk
    • <NEWSLETTER_YN> - kontakt chce / nechce dostávať newsletter
    • <CAN_SEE_PRIVATE_YN> - zákazník vidí / nevidí neverejný obsah
    • <SET_PRICELIST_BY_TURNOVER_YN> - nastavený cenník podľa obratu zákazníka
    • <PRICELIST> - názov cenníka, ktorý má zákazník pridelený. Páruje sa podľa existujúcej hodnoty v databáze (v hlavnom jazyku) a pokiaľ neexistuje, nezakladá sa automaticky nový!
    • <DEFAULT_TURNOVER> - východisková hodnota obratu
    • <TURNOVER> - obrat zákazníka (len export)
    • <TURNOVER_CURRENCY> - mena obratu zákazníka (len export)
    • <LOYALTY_SYSTEM> - počet bodov získaných vo vernostnom systéme
    • <NOTE> - poznámka
    • <CAN_RATE_PRODUCTS_YN> - može hodnotiť produkty - hviezdičky, recenzie
    • <COMPANY> - firemné údaje
      • <NAME> - názov firmy
      • <COMPANY_NUMBER> - IČO
      • <VAT_NUMBER> - DIČ
      • <VAT_PAYER_YN> - platca DPH
    • <COMMUNICATION> - komunikácia
      • <PHONE> - telefón. Len čísla a znak + na začiatku, všetky ostatné znaky budú odstránené
      • <FAX> - fax
      • <IM> - instant messaging
      • <SALUTATION> - oslovenie zákazníka (v jeho jazyku)
      • <DECLENSION> - skloňovanie zákazníkovho mena v 5. páde
    • <LOGIN> - prihlasovacie údaje
      • <ACTIVE_YN> - povolenie alebo zakázanie prihlásenia zákazníka do zákazníckeho účtu
      • <BLOCKED_YN> - blokovaný kontakt
      • <EMAIL> - jednoznačný identifikátor kontaktu a zákazníka (POVINNÝ). Prihlasovací údaj do zákazníckeho účtu v prípade zákazníka. Páruje sa podľa existujúcej hodnoty v databáze, alebo vytvorí nový kontakt
      • <PASSWORD> - heslo pre prihlásenie do zákazníckeho účtu. Pokiaľ je uvedené, bude nový zákazník založený s týmto heslom a existujúcemu sa zmení. Pokiaľ nie je uvedené, existujúcemu zákazníkovi zostane pôvodné heslo a novému sa vygeneruje náhodné
    • <GROUPS> - skupiny
      • <GROUP> - názov skupiny. Páruje sa podľa existujúcej hodnoty v databáze (v hlavnom jazyku), alebo vytvorí novú
    • <ADDRESSES> - adresy
      • <BILLING> - fakturačná adresa
        • <STREET> - ulica a číslo
        • <CITY> - mesto
        • <STATE> - kraj
        • <ZIP_CODE> - PSČ
        • <COUNTRY_ID> - dvojmiestny kód krajiny podľa ISO 3166-1 alpha-2
      • <POSTAL> - doručovacia adresa (možno opakovať viackrát)
        • <COMPANY_NAME> - názov firmy
        • <FIRSTNAME> - krstné meno
        • <SURNAME> - priezvisko
        • <STREET> - ulica a číslo
        • <CITY> - mesto
        • <STATE> - kraj
        • <ZIP_CODE> - PSČ
        • <COUNTRY_ID> - dvojmiestny kód krajiny podľa ISO 3166-1 alpha-2
    • <AGREEMENTS> - súhlasy
      • <AGREEMENT>
        • <NAME> - názov súhlasu, páruje sa s existujúcim súhlasom v databáze. Pokiaľ zodpovedajúci súhlas neexistuje, ignoruje sa
        • <TIME> - čas vybavenia súhlasu. Pokiaľ bude prázdne, alebo nebude uvedené, berie sa aktuálny čas
        • <IP> - IP adresa zákazníka pri súhlase
        • <VALID_TO> - čas dokedy je súhlas platný. Pokiaľ bude prázdne, alebo nebude uvedené, berie sa z nastavenia konkrétneho súhlasu
        • <STATUS> - stav súhlasu, áno / nie, môže nadobúdať hodnoty 1/0
    • <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 - email
          • 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