Retino XML feed – dokumentace

Pro datové napojení obchodů, které nejsou postavené na krabicovém řešení, používáme objednávkový XML feed

Zde najdete popis struktury feedu a mechaniku stahování.

Struktura feedu

Každý feed začíná xml hlavičkou s označením verze 1.0 a kódováním UTF-8. Podporujeme pouze kódování UTF-8. Následuje párový tag, ve kterém jsou všechny objednávky (každá ve svém tagu). Tagy jsou case-sensitive, dodržujte proto prosím velikost písmen. Na white space mezi tagy se nepřihlíží. Ceny (typ FLOAT) se píší s tečkou jako oddělovačem desetinných míst, oddělovač tisíců se nepoužívá.Příklad:

<?xml version="1.0" encoding="UTF-8"?>
<ORDERS>
    <ORDER>
        (... struktura objednávky viz dále ...)
    </ORDER>
    <ORDER>
        (... struktura objednávky viz dále ...)
    </ORDER>
    (... další objednávky ...)
</ORDERS>

Pokud potřebujete poslat prázdný feed (bez objednávek), uveďte ve feedu pouze hlavičku a prázdný párový tag ORDERS.Příklad:

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

Struktura objednávky

Příklad:

<ORDER>
    <ORDER_ID>4347</ORDER_ID>
    <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>Jiří Zákazník</NAME>
            <COMPANY></COMPANY>
            <STREET>Masarykova</STREET>
            <HOUSENUMBER>1</HOUSENUMBER>
            <CITY>Praha</CITY>
            <ZIP>10000</ZIP>
            <COUNTRY>Česká republika</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>Česká republika</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 dále ...)
        </ITEM>
        <ITEM>
            (... struktura položky viz dále ...)
        </ITEM>
        (... další položky ...)
    </ORDER_ITEMS>
</ORDER>

Popis polí:

NázevTypPovinné?Popis
ORDER_IDVARCHAR(255)AnoInterní ID ve vašem objednávkovém systému. Používáme pro proklik mezi Retinem a vaším systémem. Pokud je stejné jako CODE, uveďte jej podruhé v tomto tagu
CODEVARCHAR(255)AnoČíslo objednávky tak, jak jej vidí koncový zákazník
INVOICE_CODEVARCHAR(255)NeČíslo faktury tak, jak jej vidí koncový zákazník
DATEDATETIMEAnoDatum založení objednávky ve formátu ISO 8601
CURRENCY/CODEVARCHAR(3)AnoMěna objednávky ve formátu ISO 4217
PACKAGE_NUMBERVARCHAR(255)NeČíslo zásilky původní objednávky
CUSTOMERAnoInformace o zákazníkovi (viz další tabulka)
TOTAL_PRICEAnoInformace o ceně objednávky (viz další tabulka)
ORDER_ITEMSAnoPoložky objednávky (viz další sekce)

Popis polí tagu CUSTOMER:

EMAILVARCHAR(254)AnoEmail zákazníka, musí být validní emailová adresa
PHONEVARCHAR(255)NeTelefon zákazníka, pro další použití ideálně v E.164 formátu (ale nevaliduje se proti němu)
BILLING_ADDRESSAnoFakturační adresa zákazníka (viz další tabulka)
SHIPPING_ADDRESSAnoDoručovací adresa zákazníka (viz další tabulka), pokud je stejná s fakturační, uveďte ji zde podruhé

Popis polí tagu BILLING_ADDRESS a SHIPPING_ADDRESS:

NAMEVARCHAR(255)AnoJméno zákazníka
COMPANYVARCHAR(255)NeNázev společnosti
STREETVARCHAR(255)AnoUlice
HOUSENUMBERVARCHAR(255)NeČíslo domu (pokud nemáte číslo domu zvlášť, uveďte jej dohromady s ulicí v předchozím tagu a tento nechte prázdný)
CITYVARCHAR(255)AnoMěsto
ZIPVARCHAR(255)AnoPSČ
COUNTRYVARCHAR(255)AnoZemě (v lidsky čitelném formátu, např. Česká republika)
COMPANY_IDVARCHAR(255)NeIČ společnosti (pouze tag BILLING_ADDRESS)
VAT_IDVARCHAR(255)NeDIČ společnosti (pouze tag BILLING_ADDRESS)

