ABRA Flexi REST API – prehľadná dokumentácia

Rýchly štart

ABRA Flexi má REST API zabudované – nič neinštalujete. Každá evidencia (faktúry, adresár, cenník…) má vlastnú adresu a dáta vracia v JSON, XML, CSV či PDF. Na vyskúšanie stačí verejný demo server, ktorý nevyžaduje prihlásenie:

curl "https://demo.flexibee.eu/c/demo/adresar.json?limit=3&detail=custom:kod,nazev,ic"

Odpoveď má vždy obálku winstrom a v nej pole záznamov pomenované podľa evidencie:

{
  "winstrom": {
    "@version": "1.0",
    "adresar": [
      { "id": "660", "kod": "ZAK-4567", "nazev": "Vzorová firma, s. r. o.", "ic": "12345678" },
      { "id": "661", "kod": "DODAVATEL-12", "nazev": "Tlačiareň, a. s.", "ic": "87654321" }
    ]
  }
}

Na vlastnom serveri pridáte meno a heslo používateľa Flexi:

curl -u "api_uzivatel:heslo" \
  "https://vasa-firma.flexibee.eu:5434/c/vasa_firma/faktura-vydana.json?limit=5"

Adresa a štruktúra URL

API je pod cestou /c/. Novšie verzie Flexi majú webové rozhranie pod /flexi/ – na integrácie však používajte /c/. Za cestu ktorejkoľvek evidencie môžete pridať /properties.json a Flexi vráti popis všetkých jej polí. Z tohto zdroja je vygenerovaná aj táto dokumentácia.

Prihlásenie

HTTP Basic – meno a heslo v každej požiadavke. Najjednoduchšie a pre integrácie úplne postačujúce:

curl -u "api_uzivatel:heslo" "https://{server}/c/{firma}/adresar.json"

Session – pri veľkom počte požiadaviek sa môžete prihlásiť raz a posielať session ID:

Parametre username a password pošlite ako formulár. Z odpovede si uložte authSessionId a posielajte ho v hlavičke X-authSessionId.

Formáty a hodnoty

Formát určuje prípona v URL: .json a .xml pre integrácie, .csv a .xlsx pre exporty, .pdf pre tlačové zostavy a .isdoc pre elektronické faktúry. V JSON platí niekoľko pravidiel, ktoré prekvapia každého, kto s Flexi začína:

• Všetky hodnoty sú reťazce – aj čísla a logické hodnoty: "sumCelkem": "121.0", "storno": "false". Pri zápise Flexi prijme aj JSON čísla a true/false.
• Dátumy obsahujú časové pásmo: "datVyst": "2026-09-30+02:00". Pri zápise stačí "2026-09-30".
• Väzby sa vracajú ako identifikátor a dve pomocné polia – odkaz a čitateľný popis:

  "firma": "code:ZAK-4567",
  "firma@ref": "/c/vasa_firma/adresar/660.json",
  "firma@showAs": "ZAK-4567: Vzorová firma, s. r. o."

• Výbery z číselníka majú kľúč a popis: "stavUhrK": "stavUhr.uhrazeno" + "stavUhrK@showAs": "Uhrazeno". Vo filtroch aj pri zápise používajte kľúč.
• Názvy polí a hodnoty sú české (nazev, mesto, datSplat) – presne tak, ako ich definuje ABRA. Katalóg ich ku každému poľu vysvetľuje.

Identifikátory záznamov

Záznam nemusíte identifikovať len interným číslom. Flexi rozumie viacerým identifikátorom – v URL aj v tele požiadavky:

Pri čítaní cez code: alebo ext: Flexi vráti presmerovanie (301) na adresu s interným ID – HTTP klient musí presmerovania nasledovať (v curl prepínač -L). Záznam môže mať pri zápise aj viac identifikátorov naraz: "id": ["ext:ESHOP:4567", "code:ZAK-4567"].

Čítanie a stránkovanie

Stránkovanie veľkej evidencie – sťahujte po dávkach, kým nedostanete menej záznamov, než je limit:

GET /c/{firma}/faktura-vydana.json?detail=custom:id,kod,sumCelkem&order=id@A&limit=500&start=0
GET /c/{firma}/faktura-vydana.json?detail=custom:id,kod,sumCelkem&order=id@A&limit=500&start=500
…

