Odpovědi na dotazy, které při práci s REST API padají nejčastěji — jak posílat importní XML, odkud vzít strojový identifikátor firmy a jak vybrat tiskovou sestavu pro export do PDF.

Doporučené zásady pro XML import

Čeho se mám držet při importu XML?

Při importu se vyplatí dodržovat pár zásad:

Vždy uvádějte <id>. Když chybí, systém zakládá nový záznam — a to i tehdy, když jste chtěli aktualizovat ten stávající. U dokladů, jejichž kód generujete sami, se hodí <id>code:KÓD</id>, při integraci s jiným systémem externí identifikátor <id>ext:SHOP:111</id> (co znamená SHOP, je čistě na Vás). Vnitřní číselná ID a hybridní ws:{UUID firmy}:{ID} jsou interní: ve výstupu se hybridní tvar objeví jen v režimu ?mode=xml_import_export a odkaz na neexistující vnitřní ID skončí chybou, zatímco neexistující kód či externí ID vede k založení nového záznamu (u kódu se pak z identifikátoru vyplní i vlastnost kod).
Položkám dávejte identifikátor, nebo použijte removeAll="true". Kód u položek nefunguje — import skončí chybou, že entita kód neobsahuje nebo jej nelze použít jako ID, protože není unikátní. Nejlepší je proto externí identifikátor. Položka bez identifikátoru se při každém importu založí znovu, takže přibývají duplicity. Atribut removeAll="true" na kolekci položek naopak ponechá jen ty položky, které jsou v XML uvedeny, a ostatní smaže.
Prázdný element maže hodnotu, neuvedený ji nechává být. Uvedete-li element prázdný (<popis/> nebo <popis></popis>), nastaví se vlastnost na prázdnou hodnotu. Chcete-li změnit jen některé vlastnosti, uveďte jen je — ty ostatní zůstanou beze změny.
Importujte jen to, co potřebujete. Minimální doklad má typicky tři nebo čtyři vlastnosti — typ dokladu, datum vystavení, částky, případně položky. Zbytek se dopočte, přebere z typu dokladu nebo doplní vazbou, jak popisuje článek Vnitřní vazby při ukládání. Další vlastnosti přidávejte postupně, jak je budete potřebovat.
Ověřte si, jak se vlastnost jmenuje. Seznam vlastností, které lze u evidence importovat, vydá adresa /c/{firma}/{evidence}/properties.xml — u přijaté objednávky tedy objednavka-prijata/properties.xml. Seznam všech evidencí je na evidence-list. Referenční dokumentaci k API máte na svém serveru pod /devdoc (u lokální instalace https://localhost:5434/devdoc) a veřejně je k nahlédnutí na demo serveru.

Ukázka aktualizace, která přepíše popis, ponechá jedinou položku a ostatní položky dokladu smaže:

<winstrom version="1.0">
  <objednavka-prijata>
    <id>ext:SHOP:111</id>
    <popis>Objednávka z e-shopu</popis>
    <polozkyDokladu removeAll="true">
      <objednavka-prijata-polozka>
        <id>ext:SHOP:111-1</id>
        <nazev>Téčko 100 mm</nazev>
        <mnozMj>2.0</mnozMj>
      </objednavka-prijata-polozka>
    </polozkyDokladu>
  </objednavka-prijata>
</winstrom>

🚨 Název kolekce položek se liší podle evidence a špatný název se tiše ignoruje. Doklad se založí, ale bez položek — a odpověď hlásí úspěch. Univerzálně funguje polozkyDokladu; polozkyFaktury projde jen u faktur a polozkyObchDokladu jen u obchodních dokladů typu objednávek. Který název daná evidence zná, vypíše seznam vazeb /c/{firma}/{evidence}/relations.xml.

💡 Nechcete-li importem přepsat to, co uživatel mezitím upravil ručně, přidejte na evidenci atribut update="ignore" — existující záznam se přeskočí (v odpovědi se objeví jako skipped). Hodnota fail místo toho import ukončí chybou. Obdobně u vazby atribut if-not-found určuje, co se stane, když odkazovaný záznam neexistuje: null vazbu nenastaví, create chybějící záznam číselníkového typu založí.

⚠️ Adresy /properties a /reports nemají HTML podobu — v prohlížeči vrátí prázdnou stránku (204 No Content). Pracujte proto s příponou .xml nebo .json.

Identifikátor firmy

Když založím firmu, jak se bude jmenovat strojový identifikátor společnosti „Nikdo Neví s.r.o."?

Obecný postup je, že se název odháčkuje, převede na malá písmena a všechny znaky, které nejsou a-z nebo 0-9, se nahradí podtržítkem. Pro firmu „Nikdo Neví s.r.o." tak vyjde nikdo_nevi_s_r_o_. Výsledek ale musí být na serveru unikátní — pokud takový identifikátor už existuje, přidá se na konec číslo; u cloudového řešení může být mechanizmus kvůli škálovatelnosti ještě složitější.

Několik skutečných příkladů:

Název firmy	Identifikátor
FIRMA s.r.o.	`firma_s_r_o_`
Úvod - sklady	`uvod___sklady`
PRINTOLOGY_11/2025	`printology_11_2025`
DE Test	`de_test`

Na název se proto nespoléhejte — firmu založte a použijte identifikátor, který jí server přidělil. Přehled firem i s jejich identifikátory (element dbNazev) vydá adresa /c.xml.

Dále platí:

Přejmenováním firmy se identifikátor nemění.
Obnovením ze zálohy vzniká nová firma, a ta dostane jiný identifikátor než původní.
Smažete-li firmu a založíte znovu, může být pod stejným identifikátorem jiná firma.

Výběr reportu do PDF

Jak určit, která tisková sestava se použije při exportu do PDF? V aplikaci se mě program na výběr ptá — jak to zadat přes REST API?

Sestavu vybírá parametr report-name. Bez něj se použije výchozí sestava evidence:

GET /c/{firma}/faktura-vydana/123.pdf
GET /c/{firma}/faktura-vydana/123.pdf?report-name=faktura

Přehled sestav, které jsou pro evidenci k dispozici, vydá adresa /c/{firma}/{evidence}/reports.xml (například pro vydané faktury, k dispozici je i varianta v JSON). Do parametru report-name patří hodnota z elementu reportId; na velikosti písmen v ní nezáleží.

⚠️ Název sestavy, který v seznamu není, skončí odpovědí 500 a hlášením Report '…' can't be found — nikoli prázdným PDF. Hodnotu proto berte ze seznamu, ne z názvu, jak jej vidíte v aplikaci.

💡 Rychlá cesta k celé adrese: zvolte tisk ve webovém rozhraní a podívejte se, jaké URL aplikace vygenerovala. Úplný přehled parametrů, které lze k exportu přidat, je v článku Sestavování URL.

Související

Související články

Často kladené dotazy API

Doporučené zásady pro XML import

Identifikátor firmy

Výběr reportu do PDF

Související