API a webhooky

Kde to nájdete

Ak dokumenty vo vašej kancelárii vznikajú inde ako v DocuTract, tento systém môže komunikovať priamo s nami. Otvorte menu s vašou adresou v pravom hornom rohu a vyberte Integrácie: tam sa vydáva token, s ktorým nás bude váš systém volať, a tam pridáte adresu, na ktorú mu budeme oznamovať hotové dokumenty.

Obrazovka sa začína hotovými prepojeniami s CRM (Integrácie s CRM); tokeny a webhooky opísané tu sú pod nimi, v oddiele API a webhooky.

Token

Kliknite na Vytvoriť token, dajte mu názov, ktorý neskôr spoznáte (aby ste vedeli, ktorý systém ho používa), a označte, čo smie robiť: čítať šablóny, vytvárať dokumenty, pracovať s prípadmi.

Samotný token sa zobrazí raz, hneď po vytvorení: ukladáme len jeho hash, takže zobraziť ho druhýkrát nedokážeme ani my. Skopírujte ho rovno do nastavení svojho systému.

Zoznam ukazuje prvé znaky každého tokenu, čo smie robiť a kedy bol naposledy použitý. Zrušiť token okamžite vypne; záznam o ňom zostane, takže je vidieť, že existoval a kedy prestal fungovať.

Čo API dokáže

Váš systém môže:

• otvoriť prípad a nahrať do neho skeny;
• vytvoriť dokument zo šablóny s už vyplnenými hodnotami;
• zistiť, v akej fáze je dokument;
• prevziať všetky hodnoty spolu so skenom, z ktorého sa každá prečítala;
• získať krátkodobý odkaz na hotový súbor.

Úplný popis každej adresy a poľa sa generuje priamo z kódu a je verejne zverejnený: popis API.

Webhooky

Namiesto toho, aby ste sa nás pýtali, či je dokument hotový, dajte nám adresu a my vám napíšeme. Pridajte ju v časti Webhooky a označte udalosti: dokument hotový, dokument zlyhal, prípad hotový, nájdená nezhoda, klient poslal súbor.

Každá požiadavka je podpísaná hlavičkou X-DocuTract-Signature a tajný kľúč, ktorým sa podpis overuje, sa zobrazí raz, rovnako ako token. Váš systém musí podpis skontrolovať a odpovedať kódom 2xx. Ak odpovie čímkoľvek iným alebo neodpovie vôbec, skúsime to znova: po minúte, po piatich, po pol hodine, po dvoch a po desiatich hodinách, a potom prestaneme.

Keď niečo neprišlo

Tlačidlo Doručenia ukáže záznam: ktorú udalosť sme poslali, kedy, koľkokrát, aký kód odpovede prišiel späť a začiatok tela odpovede. To je odpoveď na „náš systém nič nedostal“: je tam čierne na bielom, že o 14:12 štyrikrát odpovedal 500.

Poslať test pošle na adresu ping hneď teraz, bez čakania na skutočnú udalosť, aby sa prijímač dal nastaviť skôr, ako ním prejde akákoľvek práca. Skúsiť znova pri neúspešnom doručení urobí ešte jeden pokus okamžite.

Zapier, Make a n8n

No-code platformy (služby, kde sa integrácia skladá bez programovania) sa na naše udalosti prihlasujú samy, cez časť API pre REST hooky, takže nikto nemusí kopírovať ich adresy do DocuTractu. Dajte platforme token s oprávneniami webhooks:read a webhooks:write a s tými, ktoré potrebujú jej akcie (napríklad templates:read a documents:write).

• POST /api/v1/hooks s {"event": "document.ready", "target_url": "https://…"} prihlási adresu na jednu udalosť. Odpoveď obsahuje id odberu a raz aj jeho secret na podpis.
• GET /api/v1/hooks vypíše takto vytvorené odbery; DELETE /api/v1/hooks/{id} jeden odstráni.
• GET /api/v1/hooks/events vypíše udalosti: document.ready, document.failed, case.ready, finding.raised, intake.uploaded.
• GET /api/v1/hooks/samples/{event} vráti ukážkový obsah, ktorý platforma zobrazí vo svojom „testovacom spúšťači“ ešte pred prvou skutočnou udalosťou.

Odber je obyčajná adresa webhooku: rovnako sa podpisuje, opakuje a zapisuje do denníka a je vidieť v zozname Webhooky. Prestane platiť, keď token, ktorý ho vytvoril, odvoláte alebo vyprší, alebo keď platforma odpovie na doručenie kódom 410 Gone.

Takto vyzerá document.ready:

{
  "document_id": "00000000-0000-4000-8000-000000000001",
  "reference": "DOC-26-0001",
  "template_id": "00000000-0000-4000-8000-000000000002",
  "template_version": 1,
  "event": "document.ready",
  "occurred_at": "2026-01-15T10:30:00+00:00"
}

a takto case.ready:

{
  "case_id": "00000000-0000-4000-8000-000000000003",
  "title": "Sample case",
  "documents": [
    { "id": "00000000-0000-4000-8000-000000000001", "reference": "DOC-26-0001" }
  ],
  "event": "case.ready",
  "occurred_at": "2026-01-15T10:30:00+00:00"
}

Polia šablóny

GET /api/v1/templates/{id}/fields (oprávnenie templates:read) vypíše, čo šablóna potrebuje: key každého poľa (podľa neho sa zadávajú values v POST /api/v1/documents), jeho label, odkiaľ sa vypĺňa, a fillable, ktoré je false pri poli, ktoré DocuTract vypĺňa sám, napríklad dátume. Formulár v Zapieri alebo Make sa stavia z tohto zoznamu, takže vždy zodpovedá šablóne v jej aktuálnej podobe.

Vyhľadávanie

Niekoľko volaní existuje preto, aby systém alebo no-code platforma našli, čo potrebujú, bez hádania:

• GET /api/v1/me (bez oprávnenia) vráti pracovný priestor, ku ktorému token patrí, jeho tarif a názov a oprávnenia samotného tokenu. Je to najjednoduchší spôsob, ako overiť, že token funguje.
• GET /api/v1/documents (oprávnenie documents:read) vypíše dokumenty od najnovších. Zúžiť ho môžete parametrami reference (presné číslo DOC-…), status alebo template_id; limit je najviac 100, predvolene 25.
• GET /api/v1/cases (oprávnenie cases:read) vypíše najnovšie prípady, prípadne len tie s jedným status, s rovnakým limit. Každý prípad má teraz aj pole created_at.
• GET /api/v1/case-types (oprávnenie cases:read) vypíše typy prípadov, z ktorých možno prípad založiť.
• GET /api/v1/templates?name=… ponechá len šablóny, ktorých názov obsahuje daný text, bez ohľadu na veľkosť písmen.

Stránkovanie zámerne chýba: tieto zoznamy slúžia na nájdenie najnovšieho, nie na export celého pracovného priestoru.

Ktorý plán

API a webhooky sú súčasťou plánu Team. V každom inom pláne zostanú tokeny a adresy, ktoré ste už vytvorili, viditeľné a dajú sa zrušiť, no nové sa nevydávajú a volania s tokenom sa už neobsluhujú. Porovnajte plány na stránke s cenníkom.