Popis polí tagu TOTAL_PRICE:

WITH_VATFLOATAspoň jedno z WITH_VAT / WITHOUT_VATCelková cena objednávky s DPH
WITHOUT_VATFLOATAspoň jedno z WITH_VAT / WITHOUT_VATCelková cena objednávky bez DPH (neplátci DPH vyplní pouze toto pole)
VATFLOATPokud je WITH_VATDPH (v absolutní částce)
ROUNDINGFLOATNeZaokrouhlení

Struktura položky objednávky

Příklad:

<ITEM>
    <TYPE>product</TYPE>
    <NAME>Produkt 1</NAME>
    <CODE>988765</CODE>
    <VARIANT_NAME></VARIANT_NAME>
    <MANUFACTURER></MANUFACTURER>
    <AMOUNT>1</AMOUNT>
    <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>

Popis polí:

TYPEENUMAnoTyp položky (možné typy viz další tabulka)
NAMEVARCHAR(255)AnoNázev položky
CODEVARCHAR(255)AnoKód produktu (uvidí zákazník)
VARIANT_NAMEVARCHAR(255)NeNázev varianty (např. u oblečení velikost/barva)
MANUFACTURERVARCHAR(255)NeVýrobce
AMOUNTFLOATAnoMnožství (nejčastěji počet kusů)
UNITVARCHAR(10)AnoJednotka (nejčastěji „ks“)
WEIGHTFLOATNeHmotnost v kg
UNIT_PRICEAnoJednotková cena
TOTAL_PRICEAnoCelková cena za celkové množství této položky

Typy položek:

productZboží (toto bude možné reklamovat/vrátit)
discountSleva
shippingDoprava
billingPlatba (např. dobírkou, kartou)

Popis polí tagu UNIT_PRICE a TOTAL_PRICE:

WITH_VATFLOATAspoň jedno z WITH_VAT / WITHOUT_VATCelková cena objednávky s DPH
WITHOUT_VATFLOATAspoň jedno z WITH_VAT / WITHOUT_VATCelková cena objednávky bez DPH (neplátci DPH vyplní pouze toto pole)
VATFLOATPokud je WITH_VATDPH (v absolutní částce)
VAT_RATEFLOATPokud je WITH_VATDPH (v procentech, např. „21“)

Prvotní načtení feedu

Aby zákazník mohl vytvářet případ i ze starších objednávek (typicky u reklamace), potřebujeme jednorázově získat data o historických objednávkách. Zašlete nám prosím na náš customer support feed v tomto formátu, ve kterém budou objednávky za období, jaké si přeje e-shop, aby měl u nás k dispozici. Ze zkušenosti doporučujeme posledních 30 měsíců.

Inkrementální načítání feedu

Poté, co získáme prvotní feed s historickými objednávkami, systém automaticky udržuje databázi synchronizovanou. Mechanismus načítání je popsaný zde.

Feed stahujeme pravidelně v cca 6hodinových intervalech. Tento interval se může v budoucnosti změnit.V zásadě máte dvě možnosti, jak feed generovat:

  1. Generovat jej staticky v pravidelných intervalech tak, aby obsahoval objednávky za posledních X dní. Ze zkušenosti doporučujeme nastavit X = 7.
  2. Generovat jej dynamicky na základě našeho požadavku tak, že nám pošlete objednávky „které jsme ještě neviděli“, tj. uchováte si někde časovou značku posledního stahování a při dalším nám pošlete jen nové nebo nově změněné objednávky.

Přenos používá HTTPS a je možné jej zabezpečit HTTP Basic autentifikací. Váš server musí vrátit odpověď do 60s.

Pokud nám pošlete objednávku, kterou už v databázi máme, nezakládáme novou, ale updatujeme starou. Objednávky párujeme podle tagu CODE.

Vzor 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>Česká republika</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>Česká republika</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>
        <PRICE_TO_PAY>457.00</PRICE_TO_PAY>
        <PAID>1</PAID>
    </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>