Dokumentácia ABRA Flexi REST API vo Swaggeri

Operácie evidencie faktura-vydana v dokumentácii ABRA Flexi REST API: GET, POST, PUT, DELETE a PDF

V skratke

Čo: dokumentácia ABRA Flexi REST API – interaktívna referencia vo Swagger UI, katalóg evidencií a polí, príručka a OpenAPI na stiahnutie.
Rozsah: 251 evidencií, 8 670 polí, 1 592 operácií a 18 príkladov zápisu overených na demo serveri.
Ako vznikla: automaticky z metadát, ktoré o sebe vracia samotná ABRA Flexi, doplnená o príklady z reálnej integrácie e-shopu.
Pre koho: analytik v nej rýchlo nájde, aké dáta vo Flexi sú, programátor si volania vyskúša priamo v prehliadači.

Prečo nestačí dokumentácia formou blogu

Oficiálna dokumentácia ABRA Flexi API dobre vysvetľuje princípy – ako funguje filtrovanie, import, identifikátory či sledovanie zmien. Je však písaná ako sada článkov a pri každodennej práci na integrácii naráža na limity:

Zoznam polí evidencie nenájdete na jednom mieste. Aké polia má vydaná faktúra, ktoré sú povinné a aké hodnoty môže mať stavUhrK? Odpoveď dá až volanie /faktura-vydana/properties na živom serveri – a výsledok je JSON so stovkami riadkov.
Analytik sa bez programátora nepohne. Pri analýze integrácie potrebuje vedieť, či Flexi eviduje napr. dodaciu adresu či IČ DPH odberateľa a ako sa pole volá. Hľadať to v článkoch je pomalé.
Príklady sú roztrúsené. Ako naraz založiť zákazníka a objednávku alebo ako zapísať dobropis s väzbou na faktúru, si musíte poskladať z viacerých stránok.
Chýba strojovo čitateľná špecifikácia. Bez súboru OpenAPI nemôžete API naimportovať do Postmanu ani si vygenerovať klienta pre C#, Javu či PHP.

Na týchto problémoch sme sa zasekávali pri vlastných integráciách s ABRA Flexi. Rozhodli sme sa preto urobiť dokumentáciu, akú by sme sami chceli mať.

Čo sme chceli dosiahnuť

Pre koho	Čo potrebuje	Riešenie
Analytik	Rýchlo nájsť evidenciu a pole, jeho typ, povinnosť a povolené hodnoty.	Katalóg evidencií a polí s vyhľadávaním.
Programátor	Operácie, parametre, štruktúru požiadaviek a odpovedí, fungujúce príklady.	Swagger UI s tlačidlom Try it out.
Integrácia	Strojovo čitateľný popis API.	Súbory OpenAPI 3.0.
Všetci	Pochopiť princípy bez čítania desiatok článkov.	Príručka v slovenčine.

Dôležitá podmienka: dokumentácia nesmie byť písaná ručne. Flexi má stovky evidencií a s každou verziou sa niečo mení – ručne udržiavaný popis by bol zastaraný skôr, než by sme ho dopísali.

Ako sme dokumentáciu vytvorili

Metadátaproperties, relations, actions, XSD

→

Generátormoduly, typy, príklady

→

OpenAPI 3.012 modulov + kompletný súbor

→

Swagger UIreferencia a Try it out

→

Katalógpre analytikov

1. Metadáta priamo z ABRA Flexi

ABRA Flexi o sebe veľa prezradí. Za cestu ktorejkoľvek evidencie stačí pridať:

/properties.json – polia s typom, názvom, povinnosťou, maximálnou dĺžkou, povolenými hodnotami a väzbou na inú evidenciu,
/relations.json – súvisiace kolekcie (položky, prílohy, úhrady…),
/actions.json – akcie ako storno či podpis na úhradu,
/reports.json – tlačové zostavy pre PDF.

Zoznam všetkých evidencií vráti /evidence-list.json aj s informáciou, či evidencia podporuje zápis. Jediné, čo v metadátach chýba, sú názvy vnorených kolekcií pri zápise – napr. že položky faktúry sa posielajú ako polozkyFaktury, ale položky objednávky ako polozkyObchDokladu. Tie sme vytiahli z XSD schém importu, ktoré Flexi poskytuje na adrese /{evidencia}/schema-import.xsd.

