Dokumentace XML - zákazníci

Základní pravidla

• XML se používá pro import do Upgates i export z Upgates
• Můžete se podívat na prázdné vzorové XML
• Na testování struktury je možné použít naše XSD
• Tagy končiace 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-DDTHH:MM:SS dle ISO 8601. Y je rok, M je měsíc a D je den.
• 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 <ADDRESSES>, pokud neobsahuje žádné adresy)
• V případě editace (při importu) se prázdný tag chápe jako vymazání původní hodnoty v databázi
• Zákazníci se při importu párují podle emailu
• Všechny tagy jsou nepovinné, kromě kořenových tagů <CONTACTS> a <CONTACT>. Při importu nových zákazníků je povinný tag <EMAIL> (s celou nadřazenou strukturou). Dále je všude povinný atribut language.
• Systém eviduje 3 druhy zákazníků:
  • 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, které mohou obsahovat HTML formátování, je možno zapsat buď převedeno do HTML entit, anebo pomocí CDATA (<![CDATA[ ]]>)
• Číselné hodnoty se uvádí nezformátované bez znaku jednotky (např. ceny, hmotnost nebo DPH). Jako oddělovač desetinných míst použijte tečku nebo čárku.
• Další chování importu můžete ovlivnit nastavením v administraci
• Více informací o importu najdete v článku Import dat do e-shopu.

Export

• Exportují se všechny tagy z výjimkou tagů s prázdnou hodnotou, ty mohou v exportu chybět
• Export z jednoho e-shopu Upgates je možno použít pro import do jiného e-shopu Upgates

Struktura XML

• <CONTACTS>
  • version - verze formátu XML, aktuálně je to 1.0
  • <CONTACT>
    • <CUSTOMER_ID> - ID zákazníka (pouze export)
    • <CUSTOMER_YN>
      • 1 = zákazník (registrovaný; má zákaznický účet)
      • 0 = kontakt (neregistrovaný)
    • <COMPANY_YN>
      • 1 = firemní zákazník (má vyplněné firemní údaje)
      • 0 = osoba zákazník
    • <DEGREE> - titul
    • <FIRSTNAME> - křestní jméno
    • <SURNAME> - příjmení
    • <NICKNAME> - přezdívka
    • <CODE> - zákaznické číslo. Pokud není uvedeno, vyplní se automaticky podle číselné řady
    • <LANGUAGE> - dvoumístný kód jazyka, pod kterým byl kontakt vytvořen. Jazyk musí být založený v administraci. Pokud není uvedený, automaticky se bere výchozí jazyk
    • <NEWSLETTER_YN> - kontakt chce / nechce dostávat newsletter
    • <CAN_SEE_PRIVATE_YN> - zákazník vidí / nevidí neveřejný obsah
    • <SET_PRICELIST_BY_TURNOVER_YN> - nastavený ceník podle obratu zákazníka
    • <PRICELIST> - název ceníku, který má zákazník přidělen. Páruje se podle existující hodnoty v databázi (v hlavním jazyku) a pokud neexistuje, nezakládá se automaticky nová!
    • <DEFAULT_TURNOVER> - výchozí hodnota obratu
    • <TURNOVER> - obrat zákazníka (pouze export)
    • <TURNOVER_CURRENCY> - měna obratu zákazníka (pouze export)
    • <LOYALTY_SYSTEM> - počet bodů získaných ve věrnostním systému
    • <NOTE> - poznámka
    • <CAN_RATE_PRODUCTS_YN> - může hodnotit produkty - hvězdičky, recenze
    • <COMPANY> - firemní údaje
      • <NAME> - název firmy
      • <COMPANY_NUMBER> - IČO
      • <VAT_NUMBER> - DIČ
      • <VAT_PAYER_YN> - plátce DPH
    • <COMMUNICATION> - komunikace
      • <PHONE> - telefon. Pouze čísla a znak + na začátku, všechny ostatní znaky budou odstraněny
      • <FAX> - fax
      • <IM> - instant messaging
      • <SALUTATION> - oslovení zákazníka (v jeho jazyce)
      • <DECLENSION> - skloňování zákazníkova jména v 5. pádě
    • <LOGIN> - přihlašovací údaje
      • <ACTIVE_YN> - povolení nebo zakázání přihlášení zákazníka do zákaznického účtu
      • <BLOCKED_YN> - blokovaný kontakt
      • <EMAIL> - jednoznačný identifikátor kontaktu a zákazníka (POVINNÝ). Přihlašovací údaj do zákaznického účtu v případě zákazníka. Páruje se podle existující hodnoty v databázi, nebo vytvoří nový kontakt
      • <PASSWORD> - heslo pro přihlášení do zákaznického účtu. Pokud je uvedeno, bude nový zákazník založen s tímto heslem a stávajícímu se změní. Pokud není uvedeno, stávajícímu zákazníkovi zůstane původní heslo a novému se vygeneruje náhodné
    • <GROUPS> - skupiny
      • <GROUP> - název skupiny. Páruje se podle existující hodnoty v databázi (v hlavním jazyku), nebo vytvoří novou
    • <ADDRESSES> - adresy
      • <BILLING> - fakturační adresa
        • <STREET> - ulice a číslo
        • <CITY> - město
        • <STATE> - kraj
        • <ZIP_CODE> - PSČ
        • <COUNTRY_ID> - dvoumístný kód země podle ISO 3166-1 alpha-2
      • <POSTAL> - doručovací adresa (možno opakovat vícekrát)
        • <COMPANY_NAME> - název firmy
        • <FIRSTNAME> - křestní jméno
        • <SURNAME> - příjmení
        • <STREET> - ulice a číslo
        • <CITY> - město
        • <STATE> - kraj
        • <ZIP_CODE> - PSČ
        • <COUNTRY_ID> - dvoumístný kód země podle ISO 3166-1 alpha-2
    • <AGREEMENTS> - souhlasy
      • <AGREEMENT>
        • <NAME> - název souhlasu, páruje se s existujícím souhlasem v databázi. Pokud odpovídající souhlas neexistuje, ignoruje se
        • <TIME> - čas pořízení souhlasu. Pokud bude prázdné, nebo nebude uvedeno, bere se aktuální čas
        • <IP> - IP adresa zákazníka při souhlasu
        • <VALID_TO> - čas do kdy je souhlas platný. Pokud bude prázdné, anebo nebude uvedeno, bere se z nastavení konkrétního souhlasu
        • <STATUS> - stav souhlasu, ano / ne, může nabývat hodnot 1/0
    • <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