/ API
Obecné Jak začít PAMICA POHODA
Kontakty

Základní struktura XML dokumentu


Program POHODA používá pro XML komunikaci strukturované XML dokumenty, jejichž formát je definován pomocí XSD schémat.

Každá agenda (např. faktury, adresář, objednávky) má své vlastní XSD schéma, které určuje, jak má vypadat struktura XML souboru pro import nebo export dat.

XML komunikace v programu POHODA funguje na základě standardního principu požadavek–odpověď, který zajišťuje strukturovanou výměnu dat mezi externím systémem a aplikací POHODA.


Struktura XML požadavku a jeho účel

Co je XML požadavek

XML požadavek je strukturovaný dokument, který slouží k předání instrukcí systému POHODA. Obsahuje informace o tom, jaký typ operace má být proveden (např. import faktury, aktualizace adresáře, export zásob) a jaká data se mají zpracovat.


Z čeho se XML požadavek skládá

  • Kořenový element <dataPack>
    Obsahuje základní metadata o požadavku (verze, ID, jazyk).
    Může obsahovat více položek <dataPackItem>, z nichž každá představuje jednu operaci.
  • Položky <dataPackItem>
    Reprezentují konkrétní záznam (např. jednu fakturu).
    Obsahují datový blok s konkrétní strukturou dle typu záznamu (např. <invoice>, <addressbook>, <stock>).
  • Namespace (jmenné prostory)
    Každý typ záznamu má vlastní XML namespace, který určuje jeho strukturu a validaci.
  • Verzování
    Atribut version určuje verzi XML formátu (např. 2.0).

K čemu XML požadavek slouží

  • Import dat do systému POHODA (např. nové faktury, objednávky, adresy).
  • Export dat z POHODY (např. seznam zásob, účetní doklady).
  • Aktualizace existujících záznamů (např. změna údajů zákazníka).
  • Mazání záznamů (např. smazání adres).
  • Tisk tiskových sestav programu POHODA do PDF nebo na tiskárnu.
  • Odeslání emailu z programu POHODA.

Obálka dataPack - Kořenový element XML dokumentu

Element <dataPack> je hlavní obálkou XML požadavku, která definuje základní parametry komunikace. Obsahuje jeden nebo více elementů <dataPackItem>, z nichž každý představuje jednu operaci nad konkrétním typem dat.

Hlavní atributy:
  • version – verze XML formátu (např. "2.0").
  • id – identifikátor požadavku (např. "import").
  • xmlns:dat – namespace pro datový balíček
  • ico – ičo firmy, pro kterou je požadavek určen. Slouží k identifikaci účetní jednotky.
  • key – jedinečný identifikátor firmy, pro kterou je požadavek určen. Slouží k identifikaci účetní jednotky.
    Pokud není uveden atribut "ico" (nebo je prázdný), hodnota musí souhlasit s "klíčem" zadané firmy.
  • application – název aplikace nebo systému, který požadavek generuje (např. "eshop").
  • note – volitelná poznámka k požadavku, může obsahovat doplňující informace.

      
       <dat:dataPack version="2.0" id="import" ico="12345678" application="eshop" note="Import objednávek" key="REQ001" xmlns:dat="http://www.stormware.cz/schema/version_2/data.xsd">
  <!-- Obsahuje jeden nebo více dataPackItem -->
</dat:dataPack>

Položky dataPackItem

Element <dataPackItem> představuje jednu konkrétní operaci v rámci XML požadavku. (např. import faktury, export zásob, XML tisk).
Obsahuje konkrétní datový záznam (např. jednu fakturu). Každý záznam je vnořený v elementu odpovídajícím dané agendě (např. <invoice>, <print> , <stock>).

Hlavní atributy:
  • version – verze datovéhé bloku (např. "2.0").
  • id – identifikátor požadavku (např. "import").
  • xmlns:dat – Namespace podle typu záznamu (např. inv: pro faktury, stk: pro sklad).

Obsah:
  • Vnořený element odpovídající typu záznamu (např. <inv:invoice>, <stk:stock>, <adr:addressbook>)

      
        <dat:dataPackItem id="inv001" version="2.0">
  <inv:invoice version="2.0">
    <!-- Obsah faktury -->
  </inv:invoice>
</dat:dataPackItem>


Struktura XML odpovědi – responsePack

Po zpracování XML požadavku POHODA vrací odpověď ve formátu XML, která informuje o výsledku operace. Tato odpověď je strukturována pomocí kořenového elementu <responsePack> , který obsahuje jeden nebo více elementů <responsePackItem>.

Hlavní atributy:
  • id – identifikátor dávky, musí odpovídat id z původního dataPack požadavku.
  • version – odpovědi (např. "2.0").
  • xmlns:rsp – Namespace pro odpověď (např. "http://www.stormware.cz/schema/version_2/response.xsd").
  • state – stav zpracování požadavku (ok, error, warning)

      
        <rsp:responsePack version="2.0" id="response" state="ok" xmlns:rsp="http://www.stormware.cz/schema/version_2/response.xsd">
  <!-- Obsahuje jeden nebo více responsePackItem -->
</rsp:responsePack>

Element responsePackItem

Každý <responsePackItem> odpovídá jednomu záznamu z požadavku (např. jedné faktuře) a obsahuje informace o tom, zda byla operace úspěšná, případně jaké chyby nastaly.



Obsahuje:
  • <state> – Stav operace (ok, error, warning)
  • <note> – Textová zpráva s popisem výsledku nebo chyby
  • <importDetails> – (volitelně) podrobnosti o zpracování jednotlivých částí záznamu
  • <detail> – Obsahuje konkrétní chyby, včetně kódu a zprávy.
  • <code> – Číselný kód chyby (např. 603).
  • <message> – Popis chyby (např. „Chybí povinné pole 'date'.").
  • <recordItem> – Identifikace části záznamu, kde chyba nastala (např. invoiceHeader)

      
        <rsp:responsePackItem id="inv001" state="ok">
        <rsp:state>ok</rsp:state>
  <rsp:note>Faktura byla úspěšně importována.</rsp:note>
</rsp:responsePackItem>

Chybové hlášení

V případě chyby může odpověď obsahovat podrobnosti v elementech <importDetails> a <detail>, např.:


      
       <rsp:responsePackItem id="invoice1">
  <rsp:state>error</rsp:state>
  <rsp:note>Import se nezdařil.</rsp:note>
  <rsp:importDetails>
    <rsp:detail>
      <rsp:code>1001</rsp:code>
      <rsp:message>Chybí povinné pole 'date'.</rsp:message>
    </rsp:detail>
  </rsp:importDetails>
</rsp:responsePackItem>