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>