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ázev TypPovinné?Popis
ORDER_ID VARCHAR(255) Ano Interní 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
CODE VARCHAR(255) Ano Číslo objednávky tak, jak jej vidí koncový zákazník
INVOICE_CODE VARCHAR(255) Ne Číslo faktury tak, jak jej vidí koncový zákazník
DATE DATETIME Ano Datum založení 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 původní objednávky
CUSTOMER Ano Informace o zákazníkovi (viz další tabulka)
TOTAL_PRICE Ano Informace o ceně objednávky (viz další tabulka)
ORDER_ITEMS Ano Položky objednávky (viz další sekce)
Popis polí tagu CUSTOMER:
EMAIL VARCHAR(254) Ano Email zákazníka, musí být validní emailová adresa
PHONE VARCHAR(255) Ne Telefon zákazníka, pro další použití ideálně v E.164 formátu (ale nevaliduje se proti němu)
BILLING_ADDRESS Ano Fakturační adresa zákazníka (viz další tabulka)
SHIPPING_ADDRESS Ano Doruč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:
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 číslo domu zvlášť, uveďte jej dohromady s ulicí v předchozím tagu a tento nechte prázdný)
CITY VARCHAR(255) Ano Město
ZIP VARCHAR(255) Ano PSČ
COUNTRY VARCHAR(255) Ano Země (v lidsky čitelném formátu, např. Česká republika)
COMPANY_ID VARCHAR(255) Ne IČ společnosti (pouze tag BILLING_ADDRESS)
VAT_ID VARCHAR(255) Ne DIČ společnosti (pouze tag BILLING_ADDRESS)
Popis polí tagu TOTAL_PRICE:
WITH_VAT FLOAT Aspoň jedno z WITH_VAT / WITHOUT_VAT Celková cena objednávky s DPH
WITHOUT_VAT FLOAT Aspoň jedno z WITH_VAT / WITHOUT_VAT Celková cena objednávky bez DPH (neplátci DPH vyplní pouze toto pole)
VAT FLOAT Pokud je WITH_VAT DPH (v absolutní částce)
ROUNDING FLOAT Ne Zaokrouhlení

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í:
TYPE ENUM Ano Typ položky (možné typy viz další tabulka)
NAME VARCHAR(255) Ano Název položky
CODE VARCHAR(255) Ano Kód produktu (uvidí zákazník)
VARIANT_NAME VARCHAR(255) Ne Název varianty (např. u oblečení velikost/barva)
MANUFACTURER VARCHAR(255) Ne Výrobce
AMOUNTFLOAT Ano Množství (nejčastěji počet kusů)
UNIT VARCHAR(10) Ano Jednotka (nejčastěji "ks")
WEIGHT FLOAT Ne Hmotnost v kg
UNIT_PRICE Ano Jednotková cena
TOTAL_PRICE Ano Celková cena za celkové množství této položky
Typy položek:
product Zboží (toto bude možné reklamovat/vrátit)
discount Sleva
shipping Doprava
billing Platba (např. dobírkou, kartou)
Popis polí tagu UNIT_PRICE a TOTAL_PRICE:
WITH_VAT FLOAT Aspoň jedno z WITH_VAT / WITHOUT_VAT Celková cena objednávky s DPH
WITHOUT_VAT FLOAT Aspoň jedno z WITH_VAT / WITHOUT_VAT Celková cena objednávky bez DPH (neplátci DPH vyplní pouze toto pole)
VAT FLOAT Pokud je WITH_VAT DPH (v absolutní částce)
VAT_RATE FLOAT Pokud je WITH_VAT DPH (v procentech, např. "21")

Mechanismus načítání feedu

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>
Vyzkoušet zdarma