Pro vývojáře
Retino XML feed

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ázevTypPovinné?Popis
ORDER_IDVARCHAR(255)AnoInterní 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_URLVARCHAR(255)NeOdkaz na detail objednávky v administraci e-shopu
CODEVARCHAR(255)AnoČíslo objednávky tak, jak jej vidí zákazník
INVOICE_CODEVARCHAR(255)NeČíslo faktury tak, jak jej vidí zákazník
DATEDATETIMEAnoDatum a čas 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 pro sledování u přepravce
CUSTOMERviz nížeAnoInformace o zákazníkovi (viz níže)
TOTAL_PRICEviz nížeAnoCelková cena objednávky (viz níže)
ORDER_ITEMSviz nížeAnoPoložky objednávky (viz níže)

Popis tagu CUSTOMER:

EMAILVARCHAR(254)AnoZákazníkova emailová adresa, musí být validní email
PHONEVARCHAR(255)NeZákazníkův telefon, ideálně v E.164 formátu (ale nevaliduje se)
BILLING_ADDRESSviz nížeAnoFakturační adresa zákazníka (viz níže)
SHIPPING_ADDRESSviz nížeAnoDoruč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:

NAMEVARCHAR(255)AnoJméno zákazníka
COMPANYVARCHAR(255)NeNázev společnosti
STREETVARCHAR(255)AnoUlice
HOUSENUMBERVARCHAR(255)NeČíslo domu (pokud nemáte ulici a číslo domu zvlášť, vyplňte oboje do tagu STREET a tento nechte prázdný)
CITYVARCHAR(255)AnoMěsto
ZIPVARCHAR(255)AnoPSČ
COUNTRYVARCHAR(255)AnoZemě (v ISO-3166 formátu, ale nevaliduje se)
COMPANY_IDVARCHAR(255)NeIČ (pouze v BILLING_ADDRESS)
VAT_IDVARCHAR(255)NeDIČ (pouze v BILLING_ADDRESS)

Popis tagu TOTAL_PRICE:

WITH_VATDECIMALAspoň jedno z WITH_VAT / WITHOUT_VATCelková částka objednávky vč. DPH
WITHOUT_VATDECIMALAspoň jedno z WITH_VAT / WITHOUT_VATCelková částka objednávky bez DPH (pokud nejste plátci DPH, vyplníte pouze tento tag)
VATDECIMALPokud je vyplněno WITH_VATDPH (absolutní částka)
ROUNDINGDECIMALNeZaokrouhlení

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í:

TYPEENUMAnoTyp položky (seznam možností viz níže)
NAMEVARCHAR(255)AnoNázev položky
CODEVARCHAR(255)AnoKód produktu
VARIANT_NAMEVARCHAR(255)NeNázev varianty (např. barva nebo velikost u módy)
MANUFACTURERVARCHAR(255)NeVýrobce
AMOUNTDECIMALAnoMnožsví
UNITVARCHAR(10)AnoJednotka (např. ks nebo g)
WEIGHTDECIMALNeVáha v kg
UNIT_PRICEviz nížeAnoCena za jednotku
TOTAL_PRICEviz nížeAnoCelková cena za všechny jednotky (celé množství)
IMGURLVARCHAR(255)NeUrl adresa obrázku produktu

Typy položek:

productProdukt (toto bude moct zákazník vrátit / reklamovat)
discountSleva
shippingDoprava
billingPlatba (dobírka apod.)

Popis tagů UNIT_PRICE a TOTAL_PRICE:

WITH_VATDECIMALAspoň jedno z WITH_VAT / WITHOUT_VATCena s DPH
WITHOUT_VATDECIMALAspoň jedno z WITH_VAT / WITHOUT_VATCena bez DPH (neplátci DPH vyplní pouze toto)
VATDECIMALPokud je vyplněno WITH_VATDPH (absolutní částka)
VAT_RATEDECIMALPokud je vyplněno WITH_VATDPH (%), 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>

Máte dotaz? Napište nám na support@retino.com.

Tohle je Sparta Retino. A měli byste ho zkusit.

Myslíme si, že se vám bude líbit. Ale chápeme, že náš názor nebude úplně objektivní. Proto můžete všechny funkce Retina vyzkoušet na 14 dní zdarma.

Vyzkoušet Retino zdarma Kontaktujte nás
App screenshot