Retino XML feed

Pokud nepoužíváte platformu, pro kterou máme nativní integraci, můžete Retino datově integrovat se svým e-shopem prostřednictvím XML feedu v našem formátu.

V tomto článku popíšeme strukturu XML feedu a mechanismus jeho načítání.

Struktura feedu

Feed začíná xml hlavičkou s verzí 1.0 a UTF-8 kódování. Podporujeme pouze UTF-8 kódování. Poté následuje párový tag ORDERS , ve kterém jsou všechny objednávky (každá v tagu ORDER ). Tagy jsou case-sensitive. White-space (mezery apod.) mezi tagy jsou ignorovány. Ceny (typ DECIMAL ) jsou psány s desetinnou tečkou (.), bez oddělovače tisíců. Příklad:

<?xml version="1.0" encoding="UTF-8"?>
<ORDERS>
    <ORDER>
        (... order structure - see below ...)
    </ORDER>
    <ORDER>
        (... order structure - see below ...)
    </ORDER>
    (... more orders ...)
</ORDERS>

Pokud potřebujete poslat prázdný feed, vložte do něj hlavičku a prázdný párový tag ORDERS . Příklad:

<?xml version="1.0" encoding="UTF-8"?>
<ORDERS>
</ORDERS>

Struktura ORDER

Příklad:

<ORDER>
    <ORDER_ID>4347</ORDER_ID>
    <ORDER_URL>https://example.com/admin/order-detail/4347</ORDER_URL>
    <CODE>201800001</CODE>
    <INVOICE_CODE>201800001</INVOICE_CODE>
    <DATE>2018-03-02 21:46:52</DATE>
    <CURRENCY>
        <CODE>CZK</CODE>
    </CURRENCY>
    <PACKAGE_NUMBER>12345678</PACKAGE_NUMBER>
    <CUSTOMER>
        <EMAIL>zakaznik@seznam.cz</EMAIL>
        <PHONE>777123456</PHONE>
        <BILLING_ADDRESS>
            <NAME>George Customer</NAME>
            <COMPANY></COMPANY>
            <STREET>Masarykova</STREET>
            <HOUSENUMBER>1</HOUSENUMBER>
            <CITY>Praha</CITY>
            <ZIP>10000</ZIP>
            <COUNTRY>CZ</COUNTRY>
            <COMPANY_ID></COMPANY_ID>
            <VAT_ID></VAT_ID>
        </BILLING_ADDRESS>
        <SHIPPING_ADDRESS>
            <NAME>George Customer</NAME>
            <COMPANY></COMPANY>
            <STREET>Masarykova</STREET>
            <HOUSENUMBER>1</HOUSENUMBER>
            <CITY>Praha</CITY>
            <ZIP>10000</ZIP>
            <COUNTRY>CZ</COUNTRY>
        </SHIPPING_ADDRESS>
    </CUSTOMER>
    <TOTAL_PRICE>
        <WITH_VAT>457.00</WITH_VAT>
        <WITHOUT_VAT>377.68</WITHOUT_VAT>
        <VAT>79.32</VAT>
        <ROUNDING>0.00</ROUNDING>
    </TOTAL_PRICE>
    <ORDER_ITEMS>
        <ITEM>
            (... struktura položky - viz níže ...)
        </ITEM>
        <ITEM>
            (... struktura položky - viz níže ...)
        </ITEM>
        (... více položek ...)
    </ORDER_ITEMS>
</ORDER>

Popis polí:

Název Typ Povinné? Popis
ORDER_ID VARCHAR(255) Ano Interní ID používané ve vašem systému. Používáme jej pro provázání systémů přímým odkazem. Pokud je toto pole stejné jako číslo objednávky viditelné zákazníkem (tag CODE ), uveďte jej zde podruhé.
ORDER_URL VARCHAR(255) Ne Odkaz na detail objednávky v administraci e-shopu
CODE VARCHAR(255) Ano Číslo objednávky tak, jak jej vidí zákazník
INVOICE_CODE VARCHAR(255) Ne Číslo faktury tak, jak jej vidí zákazník
DATE DATETIME Ano Datum a čas objednávky ve formátu ISO 8601
CURRENCY/CODE VARCHAR(3) Ano Měna objednávky ve formátu ISO 4217
PACKAGE_NUMBER VARCHAR(255) Ne Číslo zásilky pro sledování u přepravce
CUSTOMER viz níže Ano Informace o zákazníkovi (viz níže)
TOTAL_PRICE viz níže Ano Celková cena objednávky (viz níže)
ORDER_ITEMS viz níže Ano Položky objednávky (viz níže)

