Retino XML feed

Retino XML feed – documentation

Even if you are not using a natively supported 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 (DECIMAL 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>
    <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>
            (... item structure - see below ...)
        </ITEM>
        <ITEM>
            (... item structure - see below ...)
        </ITEM>
        (... more items ...)
    </ORDER_ITEMS>
</ORDER>

Field description:

Name	Type	Required?	Description
ORDER_ID	VARCHAR(255)	Yes	Internal 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.
ORDER_URL	VARCHAR(255)	No	Link to the order detail in the shop administation
CODE	VARCHAR(255)	Yes	Order code as observable by the customer
INVOICE_CODE	VARCHAR(255)	No	Invoice code as observable by the customer
DATE	DATETIME	Yes	Order date formatted as ISO 8601
CURRENCY/CODE	VARCHAR(3)	Yes	Order currency formatted as ISO 4217
PACKAGE_NUMBER	VARCHAR(255)	No	Package number of the order
CUSTOMER		Yes	Customer info (see below)
TOTAL_PRICE		Yes	Order price (see below)
ORDER_ITEMS		Yes	Order items (see below)

Tag CUSTOMER description:

EMAIL	VARCHAR(254)	Yes	Customer’s email, must be a valid email address
PHONE	VARCHAR(255)	No	Customer’s phone number, ideally in E.164 format (however it is not validated)
BILLING_ADDRESS		Yes	Customer’s billing address (see below)
SHIPPING_ADDRESS		Yes	Customer’s shipping address (see below). If this is the same as billing address, just state it twice

Tags BILLING_ADDRESS and SHIPPING_ADDRESS description:

NAME	VARCHAR(255)	Yes	Customer’s name
COMPANY	VARCHAR(255)	No	Company’s name
STREET	VARCHAR(255)	Yes	Street
HOUSENUMBER	VARCHAR(255)	No	House number (if you don’t have separate house number, leave this empty and put both street and house number in the STREET tag)
CITY	VARCHAR(255)	Yes	City
ZIP	VARCHAR(255)	Yes	Zip code
COUNTRY	VARCHAR(255)	Yes	Country (ISO-3166 format, but is not validated)
COMPANY_ID	VARCHAR(255)	No	Company registration ID (only tag BILLING_ADDRESS)
VAT_ID	VARCHAR(255)	No	Company VAT ID (only tag BILLING_ADDRESS)

Tag TOTAL_PRICE description:

WITH_VAT	DECIMAL	At least one of WITH_VAT / WITHOUT_VAT	Total price of order including VAT
WITHOUT_VAT	DECIMAL	At least one ofWITH_VAT / WITHOUT_VAT	Total price of order excluding VAT (if you are not VAT payers, fill just this tag)
VAT	DECIMAL	If WITH_VAT is used	VAT (absolute amount)
ROUNDING	DECIMAL	No	Rounding

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:

TYPE	ENUM	Yes	Item type (see possible values below)
NAME	VARCHAR(255)	Yes	Item name
CODE	VARCHAR(255)	Yes	Product ID / code
VARIANT_NAME	VARCHAR(255)	No	Variant name (e.g. color or size for fashion products)
MANUFACTURER	VARCHAR(255)	No	Manufacturer
AMOUNT	DECIMAL	Yes	Amount
UNIT	VARCHAR(10)	Yes	Unit (e.g. “pc” or “g”)
WEIGHT	DECIMAL	No	Weight in kg
UNIT_PRICE		Yes	Unit price
TOTAL_PRICE		Yes	Total price for all the amount
IMGURL	VARCHAR(255)	No	Image url of the item

Item types:

product	Product (customer will be able to return this)
discount	Discount
shipping	Shipping
billing	Billing (e.g. payment card, …)

Tags UNIT_PRICE and TOTAL_PRICE description:

WITH_VAT	DECIMAL	At least one of WITH_VAT / WITHOUT_VAT	Price including VAT
WITHOUT_VAT	DECIMAL	At least one of WITH_VAT / WITHOUT_VAT	Price excluding VAT (non-payers only fill this tag)
VAT	DECIMAL	If there is WITH_VAT	VAT (absolute amount)
VAT_RATE	DECIMAL	If there is WITH_VAT	VAT (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:

Static generation, so that it contains orders from the past X days. We recommend X = 7.
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.

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.

Data transfer security

Data transfer is via HTTPS and you can secure it with HTTP Basic authentication. We recommend using HTTP Basic authentication for data security reasons. If this is not possible in your case, we recommend publishing the feed at an “unguessable” URL, such as www.store.com/9b9972387feb11eabc550242ac130003.xml.

Special characters

Beware that XML format doesn’t allow special characters such as <, > or & inside strings. The easiest way to solve this is to use the CDATA entity.

Wrong example (XML parser won’t parse this):

<NAME>Slim&Sun 100 tablet</NAME>

Correct exaple (using CDATA):

<NAME><![CDATA[Slim&Sun 100 tablet]]></NAME>

Feed validation

To test if the XML feed you are generating has valid format. Download XSD schema below:

retino_xml_schema.xsd

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

Questions? Contact us at support@retino.com.