Pri stránkovaní vždy zoraďte podľa stabilného poľa (napr. id), inak sa môžu záznamy medzi stránkami posunúť.

Filtre

Filter sa zapisuje do URL za evidenciu v okrúhlych zátvorkách. Textové a dátumové hodnoty dávajte do apostrofov:

GET /c/{firma}/faktura-vydana/(datSplat < now() and zbyvaUhradit > 0).json

V URL treba medzery a špeciálne znaky zakódovať (%20 namiesto medzery, %3E namiesto >) – väčšina HTTP knižníc to urobí sama. Dlhý filter, napríklad kod in (…) so stovkami hodnôt, pošlite radšej v tele požiadavky:

{
  "winstrom": {
    "@version": "1.0",
    "filter": "lastUpdate >= '2026-09-01T00:00:00' and ic is not empty",
    "detail": "custom:kod,nazev,ic,email",
    "order": "nazev@A",
    "limit": 1000,
    "no-ext-ids": true
  }
}

Vnorené dáta a väzby

Faktúra bez položiek či objednávka bez zákazníka je pre integráciu málo. Súvisiace dáta dostanete tromi spôsobmi:

1. Vnorená kolekcia (relations) – položky dokladu priamo v odpovedi:

GET /c/{firma}/faktura-vydana/(datVyst >= '2026-09-01').json
    ?detail=custom:kod,datVyst,sumCelkem,polozkyFaktury(nazev,mnozMj,cenaMj)
    &relations=polozkyFaktury

2. Vložený odkazovaný záznam (includes) – napr. IČO odberateľa priamo vo faktúre:

GET /c/{firma}/faktura-vydana/123.json
    ?detail=custom:kod,firma(nazev,ic,dic)
    &includes=/faktura-vydana/firma

3. Samostatná adresa väzby – napr. prílohy alebo úhrady (väzobné doklady) faktúry:

GET /c/{firma}/faktura-vydana/123/prilohy.json
GET /c/{firma}/faktura-vydana/123/vazebni-doklady.json

Zoznam väzieb a vnorených kolekcií každej evidencie je v katalógu a vo Swagger UI pri operácii „Súvisiace záznamy“.

Zápis: vytvorenie a úprava

Zápis je „import“: pošlete záznamy v obálke winstrom na adresu evidencie. Flexi sám rozhodne, či záznam vytvorí, alebo aktualizuje – podľa identifikátora v poli id.

{
  "winstrom": {
    "@version": "1.0",
    "faktura-vydana": [
      {
        "id": "ext:ESHOP:FV-2026-001234",
        "typDokl": "code:FAKTURA",
        "firma": "code:ZAK-4567",
        "datVyst": "2026-09-30",
        "datSplat": "2026-10-14",
        "varSym": "2026001234",
        "mena": "code:EUR",
        "formaUhradyCis": "code:PREVOD",
        "stitky": "ESHOP",
        "polozkyFaktury": [
          { "typPolozkyK": "typPolozky.katalog", "cenik": "code:9788000000000",
            "mnozMj": "2", "cenaMj": "12.90",
            "typCenyDphK": "typCeny.sDph", "typSzbDphK": "typSzbDph.dphSniz" },
          { "typPolozkyK": "typPolozky.obecny", "nazev": "Doprava – kuriér",
            "mnozMj": "1", "cenaMj": "3.90",
            "typCenyDphK": "typCeny.sDph", "typSzbDphK": "typSzbDph.dphZakl" }
        ]
      }
    ]
  }
}

• Väzby (typDokl, firma, mena, cenik…) zadávate identifikátorom – najčastejšie code:. Kódy typov dokladov, foriem úhrady či skladov sú v každej firme iné; zistíte ich napr. cez GET /typ-faktury-vydane.json.
• Čo nepošlete, to Flexi doplní z typu dokladu a nastavení – číslo dokladu z dokladovej rady, splatnosť, účtovanie, adresu odberateľa z adresára.
• V jednej požiadavke môže byť viac záznamov aj viac evidencií. Flexi ich spracuje v poradí, takže objednávka sa môže odkazovať na zákazníka, ktorého zakladáte o riadok vyššie (príklad).
• Úpravu urobíte rovnakým volaním s identifikátorom existujúceho záznamu – stačí poslať len menené polia. Prípadne PUT /{evidencia}/{id}.json.
• Štítky (stitky) oddeľujte čiarkou. Musia vo Flexi existovať, inak zápis skončí chybou.