Všetko sme stiahli z verejného demo servera ABRA Flexi (verzia 2026.5.5) – spolu vyše tisíc volaní, len na čítanie.

2. Generátor OpenAPI

Skript v Pythone z metadát poskladá špecifikáciu OpenAPI 3.0. Pre každú evidenciu vytvorí operácie, ktoré naozaj podporuje:

Operácia	Kedy
zoznam, filter, detail	všetky evidencie
vytvorenie a úprava (import), zmazanie	len evidencie so zápisom (164 z 251)
súvisiace záznamy	evidencie s väzbami
PDF	evidencie s tlačovými zostavami

Pri typoch polí sme museli urobiť rozhodnutie, ktoré oficiálna dokumentácia nezdôrazňuje: ABRA Flexi vracia v JSON všetky hodnoty ako reťazce – aj sumy ("121.0") a logické hodnoty ("true"). Ak by špecifikácia tvrdila, že sumCelkem je číslo, vygenerovaný klient by pri čítaní odpovede zlyhal. Preto sú v špecifikácii všetky polia typu string a pôvodný typ z Flexi je v popise a v rozšírení x-flexi-type. Polia, ktoré Flexi len vypočíta, sú označené ako readOnly, výbery z číselníka majú zoznam povolených hodnôt.

Všetko v jednom súbore má 3,6 MB – to je na prehliadač priveľa. Evidencie sme preto rozdelili do 11 tematických modulov (Predaj, Nákup, Sklad, Banka a pokladňa…) a jedného spoločného modulu so službami ako changes API či webhooky. Kompletný súbor ostáva na stiahnutie pre Postman a generátory klientov.

3. Príklady z reálnej integrácie – overené

Vygenerovaná štruktúra povie, aké polia existujú, ale nie ako ich skombinovať. Príklady sme preto vzali z reálnej integrácie e-shopu a interného informačného systému s ABRA Flexi: objednávka so založením zákazníka, faktúra s položkami z cenníka, dobropis, storno, príjemka vratky, produkt s atribútmi, prijatá faktúra, honorár rozúčtovaný na zákazku a ďalšie. Údaje sme anonymizovali.

Každý z 18 príkladov overuje skript na demo serveri s parametrom dry-run=true – Flexi požiadavku spracuje so všetkými kontrolami, ale nič neuloží. Príklad, ktorý neprejde, sa do dokumentácie nedostane. Pri overovaní sme napríklad zistili, že niektoré typy záväzkov vyžadujú variabilný symbol – príklad sme doplnili.

4. Swagger UI na nva.sk

Interaktívnu referenciu zobrazuje Swagger UI, ktoré máme uložené priamo na našom webe (nenačítava sa z cudzích serverov). Demo server ABRA Flexi povoľuje volania z prehliadača (CORS), takže tlačidlo Try it out funguje bez akéhokoľvek medzikroku – požiadavka ide z vášho prehliadača priamo do Flexi. Zápisové operácie majú predvolene zapnutý dry-run, aby nikto omylom nezmenil dáta.

Swagger UI: operácia POST /faktura-vydana.json s popisom, parametrom dry-run a príkladom novej faktúry s položkami — Zápis vydanej faktúry vo Swagger UI: vnorené kolekcie, dostupné akcie, parameter `dry-run` a výber z piatich overených príkladov. Kliknutím obrázok zväčšíte.

5. Katalóg pre analytikov

Swagger je nástroj pre programátorov. Analytik potrebuje skôr tabuľku: pole, názov, typ, či je povinné a aké hodnoty môže mať. Z rovnakých dát preto generujeme aj katalóg evidencií a polí. Vyhľadáva sa v ňom po česky, po slovensky aj podľa názvu v API – napríklad zadáte „IČ DPH“ a katalóg ukáže všetky evidencie s poľom vatId.

Katalóg evidencií: detail evidencie Vydané faktúry s adresami volaní, vnorenými kolekciami a tabuľkou polí — Detail evidencie v katalógu: stav zápisu, ukážkové adresy, vnorené kolekcie a tabuľka polí s filtrom. Kliknutím obrázok zväčšíte.

6. Príručka