Popis tagu CUSTOMER :

EMAIL VARCHAR(254) Ano Zákazníkova emailová adresa, musí být validní email
PHONE VARCHAR(255) Ne Zákazníkův telefon, ideálně v E.164 formátu (ale nevaliduje se)
BILLING_ADDRESS viz níže Ano Fakturační adresa zákazníka (viz níže)
SHIPPING_ADDRESS viz níže Ano Doručovací adresa zákazníka (viz níže) – pokud je stejná jako fakturační, uveďte ji zde podruhé

Popis tagů BILLING_ADDRESS  a SHIPPING_ADDRESS :

NAME VARCHAR(255) Ano Jméno zákazníka
COMPANY VARCHAR(255) Ne Název společnosti
STREET VARCHAR(255) Ano Ulice
HOUSENUMBER VARCHAR(255) Ne Číslo domu (pokud nemáte ulici a číslo domu zvlášť, vyplňte oboje do tagu STREET  a tento nechte prázdný)
CITY VARCHAR(255) Ano Město
ZIP VARCHAR(255) Ano PSČ
COUNTRY VARCHAR(255) Ano Země (v ISO-3166 formátu, ale nevaliduje se)
COMPANY_ID VARCHAR(255) Ne IČ (pouze v BILLING_ADDRESS )
VAT_ID VARCHAR(255) Ne DIČ (pouze v BILLING_ADDRESS )

Popis tagu TOTAL_PRICE :

WITH_VAT DECIMAL Aspoň jedno z WITH_VAT / WITHOUT_VAT Celková částka objednávky vč. DPH
WITHOUT_VAT DECIMAL Aspoň jedno z WITH_VAT / WITHOUT_VAT Celková částka objednávky bez DPH (pokud nejste plátci DPH, vyplníte pouze tento tag)
VAT DECIMAL Pokud je vyplněno WITH_VAT DPH (absolutní částka)
ROUNDING DECIMAL Ne Zaokrouhlení

Popis položky objednávky

Příklad:

<ITEM>
    <TYPE>product</TYPE>
    <NAME>Product 1</NAME>
    <CODE>988765</CODE>
    <VARIANT_NAME></VARIANT_NAME>
    <MANUFACTURER></MANUFACTURER>
    <AMOUNT>1</AMOUNT>
    <UNIT>pc</UNIT>
    <WEIGHT>0</WEIGHT>
    <UNIT_PRICE>
        <WITH_VAT>407.00</WITH_VAT>
        <WITHOUT_VAT>336.36</WITHOUT_VAT>
        <VAT>70.64</VAT>
        <VAT_RATE>21</VAT_RATE>
    </UNIT_PRICE>
    <TOTAL_PRICE>
        <WITH_VAT>407.00</WITH_VAT>
        <WITHOUT_VAT>336.36</WITHOUT_VAT>
        <VAT>70.64</VAT>
        <VAT_RATE>21</VAT_RATE>
    </TOTAL_PRICE>
</ITEM>

Popis polí:

TYPE ENUM Ano Typ položky (seznam možností viz níže)
NAME VARCHAR(255) Ano Název položky
CODE VARCHAR(255) Ano Kód produktu
VARIANT_NAME VARCHAR(255) Ne Název varianty (např. barva nebo velikost u módy)
MANUFACTURER VARCHAR(255) Ne Výrobce
AMOUNT DECIMAL Ano Množsví
UNIT VARCHAR(10) Ano Jednotka (např. ks nebo g)
WEIGHT DECIMAL Ne Váha v kg
UNIT_PRICE viz níže Ano Cena za jednotku
TOTAL_PRICE viz níže Ano Celková cena za všechny jednotky (celé množství)
IMGURL VARCHAR(255) Ne Url adresa obrázku produktu

Typy položek:

product Produkt (toto bude moct zákazník vrátit / reklamovat)
discount Sleva
shipping Doprava
billing Platba (dobírka apod.)

