API a webhooky
Nahrávání a čtení dokladů je dostupné přes REST API. Správa účtu, šanonů, štítků a propojení zůstává v aplikaci.
Klíč
Zakládá se v Nastavení → Pro vývojáře. Klíč se ukáže jednou, při založení — potom už ne, protože se ukládá jen jeho otisk. Ztracený klíč se neobnovuje, zakládá se nový a starý se smaže. Klíčů jde mít pět, každý s volitelnou dobou platnosti do dvou let.
Klíč se posílá v hlavičce X-API-Key.
Co API umí
| Operace | Popis |
|---|---|
POST /api/upload | Nahrání souboru s volbami: formát, směr, druh, měna, schéma, šanon, webhook |
POST /api/upload/url | Totéž z veřejné adresy; stáhneme si soubor sami |
GET /api/jobs | Výpis dokladů s filtry a stránkováním |
GET /api/jobs/{id} | Stav, přečtená data, nálezy a výsledek v cílovém formátu |
GET /api/jobs/{id}/original | Nahraný soubor |
DELETE /api/jobs/{id} | Smazání do koše |
Excel a PDF chodí ve výsledku jako Base64. Kdo výsledek nepotřebuje, pošle
includeResult=false, ušetří tím převod na serveru.
Popis rozhraní ve formátu OpenAPI je na adrese /api/docs; odkaz je v nastavení
u klíčů. Popis se generuje z běžícího kódu, takže odpovídá tomu, co API dělá.
Kontrola u dokladů z API
Kontrola před odesláním platí ve výchozím nastavení i pro doklady nahrané klíčem: doklad čeká na potvrzení v aplikaci a webhook odejde až po něm. Kdo staví integraci, u které nikdo nesedí u obrazovky, si v Nastavení → Kontrola před odesláním odebere kanál API, nebo kontrolu vypne.
MCP
Pro AI agenty je na adrese /api/mcp server MCP se stejným klíčem. Umí doklady
číst a vyhledávat, nahrávat ne; nahrání vrátí jako hotový příkaz, který si agent
spustí sám.
Webhooky
Místo dotazování na stav si nechte poslat výsledek, až bude hotovo. Adresa se
nastavuje pro celý účet v Nastavení → Pro vývojáře, nebo u jednotlivého nahrání
parametrem targetWebhookUrl. Tlačítko v nastavení pošle testovací zprávu.
Pošle se POST s JSON: identifikátor dokladu, název souboru, formát a výsledek
v cílovém formátu. Když doklad projde kontrolou nebo se zpracuje znovu, přijde
webhook podruhé s příznakem opravy (IsCorrection).
Zpráva se nepodepisuje. Ověřte si odesílatele tím, že do adresy dáte vlastní tajný token. Adresy do privátních sítí se odmítají.
Neúspěšné doručení se opakuje s rostoucí prodlevou, jedenáct pokusů během zhruba čtyř a půl hodiny. Každý pokus je v aktivitě i s odpovědí vaší strany; u dokladu ve výpisu je ikona s výsledkem doručení.
Limity
API nemá vlastní strop na počet volání za minutu; nahrávání omezují kredity, velikost souboru podle tarifu a dvacet stran na doklad. Odmítnutí přijde jako chyba 400 s kódem, který říká proč. Server MCP je omezený na deset dotazů za vteřinu.