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>
    <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>Czech Republic</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>Czech Republic</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>
            (... item structure - see below ...)
        </ITEM>
        <ITEM>
            (... item structure - see below ...)
        </ITEM>
        (... more items ...)
    </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é.
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 lidsky čitelné podobě, např. Česká republika)
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í)

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.

Data transfer security

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.

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>Č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>

Jste připraveni začít?

Vytvořte si svůj účet zdarma.