Základom strojovej komunikácie s ABRA Flexi je ABRA Flexi XML — tá istá štruktúra slúži na čítanie aj na zápis dát. Použiť ju možno aj vo formáte JSON, kde sa atribúty zapisujú ako kľúče so zavináčom (napr. @rowCount).
Okrem XML a JSON dokáže REST API vydať aj prijať dáta v ďalších formátoch (CSV, XLSX, DBF, ISDOC, EDI) — ich prehľad nájdete v článku Podporované formáty.
Princípy ABRA Flexi XML
ABRA Flexi XML slúži na import aj export dát a tiež na inkrementálnu aktualizáciu, keď súbor obsahuje len tie vlastnosti, ktoré sa majú zmeniť. Na rovnakom základe stavia REST API. Na identifikáciu záznamov a väzieb možno použiť vnútorné ID, kód, UUID dokladu (key:), EAN, PLU aj vlastné externé identifikátory — úplný prehľad je v článku Identifikátory záznamov.
Neúplné XML nie je chyba: vlastnosti, ktoré neuvediete, sa buď dopočítajú, prevezmú z typu dokladu, alebo ich určí iná väzba — výberom firmy sa napríklad na faktúre vyplní aj IČO a adresa. Podrobnejšie to popisuje článok Vnútorné väzby pri ukladaní.
Koreňový element a voľba evidencie
Celý súbor je obalený koreňovým elementom. Server prijíma dva názvy — winstrom a flexibee; iný koreňový element odmietne s hlásením Kořenový element … není podporován. Atribút version je nepovinný, ale je zvykom ho uvádzať. Výstup z API má vždy koreň winstrom, s tým teda musí počítať parser na strane integrácie.
O tom, do ktorej evidencie záznam patrí, rozhoduje názov elementu vnútri koreňa — nie evidencia uvedená v URL. V jednom súbore preto možno poslať záznamy do niekoľkých evidencií naraz:
<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>
⚠️ Ak pošlete element <cenik> na adresu /c/{firma}/faktura-vydana.xml, vznikne záznam v cenníku — evidencia z URL sa pri importe neuplatní. Neznámy názov evidencie naopak skončí chybou Nalezen nepodporovaný uzel a neimportuje sa nič.
Veľkosť písmen
Na veľkosti písmen v názvoch elementov záleží. Názvy evidencií sú vždy malými písmenami a jednotlivé slová sú oddelené pomlčkou (napr. faktura-vydana, faktura-prijata, typ-dokladu). Názvy jednotlivých vlastností sú vo formáte camelCase (napr. typDokl, vytvaretKorPol, typPolozkyK).
Príklad:
<winstrom version="1.0">
<faktura-prijata>
<typDokl>code:FAKTURA</typDokl>
<vytvaretKorPol>false</vytvaretKorPol>
</faktura-prijata>
</winstrom>
🚨 Vlastnosť napísaná inou veľkosťou písmen sa ticho ignoruje: element <Popis> sa nezapíše, ale server napriek tomu odpovie success=true a updated=1. Z odpovede teda chybu nezistíte — prejaví sa až tým, že hodnota v ABRA Flexi chýba. Pri názve evidencie a pri prefixoch identifikátorov (code:, ext:) naopak veľkosť písmen nerozhoduje.
Princíp externých ID
Aby externý systém nestratil väzbu na záznamy v ABRA Flexi, možno každému záznamu priradiť vlastný identifikátor v tvare ext:SHOP:123, kde SHOP označuje externý systém a 123 je identifikátor záznamu v ňom. Ako si systém pomenujete, je na Vás.
Čo je pri externých identifikátoroch dobré vedieť:
Jeden záznam ich môže niesť viac — pridávajú sa ďalšími elementmi
<id>a možno ich pripojiť aj k záznamu, ktorý už v ABRA Flexi existuje.V rámci jednej evidencie musí byť externý identifikátor unikátny.
Ak sa pri importe odkážete na externý identifikátor, ktorý neexistuje, záznam sa založí. Neexistujúce vnútorné číselné ID naopak skončí chybou
Nebyl nalezen záznam s ID.Pri čítaní server na neinterný identifikátor odpovie presmerovaním
301na adresu s číselným ID — klient musí vedieť presmerovanie nasledovať.Skupinu identifikátorov zmaže atribút
removeExternalIds, ktorého hodnotou je ich prefix (prázdna hodnota zmaže všetky). Prefixext:sa v hodnote uvádzať nemusí.
Nasledujúci súbor odoberie z položky cenníka všetky identifikátory začínajúce na SYSTEM3 a ponechá len ten z e-shopu:
<winstrom version="1.0">
<cenik removeExternalIds="SYSTEM3">
<id>123</id>
<id>ext:SHOP:abc</id>
</cenik>
</winstrom>
ℹ️ Tam, kde nemožno uviesť viac elementov <id> (typicky v URL), sa kombinácia identifikátorov zapisuje v hranatých zátvorkách: [123][code:CZK][ext:SHOP:abc]. Identifikátory, ktoré neexistujú, server ignoruje; ak však označujú rôzne záznamy, odpovie 400 a hlásením, že identifikátory označujú rôzne objekty.