Popis tagů UNIT_PRICE a TOTAL_PRICE:

WITH_VAT DECIMAL Aspoň jedno z WITH_VAT / WITHOUT_VAT Cena s DPH
WITHOUT_VAT DECIMAL Aspoň jedno z WITH_VAT / WITHOUT_VAT Cena bez DPH (neplátci DPH vyplní pouze toto)
VAT DECIMAL Pokud je vyplněno WITH_VAT DPH (absolutní částka)
VAT_RATE DECIMAL Pokud je vyplněno WITH_VAT DPH (%), např. 21

Feed pro počáteční synchronizaci

Reklamace se typicky mohou řešit až 2 roky zpětně. Proto potřebujeme přístup ke starším objednávkám. Pošlete nám prosím jednorázově feed s historickými objednávkami za období, které si e-shop přeje, aby měl k dispozici v Retinu. Doporučujeme posledních 30 měsíců. Feed pošlete na naši zákaznickou podporu na support@retino.com.

Feed pro inkrementální synchronizaci

Jakmile proběhne počáteční synchronizaci, potřebujeme databázi udržovat aktuální. Pro tento účel potřebujeme inkrementální feed, který náš systém bude automaticky načítat. Funguje to následovně:

Feed si stahujeme z URL adresy každých cca 6 hodin. Tento interval se může v budoucnosti změnit. Máte dvě možnosti, jak feed generovat:

  1. Staticky generovaný feed, který obsahuje objednávky za posledních X dní. Doporučujeme X = 7.
  2. Dynamicky generovaný feed, kdy nám vždy pošlete objednávky, které „jsme ještě neviděli“, tedy že si někde uschováte časovou značku posledního načtení feedu a pak nám zašlete objednávky změněné od té doby.

Doporučujeme možnost č. 1.

Přenos dat probíhá přes HTTPS a lze jej zabezpečit přes HTTP Basic autentizaci. Doporučujeme toto zabezpečení s ohledem na bezpečnost dat. Pokud to ve vašem případě není možné, doporučujeme alespoň URL feedu nastavit na „neuhodnutelnou“ adresu, např. www.store.com/9b9972387feb11eabc550242ac130003.xml.

Váš server musí vrátit odpověď do 60 sekund.

Pokud nám pošlete objednávku, kterou jsme již viděli, nevytváříme novou, ale aktualizujeme starou. Objednávky párujeme podle tagu CODE .

Bezpečnost přenosu

Přenos dat probíhá přes HTTPS a lze jej zabezpečit přes HTTP Basic autentizaci. Doporučujeme toto zabezpečení s ohledem na bezpečnost dat. Pokud to ve vašem případě není možné, doporučujeme alespoň URL feedu nastavit na „neuhodnutelnou“ adresu, např. www.store.com/9b9972387feb11eabc550242ac130003.xml.

Pozor na speciální znaky

Upozorňujeme, že XML formát nedovoluje mít v řetězcích uvnitř dokumentu určité znaky jako <, > nebo &. Nejjednodušší řešení je všechny tagy, ve kterých se speciální znaky mohou objevit, obalit do entity CDATA.

Chybný příklad (XML parser vyhodí chybu):

<NAME>Slim&Sun 100 tablet</NAME>

Správný příklad (ošetřeno pomocí CDATA):

<NAME><![CDATA[Slim&Sun 100 tablet]]></NAME>

Kontrola feedu

Pro kontrolu správnosti formátu dat ve XML feedu můžete použít soubor typu XSD. Stáhněte si soubor obsahující schéma feedu níže:

retino_xml_schema.xsd


Příklad feedu

