Odpovede na otázky, ktoré pri práci s REST API padajú najčastejšie — ako posielať importné XML, odkiaľ vziať strojový identifikátor firmy a ako vybrať tlačovú zostavu pre export do PDF.

Odporúčané zásady pre XML import

Čoho sa mám držať pri importe XML?

Pri importe sa oplatí dodržiavať pár zásad:

Vždy uvádzajte <id>. Keď chýba, systém zakladá nový záznam — a to aj vtedy, keď ste chceli aktualizovať ten existujúci. Pri dokladoch, ktorých kód generujete sami, sa hodí <id>code:KÓD</id>, pri integrácii s iným systémom externý identifikátor <id>ext:SHOP:111</id> (čo znamená SHOP, je čisto na Vás). Vnútorné číselné ID a hybridný ws:{UUID firmy}:{ID} sú interné: vo výstupe sa hybridný tvar objaví len v režime ?mode=xml_import_export a odkaz na neexistujúce vnútorné ID skončí chybou, zatiaľ čo neexistujúci kód či externé ID vedie k založeniu nového záznamu (pri kóde sa potom z identifikátora vyplní aj vlastnosť kod).
Položkám dávajte identifikátor, alebo použite removeAll="true". Kód pri položkách nefunguje — import skončí chybou, že entita kód neobsahuje alebo ho nemožno použiť ako ID, pretože nie je unikátny. Najlepšie je preto externý identifikátor. Položka bez identifikátora sa pri každom importe založí znova, takže pribúdajú duplicity. Atribút removeAll="true" na kolekcii položiek naopak ponechá len tie položky, ktoré sú v XML uvedené, a ostatné vymaže.
Prázdny element vymaže hodnotu, neuvedený ju necháva byť. Ak uvediete element prázdny (<popis/> alebo <popis></popis>), nastaví sa vlastnosť na prázdnu hodnotu. Ak chcete zmeniť len niektoré vlastnosti, uveďte len ich — ostatné zostanú bez zmeny.
Importujte len to, čo potrebujete. Minimálny doklad má typicky tri alebo štyri vlastnosti — typ dokladu, dátum vystavenia, sumy, prípadne položky. Zvyšok sa dopočíta, prevezme z typu dokladu alebo doplní väzbou, ako popisuje článok Vnútorné väzby pri ukladaní. Ďalšie vlastnosti pridávajte postupne, ako ich budete potrebovať.
Overte si, ako sa vlastnosť volá. Zoznam vlastností, ktoré možno pri evidencii importovať, vydá adresa /c/{firma}/{evidence}/properties.xml — pri prijatej objednávke teda objednavka-prijata/properties.xml. Zoznam všetkých evidencií je na evidence-list. Referenčnú dokumentáciu k API máte na svojom serveri pod /devdoc (pri lokálnej inštalácii https://localhost:5434/devdoc) a verejne je k nahliadnutiu na demo serveri.

Ukážka aktualizácie, ktorá prepíše popis, ponechá jedinú položku a ostatné položky dokladu vymaž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ázov kolekcie položiek sa líši podľa evidencie a nesprávny názov sa ticho ignoruje. Doklad sa založí, ale bez položiek — a odpoveď hlási úspech. Univerzálne funguje polozkyDokladu; polozkyFaktury prejde len pri faktúrach a polozkyObchDokladu len pri obchodných dokladoch typu objednávok. Ktorý názov daná evidencia pozná, vypíše zoznam väzieb /c/{firma}/{evidence}/relations.xml.

💡 Ak nechcete importom prepísať to, čo používateľ medzitým upravil ručne, pridajte na evidenciu atribút update="ignore" — existujúci záznam sa preskočí (v odpovedi sa objaví ako skipped). Hodnota fail namiesto toho import ukončí chybou. Obdobne pri väzbe atribút if-not-found určuje, čo sa stane, keď odkazovaný záznam neexistuje: null väzbu nenastaví, create chýbajúci záznam číselníkového typu založí.

⚠️ Adresy /properties a /reports nemajú HTML podobu — v prehliadači vrátia prázdnu stránku (204 No Content). Pracujte preto s príponou .xml alebo .json.

Identifikátor firmy

Keď založím firmu, ako sa bude volať strojový identifikátor spoločnosti „Nikdo Neví s.r.o."?

Všeobecný postup je taký, že sa z názvu odstránia diakritické znamienka, prevedie sa na malé písmená a všetky znaky, ktoré nie sú a-z alebo 0-9, sa nahradia podčiarknikom. Pre firmu „Nikdo Neví s.r.o." tak vyjde nikdo_nevi_s_r_o_. Výsledok však musí byť na serveri unikátny — ak taký identifikátor už existuje, pridá sa na koniec číslo; pri cloudovom riešení môže byť mechanizmus kvôli škálovateľnosti ešte zložitejší.

Niekoľko skutočných príkladov:

Názov 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ázov sa preto nespoliehajte — firmu založte a použite identifikátor, ktorý jej server pridelil. Prehľad firiem aj s ich identifikátormi (element dbNazev) vydá adresa /c.xml.

Ďalej platí:

Premenovaním firmy sa identifikátor nemení.
Obnovením zo zálohy vzniká nová firma, a tá dostane iný identifikátor ako pôvodná.
Ak firmu vymažete a založíte znova, môže byť pod rovnakým identifikátorom iná firma.

Výber reportu do PDF

Ako určiť, ktorá tlačová zostava sa použije pri exporte do PDF? V aplikácii sa ma program na výber pýta — ako to zadať cez REST API?

Zostavu vyberá parameter report-name. Bez neho sa použije predvolená zostava evidencie:

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

Prehľad zostáv, ktoré sú pre evidenciu k dispozícii, vydá adresa /c/{firma}/{evidence}/reports.xml (napríklad pre vydané faktúry, k dispozícii je aj variant v JSON). Do parametra report-name patrí hodnota z elementu reportId; na veľkosti písmen v nej nezáleží.

⚠️ Názov zostavy, ktorý v zozname nie je, skončí odpoveďou 500 a hlásením Report '…' can't be found — nie prázdnym PDF. Hodnotu preto berte zo zoznamu, nie z názvu, ako ho vidíte v aplikácii.

💡 Rýchla cesta k celej adrese: zvoľte tlač vo webovom rozhraní a pozrite sa, akú URL aplikácia vygenerovala. Úplný prehľad parametrov, ktoré možno k exportu pridať, je v článku Zostavovanie URL.

Súvisiace

Sorodni članki

Často kladené otázky API

Odporúčané zásady pre XML import

Identifikátor firmy

Výber reportu do PDF

Súvisiace