Základem strojové komunikace s ABRA Flexi je ABRA Flexi XML — tatáž struktura slouží pro čtení i pro zápis dat. Použít ji lze i ve formátu JSON, kde se atributy zapisují jako klíče se zavináčem (např. @rowCount).
Vedle XML a JSON umí REST API vydat i přijmout data v dalších formátech (CSV, XLSX, DBF, ISDOC, EDI) — jejich přehled najdete v článku Podporované formáty.
Principy ABRA Flexi XML
ABRA Flexi XML slouží pro import i export dat a také pro inkrementální aktualizaci, kdy soubor obsahuje jen ty vlastnosti, které se mají změnit. Na stejném základu staví REST API. Pro identifikaci záznamů a vazeb lze použít vnitřní ID, kód, UUID dokladu (key:), EAN, PLU i vlastní externí identifikátory — úplný přehled je v článku Identifikátory záznamů.
Neúplné XML není chyba: vlastnosti, které neuvedete, se buď dopočítají, přeberou z typu dokladu, nebo je určí jiná vazba — vybráním firmy se například na faktuře vyplní i IČO a adresa. Podrobněji to popisuje článek Vnitřní vazby při ukládání.
Kořenový element a volba evidence
Celý soubor je obalen kořenovým elementem. Server přijímá dva názvy — winstrom a flexibee; jiný kořenový element odmítne s hlášením Kořenový element … není podporován. Atribut version je nepovinný, ale je zvykem jej uvádět. Výstup z API má vždy kořen winstrom, s tím tedy musí počítat parser na straně integrace.
O tom, do které evidence záznam patří, rozhoduje název elementu uvnitř kořene — ne evidence uvedená v URL. V jednom souboru proto lze poslat záznamy do několika evidencí zároveň:
<flexibee version="1.0">
<cenik>
<id>code:T100</id>
<nazev>Téčko 100 mm</nazev>
</cenik>
<adresar>
<id>ext:SHOP:42</id>
<nazev>Odběratel z e-shopu</nazev>
</adresar>
</flexibee>
⚠️ Pošlete-li element <cenik> na adresu /c/{firma}/faktura-vydana.xml, vznikne záznam v ceníku — evidence z URL se při importu neuplatní. Neznámý název evidence naopak skončí chybou Nalezen nepodporovaný uzel a neimportuje se nic.
Velikosti písmen
Na velikosti písmen v názvech elementů záleží. Názvy evidencí jsou vždy malými písmeny a jednotlivá slova oddělena pomlčkou (např. faktura-vydana, faktura-prijata, typ-dokladu). Názvy jednotlivých vlastností jsou ve formátu camelCase (např. typDokl, vytvaretKorPol, typPolozkyK).
Příklad:
<winstrom version="1.0">
<faktura-prijata>
<typDokl>code:FAKTURA</typDokl>
<vytvaretKorPol>false</vytvaretKorPol>
</faktura-prijata>
</winstrom>
🚨 Vlastnost napsaná jinou velikostí písmen se tiše ignoruje: element <Popis> se nezapíše, ale server přesto odpoví success=true a updated=1. Z odpovědi tedy chybu nepoznáte — projeví se až tím, že hodnota v ABRA Flexi chybí. U názvu evidence a u prefixů identifikátorů (code:, ext:) naopak velikost písmen nerozhoduje.
Princip externích ID
Aby externí systém neztratil vazbu na záznamy v ABRA Flexi, lze každému záznamu přiřadit vlastní identifikátor ve tvaru ext:SHOP:123, kde SHOP označuje externí systém a 123 je identifikátor záznamu v něm. Jak si systém pojmenujete, je na Vás.
Co je u externích identifikátorů dobré vědět:
Jeden záznam jich může nést více — přidávají se dalšími elementy
<id>a lze je připojit i k záznamu, který už v ABRA Flexi existuje.V rámci jedné evidence musí být externí identifikátor unikátní.
Odkážete-li se při importu na externí identifikátor, který neexistuje, záznam se založí. Neexistující vnitřní číselné ID naopak skončí chybou
Nebyl nalezen záznam s ID.Při čtení server na neinterní identifikátor odpoví přesměrováním
301na adresu s číselným ID — klient musí umět přesměrování následovat.Skupinu identifikátorů smaže atribut
removeExternalIds, jehož hodnotou je jejich prefix (prázdná hodnota smaže všechny). Prefixext:se v hodnotě uvádět nemusí.
Následující soubor odebere z položky ceníku všechny identifikátory začínající na SYSTEM3 a ponechá jen ten z e-shopu:
<winstrom version="1.0">
<cenik removeExternalIds="SYSTEM3">
<id>123</id>
<id>ext:SHOP:abc</id>
</cenik>
</winstrom>
ℹ️ Tam, kde nelze uvést více elementů <id> (typicky v URL), se kombinace identifikátorů zapisuje v hranatých závorkách: [123][code:CZK][ext:SHOP:abc]. Identifikátory, které neexistují, server ignoruje; pokud ale označují různé záznamy, odpoví 400 a hlášením, že identifikátory označují různé objekty.