<?xml version="1.0" encoding="UTF-8"?>
<ORDERS><ORDER>
    <ORDER_ID>4347</ORDER_ID>
    <CODE>201800001</CODE>
    <INVOICE_CODE>2018-001</INVOICE_CODE>
    <DATE>2018-03-02 21:46:52</DATE>
    <CURRENCY>
        <CODE>CZK</CODE>
    </CURRENCY>
    <PACKAGE_NUMBER>12345678</PACKAGE_NUMBER>
    <CUSTOMER>
        <EMAIL>zakaznik@seznam.cz</EMAIL>
        <PHONE>777123456</PHONE>
        <BILLING_ADDRESS>
            <NAME>Jiří Zákazník</NAME>
            <COMPANY></COMPANY>
            <STREET>Masarykova</STREET>
            <HOUSENUMBER>1</HOUSENUMBER>
            <CITY>Praha</CITY>
            <ZIP>10000</ZIP>
            <COUNTRY>CZ</COUNTRY>
            <COMPANY_ID></COMPANY_ID>
            <VAT_ID></VAT_ID>
        </BILLING_ADDRESS>
        <SHIPPING_ADDRESS>
            <NAME>Jiří Zákazník</NAME>
            <COMPANY></COMPANY>
            <STREET>Masarykova</STREET>
            <HOUSENUMBER>1</HOUSENUMBER>
            <CITY>Praha</CITY>
            <ZIP>10000</ZIP>
            <COUNTRY>CZ</COUNTRY>
        </SHIPPING_ADDRESS>
    </CUSTOMER>
    <TOTAL_PRICE>
        <WITH_VAT>457.00</WITH_VAT>
        <WITHOUT_VAT>377.68</WITHOUT_VAT>
        <VAT>79.32</VAT>
        <ROUNDING>0</ROUNDING>
    </TOTAL_PRICE>
    <ORDER_ITEMS><ITEM>
    <TYPE>product</TYPE>
    <NAME>Produkt 1</NAME>
    <AMOUNT>1</AMOUNT>
    <CODE>988765</CODE>
    <VARIANT_NAME></VARIANT_NAME>
    <MANUFACTURER></MANUFACTURER>
    <UNIT>ks</UNIT>
    <WEIGHT>0</WEIGHT>
    <UNIT_PRICE>
        <WITH_VAT>407.00</WITH_VAT>
        <WITHOUT_VAT>336.36</WITHOUT_VAT>
        <VAT>70.64</VAT>
        <VAT_RATE>21</VAT_RATE>
    </UNIT_PRICE>
    <TOTAL_PRICE>
        <WITH_VAT>407.00</WITH_VAT>
        <WITHOUT_VAT>336.36</WITHOUT_VAT>
        <VAT>70.64</VAT>
        <VAT_RATE>21</VAT_RATE>
    </TOTAL_PRICE>
</ITEM><ITEM>
    <TYPE>shipping</TYPE>
    <NAME>Zásilkovna - Praha</NAME>
    <AMOUNT>1</AMOUNT>
    <CODE>SHIPPING16</CODE>
    <VARIANT_NAME></VARIANT_NAME>
    <MANUFACTURER></MANUFACTURER>
    <UNIT></UNIT>
    <WEIGHT>0</WEIGHT>
    <UNIT_PRICE>
        <WITH_VAT>25.00</WITH_VAT>
        <WITHOUT_VAT>20.66</WITHOUT_VAT>
        <VAT>4.34</VAT>
        <VAT_RATE>21</VAT_RATE>
    </UNIT_PRICE>
    <TOTAL_PRICE>
        <WITH_VAT>25.00</WITH_VAT>
        <WITHOUT_VAT>20.66</WITHOUT_VAT>
        <VAT>4.34</VAT>
        <VAT_RATE>21</VAT_RATE>
    </TOTAL_PRICE>
</ITEM><ITEM>
    <TYPE>billing</TYPE>
    <NAME>Dobírkou</NAME>
    <AMOUNT>1</AMOUNT>
    <CODE>BILLING3</CODE>
    <VARIANT_NAME></VARIANT_NAME>
    <MANUFACTURER></MANUFACTURER>
    <UNIT></UNIT>
    <WEIGHT>0</WEIGHT>
    <UNIT_PRICE>
        <WITH_VAT>25.00</WITH_VAT>
        <WITHOUT_VAT>20.66</WITHOUT_VAT>
        <VAT>4.34</VAT>
        <VAT_RATE>21</VAT_RATE>
    </UNIT_PRICE>
    <TOTAL_PRICE>
        <WITH_VAT>25.00</WITH_VAT>
        <WITHOUT_VAT>20.66</WITHOUT_VAT>
        <VAT>4.34</VAT>
        <VAT_RATE>21</VAT_RATE>
    </TOTAL_PRICE>
</ITEM></ORDER_ITEMS>
</ORDER>
</ORDERS>
Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.