Retino XML feed – documentation

Even if you are not using an e-commerce platform, you can still integrate Retino. In order to do so, you will need to create an XML feed.

In this document, you’ll find the XML structure and description of the sync mechanism.

Feed structure

Feed begins with xml header with version 1.0 and UTF-8 encoding. We only support UTF-8. The header is followed by a pair tag ORDER in which there are all the orders (each one in an ORDER tag). Tags are case-sensitive. White-space is ignored. Prices (FLOAT type) are written with decimal period (.). Thousands separator is not used. Example:

<?xml version="1.0" encoding="UTF-8"?>
<ORDERS>
    <ORDER>
        (... order structure - see below ...)
    </ORDER>
    <ORDER>
        (... order structure - see below ...)
    </ORDER>
    (... more orders ...)
</ORDERS>

If you need to send an empty feed (with no orders), use just the header and empty pair tag ORDERS. Example:

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

ORDER structure

Example:

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

Field description:

NameTypeRequired?Description
ORDER_IDVARCHAR(255)YesInternal ID in your system. We use it for enabling direct link between Retino and your backoffice. If this is the same as CODE, just use the same value in both tags.
CODEVARCHAR(255)YesOrder code as observable by the customer
INVOICE_CODEVARCHAR(255)NoInvoice code as observable by the customer
DATEDATETIMEYesOrder date formatted as ISO 8601
CURRENCY/CODEVARCHAR(3)YesOrder currency formatted as ISO 4217
PACKAGE_NUMBERVARCHAR(255)NoPackage number of the order
CUSTOMERYesCustomer info (see below)
TOTAL_PRICEYesOrder price (see below)
ORDER_ITEMSYesOrder items (see below)

Tag CUSTOMER description:

EMAILVARCHAR(254)YesCustomer’s email, must be a valid email address
PHONEVARCHAR(255)NoCustomer’s phone number, ideally in E.164 format (however it is not validated)
BILLING_ADDRESSYesCustomer’s billing address (see below)
SHIPPING_ADDRESSYesCustomer’s shipping address (see below). If this is the same as billing address, just state it twice

Tags BILLING_ADDRESS and SHIPPING_ADDRESS description:

NAMEVARCHAR(255)YesCustomer’s name
COMPANYVARCHAR(255)NoCompany’s name
STREETVARCHAR(255)YesStreet
HOUSENUMBERVARCHAR(255)NoHouse number (if you don’t have separate house number, leave this empty and put both street and house number in the STREET tag)
CITYVARCHAR(255)YesCity
ZIPVARCHAR(255)YesZip code
COUNTRYVARCHAR(255)YesCountry (human readable format, e.g. Czech Republic)
COMPANY_IDVARCHAR(255)NoCompany registration ID (only tag BILLING_ADDRESS)
VAT_IDVARCHAR(255)NoCompany VAT ID (only tag BILLING_ADDRESS)

Tag TOTAL_PRICE description:

WITH_VATFLOATAt least one of WITH_VAT / WITHOUT_VATTotal price of order including VAT
WITHOUT_VATFLOATAt least one ofWITH_VAT / WITHOUT_VATTotal price of order excluding VAT (if you are not VAT payers, fill just this tag)
VATFLOATIf WITH_VAT is usedVAT (absolute amount)
ROUNDINGFLOATNoRounding

Order item structure

Example:

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

Fields description:

TYPEENUMYesItem type (see possible values below)
NAMEVARCHAR(255)YesItem name
CODEVARCHAR(255)YesProduct ID / code
VARIANT_NAMEVARCHAR(255)NoVariant name (e.g. color or size for fashion products)
MANUFACTURERVARCHAR(255)NoManufacturer
AMOUNTFLOATYesAmount
UNITVARCHAR(10)YesUnit (e.g. “pc” or “g”)
WEIGHTFLOATNoWeight in kg
UNIT_PRICEYesUnit price
TOTAL_PRICEYesTotal price for all the amount

Item types:

productProduct (customer will be able to return this)
discountDiscount
shippingShipping
billingBilling (e.g. payment card, …)

Tags UNIT_PRICE and TOTAL_PRICE description:

WITH_VATFLOATAt least one of WITH_VAT / WITHOUT_VATPrice including VAT
WITHOUT_VATFLOATAt least one of WITH_VAT / WITHOUT_VATPrice excluding VAT (non-payers only fill this tag)
VATFLOATIf there is WITH_VATVAT (absolute amount)
VAT_RATEFLOATIf there is WITH_VATVAT (in percent, e.g. 21)

Initial feed syncing

We want to enable customers to create tickets from older orders (typically for warranty claims). In order to do so, we need to get data about historic orders. We would like to ask you to send us (to our customer support) feeed with orders for the period of time of merchant’s liking. We recommend past 30 months.

Incremental feed syncing

After initial feed syncing is done, we need to keep our database up to date. Therefore we need an incremental feed that our system will automatically load. You can see how this works here:

We download feed in approximately 6-hour intervals. This interval can be changed in the future. There are two possibilities for you how to generate the feed:

  1. Static generation, so that it contains orders from the past X days. We recommend X = 7.
  2. Dynamic generation, when you will send us orders that we “haven’t seen yet”, meaning you will store a timestamp of the last access to the feed and then send us only updated orders since that timestamp.

Data transfer is via HTTPS and you can secure it with HTTP Basic authentication. Your server must respond within 60 seconds.

If you send us an order which we have seen already, we don’t create a new one, but instead update the old one. Orders are paired by CODE tag.

Feed example

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