Nakoniec sme zhrnuli princípy do jednej príručky: štruktúra URL, prihlásenie, identifikátory, filtre, zápis, položky dokladov, akcie, chyby, synchronizácia zmien, PDF a prílohy. Každé tvrdenie sme si overili na demo serveri – vrátane HTTP kódov pri chybách.

Výsledok: tri pohľady na jedno API

Čo	Počet
Evidencie	251 v 11 moduloch
Polia	8 670, z toho 1 879 väzieb a 429 výberov z číselníka
Operácie	1 592
Overené príklady zápisu	18 v 9 evidenciách
Evidencie len na čítanie	59 (napr. saldo, účtovný denník, podklady DPH)
Evidencie so zápisom len cez nadradený záznam	28 (položky dokladov)

Pri novej verzii ABRA Flexi stačí generátor spustiť znova – dokumentácia sa obnoví za pár minút a príklady sa znovu overia.

Čo nás na ABRA Flexi API prekvapilo

Pri generovaní a overovaní sme narazili na veci, ktoré stoja za zapamätanie každému, kto na Flexi napája iný systém:

Predvolený limit je 20 záznamov. Kto ho nenastaví, ľahko prehliadne, že nedostal všetky dáta.
Identifikátor code: v URL vracia presmerovanie 301 na adresu s interným ID. HTTP klient musí presmerovania nasledovať.
Položky sa pri úprave pridávajú. Ak pošlete faktúru s položkami znova, bez polozkyFaktury@removeAll budú na nej položky dvakrát.
„Povinné“ neznamená „musíte poslať“. Metadáta označujú ako povinné aj číslo dokladu či variabilný symbol – Flexi ich však doplní sám z dokladovej rady.
Univerzálny názov položiek. Faktúry, objednávky aj bankové či skladové doklady prijímajú okrem vlastného názvu kolekcie aj polozkyDokladu.
Viac evidencií v jednej požiadavke. Zákazníka aj objednávku, ktorá sa naňho odkazuje, zapíšete jedným volaním – Flexi ich spracuje v poradí.
Filtrovať sa dá aj podľa poľa odkazovaného záznamu, napr. dobropisy cez typDokl.typDoklK = 'typDokladu.dobropis'.
Zápis do 120 evidencií ABRA oficiálne nedokumentuje, hoci funguje. V dokumentácii sú preto označené, aby ste si ich pred nasadením overili.

Ako dokumentáciu používať

Analytik

Otvorte katalóg a vyhľadajte evidenciu alebo pole – napr. objednávka alebo splatnosť.
V detaile evidencie zistíte typ poľa, či je povinné, aké hodnoty môže mať a na ktorú evidenciu odkazuje.
Tlačidlo Ukážka dát z demo servera ukáže skutočné záznamy – rýchla predstava, čo v evidencii je.

Programátor

V Swagger UI zvoľte modul a evidenciu.
Pri operácii kliknite na Try it out a Execute – požiadavka ide na demo server. Pod ňou nájdete aj hotový príkaz curl.
Pre vlastný server prepnite v zozname Servers na „Váš server ABRA Flexi“ a cez Authorize zadajte meno a heslo. (Váš server musí povoľovať volania z prehliadača; inak použite curl alebo Postman.)

Postman a generovanie klienta

V Postmane zvoľte Import a zadajte adresu súboru, napr. https://nva.sk/abra-flexi-api/openapi/abra-flexi-predaj.json. Klienta vygenerujete napríklad nástrojom openapi-generator:

npx @openapitools/openapi-generator-cli generate \
  -i https://nva.sk/abra-flexi-api/openapi/abra-flexi-predaj.json \
  -g php -o abra-flexi-klient

Obmedzenia

Ide o neoficiálnu dokumentáciu. Pri rozporoch má prednosť oficiálna dokumentácia ABRA a správanie vášho servera.
Štruktúra je z demo servera vo verzii 2026.5.5. Vaša firma môže mať používateľské polia a iné typy dokladov – aktuálny popis vráti /{evidencia}/properties.json na vašom serveri.
Príklady zápisu sú overené cez dry-run. Popis niektorých služieb (webhooky, prihlásenie cez session) vychádza z oficiálnej dokumentácie – na verejnom demo serveri sme ich nemohli overiť zápisom.