Tento článek popisuje zjednodušenou verzi XML feedu pro základní integraci s Retino Tracking. Feed obsahuje pouze nezbytné údaje pro sledování zásilek.
Základní struktura feedu
Každý XML feed musí začínat standardní hlavičkou a obsahovat kořenový element ORDERS. Feed používá UTF-8 kódování:
<?xml version="1.0" encoding="UTF-8"?>
<ORDERS>
<ORDER>
<!-- data objednávky -->
</ORDER>
</ORDERS>
Povinné elementy
Pro základní tracking zásilek potřebujete v každé objednávce tyto elementy:
Element | Popis | Formát |
ORDER_ID | Interní ID objednávky ve vašem systému | Text (max. 255 znaků) |
CODE | Číslo objednávky viditelné zákazníkovi | Text (max. 255 znaků) |
DATE | Datum a čas vytvoření objednávky | YYYY-MM-DD HH:mm:ss |
CURRENCY/CODE | Měna objednávky | Kód měny (např. CZK) |
CUSTOMER | Informace o zákazníkovi | Komplexní element (viz níže) |
TOTAL_PRICE | Cenové údaje | Komplexní element (viz níže) |
ORDER_ITEMS | Seznam položek objednávky | Minimálně jedna položka |
Element PACKAGE_NUMBER je volitelný, ale pro sledování zásilek doporučujeme jeho vyplnění.
Struktura elementu CUSTOMER
EMAIL - E-mailová adresa zákazníka (povinné)
BILLING_ADDRESS - Fakturační adresa se všemi náležitostmi (povinné)
NAME - Jméno zákazníka
STREET - Ulice
CITY - Město
ZIP - PSČ
COUNTRY - Země
SHIPPING_ADDRESS - Doručovací adresa se stejnou strukturou jako fakturační (povinné)
Struktura elementu TOTAL_PRICE
WITH_VAT - Cena s DPH (povinné)
WITHOUT_VAT - Cena bez DPH (povinné)
Struktura položek objednávky
Každá položka v elementu ORDER_ITEMS musí obsahovat minimálně:
TYPE - Typ položky (povinné)
NAME - Název položky (povinné)
AMOUNT - Množství (povinné)
CODE - Kód položky (povinné)
UNIT_PRICE - Cena za jednotku (povinné)
TOTAL_PRICE - Celková cena (povinné)
Typy položek
Pro správnou funkčnost trackingu rozlišujeme tyto typy položek:
product - Produkt/zboží
billing - Platba (např. dobírka)
shipping - Doprava
Detekce dobírkových objednávek. Pokud je objednávka na dobírku, přidejte do ORDER_ITEMS položku typu "billing" s názvem "Dobírka". To nám umožní spolehlivě detekovat objednávky placené dobírkou.
Příklad minimálního feedu
Ukázka kompletního feedu s jednou objednávkou na dobírku:
<?xml version="1.0" encoding="UTF-8"?>
<ORDERS>
<ORDER>
<ORDER_ID>12345</ORDER_ID>
<CODE>2024001</CODE>
<DATE>2024-02-20 14:30:00</DATE>
<CURRENCY>
<CODE>CZK</CODE>
</CURRENCY>
<PACKAGE_NUMBER>DR1234567890</PACKAGE_NUMBER>
<CUSTOMER>
<EMAIL>[email protected]</EMAIL>
<BILLING_ADDRESS>
<NAME>Jan Novák</NAME>
<STREET>Hlavní 123</STREET>
<CITY>Praha</CITY>
<ZIP>110 00</ZIP>
<COUNTRY>CZ</COUNTRY>
</BILLING_ADDRESS>
<SHIPPING_ADDRESS>
<NAME>Jan Novák</NAME>
<STREET>Hlavní 123</STREET>
<CITY>Praha</CITY>
<ZIP>110 00</ZIP>
<COUNTRY>CZ</COUNTRY>
</SHIPPING_ADDRESS>
</CUSTOMER>
<TOTAL_PRICE>
<WITH_VAT>1549.00</WITH_VAT>
<WITHOUT_VAT>1280.17</WITHOUT_VAT>
</TOTAL_PRICE>
<ORDER_ITEMS>
<ITEM>
<TYPE>product</TYPE>
<NAME>Testovací produkt</NAME>
<AMOUNT>1</AMOUNT>
<CODE>TEST01</CODE>
<UNIT_PRICE>
<WITH_VAT>1499.00</WITH_VAT>
<WITHOUT_VAT>1238.84</WITHOUT_VAT>
<VAT>260.16</VAT>
<VAT_RATE>21</VAT_RATE>
</UNIT_PRICE>
<TOTAL_PRICE>
<WITH_VAT>1499.00</WITH_VAT>
<WITHOUT_VAT>1238.84</WITHOUT_VAT>
<VAT>260.16</VAT>
<VAT_RATE>21</VAT_RATE>
</TOTAL_PRICE>
</ITEM>
<ITEM>
<TYPE>billing</TYPE>
<NAME>Dobírka</NAME>
<AMOUNT>1</AMOUNT>
<CODE>COD</CODE>
<UNIT_PRICE>
<WITH_VAT>50.00</WITH_VAT>
<WITHOUT_VAT>41.33</WITHOUT_VAT>
<VAT>8.67</VAT>
<VAT_RATE>21</VAT_RATE>
</UNIT_PRICE>
<TOTAL_PRICE>
<WITH_VAT>50.00</WITH_VAT>
<WITHOUT_VAT>41.33</WITHOUT_VAT>
<VAT>8.67</VAT>
<VAT_RATE>21</VAT_RATE>
</TOTAL_PRICE>
</ITEM>
</ORDER_ITEMS>
</ORDER>
</ORDERS>
Implementace a nastavení
Základní doporučení
Feed by měl obsahovat objednávky za posledních 7 dní
Aktualizujte feed alespoň každých 6 hodin
Nastavte timeout odpovědi serveru na maximálně 60 sekund
Používejte HTTPS pro zabezpečený přenos
Zabezpečení feedu
Pro ochranu dat doporučujeme použít jeden z těchto přístupů:
HTTP Basic autentizace (preferované řešení)
Náhodně generovaná URL feedu (např. www.vaseshop.cz/feed/9b9972387feb11eabc550242ac130003.xml)
Důležité poznámky
Retino stahuje feed automaticky každých 6 hodin
Objednávky jsou párovány podle elementu CODE
Při nalezení existující objednávky dojde k její aktualizaci
Feed musí být dostupný na veřejné HTTPS adrese
Rozšíření pro vratky a reklamace
Tento feed obsahuje všechny povinné elementy podle XSD schématu. Pro pokročilejší funkce vratek a reklamací můžete přidat další volitelné elementy.
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:
Případně můžete využít validátor u nás na webu:
Kompletní dokumentaci všech volitelných elementů najdete v Retino XML feed dokumentaci.