Integrace objednávek XML

XML export objednávek

Obecná specifikace XML objednávek pro e-shopy a integrace. Povinná struktura, typy položek, ceny, DPH, slevy a ukázková data.

Než začnete

Tato stránka popisuje formát XML objednávek pro Datixo. Stažitelný soubor obsahuje syntetické příklady.

01

Struktura objednávky

Každá objednávka se posílá jako úplný záznam pod kořenem ORDERS. Použijte přesné názvy elementů a částky uvádějte jako desetinná čísla.

Kořenový element <ORDERS> obsahuje jednotlivé objednávky <ORDER>. Každý <ORDER> má jeden obal <ORDER_ITEMS>, který obsahuje opakující se položky <ITEM>.

Úplná ukázka jedné objednávky

Objednávka obsahuje dva kusy produktu. Jednotková cena 100,00 Kč bez DPH a 121,00 Kč s DPH dává celkem za řádek i objednávku 200,00 Kč a 242,00 Kč.

<?xml version="1.0" encoding="UTF-8"?>
<ORDERS>
  <ORDER>
    <ORDER_ID>order-1050</ORDER_ID>
    <CODE>2026-1050</CODE>
    <DATE>2026-05-10 14:25:00</DATE>
    <STATUS>Vyřízena</STATUS>
    <REFERER><![CDATA[https://search.example/]]></REFERER>
    <ANONYMIZED_MAIL>customer-demo-7f3a</ANONYMIZED_MAIL>
    <CURRENCY>
      <CODE>CZK</CODE>
    </CURRENCY>
    <CUSTOMER>
      <BILLING_ADDRESS>
        <COUNTRY>CZ</COUNTRY>
      </BILLING_ADDRESS>
    </CUSTOMER>
    <TOTAL_PRICE>
      <WITHOUT_VAT>200.00</WITHOUT_VAT>
      <WITH_VAT>242.00</WITH_VAT>
    </TOTAL_PRICE>
    <ORDER_ITEMS>
      <ITEM>
        <TYPE>product</TYPE>
        <NAME>Ukázkový produkt</NAME>
        <CODE>SKU-100</CODE>
        <AMOUNT>2</AMOUNT>
        <UNIT_PRICE>
          <WITHOUT_VAT>100.00</WITHOUT_VAT>
          <WITH_VAT>121.00</WITH_VAT>
          <VAT_RATE>21</VAT_RATE>
          <PURCHASE_WITHOUT_VAT>60.00</PURCHASE_WITHOUT_VAT>
          <PURCHASE_WITH_VAT>72.60</PURCHASE_WITH_VAT>
          <PURCHASE_VAT>12.60</PURCHASE_VAT>
          <PURCHASE_VAT_RATE>21</PURCHASE_VAT_RATE>
        </UNIT_PRICE>
        <TOTAL_PRICE>
          <WITHOUT_VAT>200.00</WITHOUT_VAT>
          <WITH_VAT>242.00</WITH_VAT>
          <VAT_RATE>21</VAT_RATE>
        </TOTAL_PRICE>
      </ITEM>
    </ORDER_ITEMS>
  </ORDER>
</ORDERS>

Soubor obsahuje více kompletních příkladů objednávek. Stáhnout kompletní XML příklad

Pole uvnitř <ORDER>

Cesty v této tabulce začínají uvnitř <ORDER>. Lomítko označuje vnoření: TOTAL_PRICE/WITHOUT_VAT znamená element WITHOUT_VAT uvnitř TOTAL_PRICE.

XML cestaTyp / povinnostVýznam
ORDER_IDtext; povinnýNeprázdné stabilní ID objednávky, unikátní napříč všemi zdroji jednoho projektu.
CODEtext; povinnýViditelné číslo objednávky ve stejné podobě jako v měření e-shopu; používá se k párování objednávky.
DATEtext; povinnýDatum a čas vytvoření ve formátu YYYY-MM-DD HH:MM:SS. Časovou zónu sjednejte s Datixem při nastavení exportu.
STATUStext; povinnýAktuální stav objednávky podle názvu používaného e-shopem.
REFERERtext; volitelnéZdrojová informace o odkazující stránce, pokud ji e-shop zná.
ANONYMIZED_MAILtext; volitelnéNeprůhledný pseudonym zákazníka; neposílejte skutečnou e-mailovou adresu.
CURRENCY/CODEkód měny; povinnýKód ISO 4217, například CZK nebo EUR. Všechny částky včetně nákupních cen musí být v této měně.
CUSTOMER/BILLING_ADDRESS/COUNTRYpovinné pro členění podle zeměPoužijte přesně jednu z hodnot Česko, Česká republika, Slovensko, Německo, Rakousko nebo Maďarsko. Pro Česko, Slovensko a Maďarsko lze použít také CZ, SK nebo HU. Zemi vždy vyplňte, aby se objednávka správně přiřadila.
TOTAL_PRICE/WITHOUT_VATdesetinná částka; povinnáCelková částka objednávky bez DPH, včetně položek a částek účtovaných za dopravu a platbu.
TOTAL_PRICE/WITH_VATdesetinná částka; povinnáCelková částka objednávky s DPH, včetně položek a částek účtovaných za dopravu a platbu.
ORDER_ITEMSkontejner položek; povinnýPředejte všechny aktuální řádky objednávky při každém exportu, nejen nově změněné položky.

Pole uvnitř <ITEM>

Cesty v této tabulce začínají uvnitř <ITEM>. Lomítko označuje vnoření. Každý řádek ITEM popisuje jednu položku objednávky.

XML cestaTyp / povinnostVýznam
TYPEdoporučeno; pro dopravu/platbu nutné pro správné vyloučeníTyp položky ze zdrojového systému. Předejte jeho původní hodnotu; běžné příklady jsou v číselníku níže.
NAMEtext; povinnýNázev nebo popis položky.
CODEdoporučeno; pro produkt použijte stabilní SKU/kódKód produktu nebo SKU; použijte stabilní neprázdnou hodnotu, pokud ji zdroj poskytuje.
AMOUNTcelé číslo; povinnéPočet kusů položky v objednávce.
UNIT_PRICE/WITHOUT_VATdoporučenéJednotková prodejní cena bez DPH.
UNIT_PRICE/WITH_VATdoporučenéJednotková prodejní cena s DPH.
UNIT_PRICE/VAT_RATEdoporučenáSazba DPH jednotkové prodejní ceny v procentech.
TOTAL_PRICE/WITHOUT_VATdesetinná částka; povinnáCelková cena celého řádku bez DPH za uvedené množství.
TOTAL_PRICE/WITH_VATdesetinná částka; povinnáCelková cena celého řádku s DPH za uvedené množství.
TOTAL_PRICE/VAT_RATEdoporučenáSazba DPH celkové ceny řádku v procentech.

Při každém exportu objednávky uveďte její kompletní aktuální seznam řádků, nejen změny. Změnu stavu včetně storna pošlete v aktuálním STATUS; vynechání objednávky z exportu ji samo nezruší.

Soubor musí být UTF-8 XML bez DTD a namespace. Znak &, < a > v textu escapujte jako &amp;, &lt; a &gt;. Desetinná čísla zapisujte s tečkou, bez symbolu měny a oddělovače tisíců. U všech řádků uveďte přesné celkové ceny bez DPH i s DPH. Doprava a platba jsou částky účtované zákazníkovi; interní náklady dopravce ani platební brány neuvádějte jako řádky.

02

Číselník typů položek

TYPE uchovává typ zdrojové položky. Následující hodnoty jsou běžné příklady, nikoli uzavřený seznam.

TYPEVýznamZapočítání do tržeb z položek
productBěžný prodávaný produkt.Započítává se do tržeb z položek.
setSada nebo bundle jako jedna naceněná položka.Započítává se do tržeb z položek.
bazaarBazarové nebo použité zboží.Započítává se do tržeb z položek.
serviceSlužba prodaná v objednávce.Započítává se do tržeb z položek.
discount, discount-coupon, volume-discountSleva, kupón nebo množstevní sleva.Záporná cena; její dopad v objednávce uveďte pouze jednou.
other, a další zdrojové hodnotyJiná položka. Zachovejte TYPE ze zdrojového systému.Započítává se do tržeb z položek.
shippingDoprava účtovaná zákazníkovi.Do tržeb z položek se nezahrnuje.
billingPlatba nebo poplatek za platbu účtovaný zákazníkovi.Do tržeb z položek se nezahrnuje.
03

Částky, DPH a nákupní cena

Posílejte částky bez DPH i s DPH. Součty objednávky a řádku vycházejí ze zdrojových celkových cen.

  • Uveďte přesné celkové ceny řádku WITHOUT_VAT a WITH_VAT za celé množství.
  • Pokud je sleva již zahrnuta v cenách položek, neodečítejte ji znovu.
  • Sadu exportujte jako jeden řádek s cenou celé sady po slevě; komponenty neposílejte podruhé jako placené řádky.
  • Pokud nákupní cena není dostupná, pole vynechte nebo ponechte prázdné. Nula znamená skutečnou nulovou cenu.

Nákupní údaje uvnitř UNIT_PRICE

Cesty v této tabulce začínají uvnitř UNIT_PRICE, který je uvnitř ITEM. Uveďte dostupné údaje o jednotkové nákupní ceně.

Pole XMLVýznam
PURCHASE_WITHOUT_VATJednotková nákupní cena bez DPH.
PURCHASE_WITH_VATJednotková nákupní cena s DPH.
PURCHASE_VATDaň z nákupní ceny za jednotku.
PURCHASE_VAT_RATESazba DPH použita na nákupní cenu.

Předejte všechny dostupné údaje o nákupní ceně: cenu bez DPH, cenu s DPH, částku DPH a sazbu DPH. Vyplňte pouze hodnoty, které znáte.

04

Příklady objednávek

Soubor ke stažení obsahuje běžný produkt, sadu, více variant slevy, dopravu, platbu i neznámý typ. Stáhnout kompletní XML příklad

  • Sada: jeden řádek set s cenou celé sady; žádné duplicitní komponenty.
  • Samostatná sleva: záporný řádek odečtený od ceny objednávky.
  • Sleva již zahrnutá v ceně produktu; finanční dopad slevy uveďte jen jednou.
  • Ukázková položka s vlastním typem ze zdrojového systému.

Exportujte vždy aktuální úplný obsah objednávky, aby se změněné a odebrané řádky správně promítly.

Doporučení

Úplnou syntetickou ukázku stáhněte a upravte jako výchozí bod pro vlastní export.