Správanie pri existujúcom a novom zázname riadia atribúty @update a @create s hodnotami ok, ignore a fail. Napríklad "@update": "ignore" založí firmu, len ak ešte neexistuje – existujúcu preskočí.

Položky dokladov a vnorené kolekcie

Položky sa nezapisujú samostatne, ale vnorene v doklade. Názov kolekcie závisí od evidencie:

Faktúry, objednávky, bankové, pokladničné a skladové doklady prijímajú aj univerzálny názov polozkyDokladu. Typ položky určuje typPolozkyK: typPolozky.katalog (z cenníka – vyplňte cenik), typPolozky.obecny (voľný text s cenou), typPolozky.ucetni a typPolozky.text. Cena je s DPH alebo bez podľa typCenyDphK, sadzbu určuje typSzbDphK.

Pri úprave dokladu sa odoslané položky pridajú k existujúcim. Ak chcete položky nahradiť, pridajte "polozkyFaktury@removeAll": true. Jednu položku zmažete jej ID a akciou: {"id": "85930", "@action": "delete"}.

Akcie, storno a mazanie

Akcie sa spúšťajú pri zápise atribútom @action. Najčastejšia je storno dokladu – doklad zostane v evidencii, ale prestane sa počítať:

{ "winstrom": { "@version": "1.0",
  "faktura-vydana": [ { "id": "ext:ESHOP:FV-2026-001234", "@action": "storno" } ] } }

Ďalšie akcie závisia od evidencie – napr. pri faktúrach sign-for-payment (podpísať na úhradu), uhrad-zapoctem alebo odeslani-mailem. Zoznam je pri každej evidencii v katalógu. Dobropis prepojíte s pôvodnou faktúrou vnoreným objektom "vytvor-vazbu-dobropis": {"dobropisovanyDokl": "code:FV-2026-001234"}.

Mazanie cez DELETE /{evidencia}/{id}.json (alebo "@action": "delete") je nevratné a nepodarí sa, ak sa na záznam odkazujú iné záznamy. Účtovné doklady preto radšej stornujte. Bankové pohyby s neuhradenými dokladmi spárujete automaticky volaním POST /banka/automaticke-parovani.json.

Odpovede a chyby

Každý zápis vráti štatistiku a výsledok pre každý záznam:

{
  "winstrom": {
    "@version": "1.0",
    "success": "true",
    "stats": { "created": "1", "updated": "0", "deleted": "0", "skipped": "0", "failed": "0" },
    "results": [
      { "id": "40125", "request-id": "ext:ESHOP:FV-2026-001234",
        "ref": "/c/vasa_firma/faktura-vydana/40125.json" }
    ]
  }
}

Pri chybe je success "false", HTTP kód 400 a pri zázname pole errors:

{ "message": "Zadaný text 'code:NEEXISTUJE' musí identifikovat objekt …",
  "for": "typDokl", "value": "code:NEEXISTUJE",
  "code": "PROP", "messageCode": "notObjectIdentifier" }

Na spracovanie v programe používajte messageCode – text chyby je v češtine a môže sa meniť. Najčastejšie chyby:

HTTP kódy: 200/201 úspech, 400 chybná požiadavka alebo zápis, 401 neplatné prihlásenie, 402 chýbajúca licencia modulu, 403 chýbajúce oprávnenie, 404 neexistujúci záznam či adresa.

Synchronizácia zmien a webhooky

Na pravidelné sťahovanie zmien máte dve možnosti. Jednoduchšia je filter na čas poslednej zmeny:

GET /c/{firma}/faktura-vydana/(lastUpdate >= '2026-09-30T08:00:00').json?detail=custom:id,kod,stavUhrK

Spoľahlivejšie je changes API, ktoré zachytí aj zmazané záznamy. Administrátor ho raz zapne (PUT /changes/enable.json) a potom si stačí pamätať poslednú verziu:

GET /c/{firma}/changes.json?start=967025&limit=1000

{ "winstrom": { "@globalVersion": "967030", "next": "967031",
  "changes": [ { "@evidence": "faktura-vydana", "@operation": "update",
                 "@in-version": "967026", "id": "40125",
                 "external-ids": ["ext:ESHOP:FV-2026-001234"] } ] } }

Hodnotu next pošlite pri ďalšom volaní ako start. Ak nechcete Flexi pravidelne kontrolovať, zaregistrujte webhook (PUT /hooks.json?url=…&format=JSON) – Flexi bude zmeny posielať na vašu adresu sám.

PDF, prílohy a súčty

• PDF dokladu: GET /faktura-vydana/123.pdf?report-name=…&report-lang=sk. PDF nájdete aj podľa čísla: /faktura-vydana/(kod = 'FV-2026-001234').pdf. Zoznam tlačových zostáv vráti /faktura-vydana/reports.json.
• Prílohy: zoznam cez /faktura-prijata/123/prilohy.json, obsah súboru cez /priloha/{id}/content. Nahrávanie: PUT /zavazek/123/prilohy/new/zmluva.pdf so súborom v tele a hlavičkou Content-Type.
• Súčty: GET /faktura-vydana/(datVyst >= '2026-01-01')/$sum.json vráti súčty (celkom, uhradené, zostáva) za vyfiltrované doklady.
• Exporty: rovnaké URL s príponou .xlsx alebo .csv vráti tabuľku – napr. na rýchly export pre účtovníčku.

Príklady z praxe: e-shop a ABRA Flexi

Nasledujúce scenáre pochádzajú z reálnej integrácie e-shopu a interného informačného systému s ABRA Flexi. Kompletné telá požiadaviek nájdete vo Swagger UI pri operácii Vytvoriť alebo aktualizovať záznamy (rozbaľovací zoznam Examples).

Z prevádzky takejto integrácie sa osvedčilo:

• Fronta s opakovaním. Požiadavky na zápis ukladajte do fronty a pri dočasnej chybe ich zopakujte (napr. najviac 5-krát). Trvalé chyby (tabuľka vyššie) neopakujte, ale nahláste.
• Denný limit volaní na strane integrácie chráni Flexi pred zahltením pri chybe v kóde.
• Log požiadaviek a odpovedí – pri reklamácii „faktúra sa neprepísala“ je to jediný spôsob, ako rýchlo nájsť príčinu.
• Externé ID všade, kde záznam vzniká vo vašom systéme. Odpadne hľadanie interného ID pred každou úpravou.

Tipy a časté chyby

• Dostávam len 20 záznamov. Predvolený limit je 20 – nastavte vlastný alebo stránkujte.
• Odpoveď je pomalá. Použite detail=custom:… len s poliami, ktoré potrebujete, a no-ext-ids=true.
• Čísla neviem sčítať. Hodnoty sú reťazce – pred výpočtom ich prekonvertujte.
• Požiadavka s code: vracia 301. Zapnite v HTTP klientovi nasledovanie presmerovaní.
• Pri úprave sa zdvojili položky. Chýba polozkyFaktury@removeAll.
• Dátumy sú posunuté o deň. Pri prevode na UTC nezabudnite na časové pásmo +02:00/+01:00.
• Testujte na kópii firmy alebo s dry-run=true – nie na ostrých dátach.

O dokumentácii

Toto je neoficiálna dokumentácia, ktorú pripravila spoločnosť NextVision Analytics. Štruktúra evidencií, polí, väzieb, akcií a tlačových zostáv je vygenerovaná priamo z metadát ABRA Flexi 2026.5.5 (verejný demo server, 30. 9. 2026). Príklady zápisu vychádzajú z reálnych integrácií a sú overené na demo serveri. Ako dokumentácia vznikla, popisujeme v článku na blogu.

Vaša firma môže mať iné nastavenia, typy dokladov a používateľské polia – aktuálny popis vašich evidencií vráti vždy /{evidencia}/properties.json na vašom serveri. Oficiálnu dokumentáciu nájdete na flexibee.eu/api/dokumentace. ABRA Flexi je produkt spoločnosti ABRA Software a. s.