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.
O každém novém klíči přijde vlastníkovi účtu e-mail, stejně jako dva týdny předtím, než klíč vyprší. Viz Upozornění e-mailem a do Telegramu.
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, štítky, 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.
Štítky se posílají podle jména, chybějící se založí. U POST /api/upload jako
samostatné pole tags za každý štítek (-F tags=doprava -F tags=nafta); čárkou oddělený
seznam se nebere, protože čárka smí být v názvu. U POST /api/upload/url jako pole
v JSON, "tags": ["doprava", "nafta"]. Nejvýš deset štítků po čtyřiceti znacích; víc
skončí chybou 400 ERR_UPLOAD_TOO_MANY_TAGS nebo ERR_TAG_NAME_TOO_LONG dřív, než se
cokoliv strhne nebo stáhne.
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á.
Bezpečné opakování nahrání
Když spojení spadne dřív, než přijde odpověď, nevíte, jestli doklad vznikl. Pošlete
proto s nahráním hlavičku Idempotency-Key s vlastní jedinečnou hodnotou, třeba UUID.
Přijde-li stejný požadavek se stejným klíčem znovu do 24 hodin, dostane odpověď prvního
pokusu s hlavičkou Idempotent-Replayed: true. Druhý doklad nevznikne a kredity se
nestrhnou podruhé, i když máte vypnutou kontrolu duplicit. Platí pro POST /api/upload
i POST /api/upload/url; u adresy se soubor při opakování znovu nestahuje.
V Zapieru nebo Make se do klíče hodí id záznamu, ze kterého nahráváte, třeba id přílohy mailu. Opakovaný běh téhož kroku pak doklad nezaloží znovu.
- Každé nahrání potřebuje vlastní klíč. Stejný klíč s jiným souborem nebo jinými
volbami skončí chybou 422
ERR_IDEMPOTENCY_KEY_REUSED. - Opakování během zpracování prvního pokusu dostane 409
ERR_IDEMPOTENCY_KEY_IN_PROGRESS. Zkuste to za chvíli znovu. - Odmítnutí se nepamatuje. Když první pokus skončí chybou 400, třeba pro nedostatek kreditů, opakování se stejným klíčem se zpracuje znovu.
- Klíč platí ve vašem účtu 24 hodin od prvního pokusu. Je to text do 255 znaků
bez diakritiky; jiný tvar skončí chybou 400
ERR_INVALID_IDEMPOTENCY_KEY.
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í.
Když webhook nedojde ani po všech pokusech, zhruba za čtyři a půl hodiny, přijde e-mail. Během jednoho výpadku jen jednou, další selhání jsou v aktivitě. E-mail přijde i po každé změně adresy webhooku, kdyby ji změnil někdo jiný než vy.
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.