API a webhooky

Kde to najdete

Pokud dokumenty ve vaší kanceláři vznikají jinde než v DocuTract, může s námi daný systém komunikovat přímo. Otevřete nabídku s vaší adresou v pravém horním rohu a zvolte Integrace: tam se vydává token, se kterým nás bude váš systém volat, a tam přidáte adresu, na kterou mu budeme hlásit hotové dokumenty.

Obrazovka začíná hotovými propojeními s CRM (Integrace s CRM); tokeny a webhooky popsané zde jsou pod nimi, v oddílu API a webhooky.

Token

Klikněte na Vytvořit token, dejte mu název, který později poznáte (abyste věděli, který systém ho používá), a zaškrtněte, co smí dělat: číst šablony, vytvářet dokumenty, pracovat s případy.

Samotný token se zobrazí jednou, hned po vytvoření: ukládáme jen jeho hash, takže zobrazit ho podruhé nedokážeme ani my. Zkopírujte ho rovnou do nastavení svého systému.

Seznam ukazuje první znaky každého tokenu, co smí dělat a kdy byl naposledy použit. Zneplatnit token okamžitě vypne; záznam o něm zůstane, takže je vidět, že existoval a kdy přestal fungovat.

Co umí API

Váš systém může:

• založit případ a nahrát do něj skeny;
• vytvořit dokument ze šablony s již vyplněnými hodnotami;
• zjistit, v jaké fázi se dokument nachází;
• převzít všechny hodnoty spolu se skenem, ze kterého byla každá přečtena;
• získat krátkodobý odkaz na hotový soubor.

Úplný popis každé adresy a pole se generuje přímo z kódu a je veřejně dostupný: popis API.

Webhooky

Místo abyste se nás ptali, zda je dokument hotový, dejte nám adresu a my vám napíšeme. Přidejte ji v sekci Webhooky a zaškrtněte události: dokument hotový, dokument selhal, případ hotový, nalezena nesrovnalost, klient poslal soubor.

Každý požadavek je podepsán hlavičkou X-DocuTract-Signature a tajný klíč, kterým se podpis ověřuje, se zobrazí jednou, stejně jako token. Váš systém musí podpis ověřit a odpovědět kódem 2xx. Pokud odpoví čímkoli jiným nebo neodpoví vůbec, zkusíme to znovu: po minutě, po pěti, po půl hodině, po dvou hodinách a po deseti, a pak přestaneme.

Když něco nedorazilo

Tlačítko Doručení ukazuje protokol: jakou událost jsme poslali, kdy, kolikrát, jaký kód odpovědi se vrátil a začátek těla odpovědi. To je odpověď na „náš systém nic nedostal“: černé na bílém tam stojí, že ve 14:12 čtyřikrát odpověděl 500.

Odeslat test pošle na adresu hned teď ping, bez čekání na skutečnou událost, takže příjemce lze nastavit dřív, než přes něj půjde jakákoli práce. Zkusit znovu u neúspěšného doručení provede ještě jeden pokus okamžitě.

Zapier, Make a n8n

No-code platformy (služby, kde se integrace skládá bez programování) se k našim událostem přihlašují samy, přes část API pro REST hooky, takže nikdo nemusí kopírovat jejich adresy do DocuTractu. Dejte platformě token s oprávněními webhooks:read a webhooks:write a s těmi, které potřebují její akce (například templates:read a documents:write).

• POST /api/v1/hooks s {"event": "document.ready", "target_url": "https://…"} přihlásí adresu k jedné události. Odpověď obsahuje id odběru a jednou i jeho secret pro podpis.
• GET /api/v1/hooks vypíše takto vytvořené odběry; DELETE /api/v1/hooks/{id} jeden odebere.
• GET /api/v1/hooks/events vypíše události: document.ready, document.failed, case.ready, finding.raised, intake.uploaded.
• GET /api/v1/hooks/samples/{event} vrátí ukázkový obsah, který platforma zobrazí ve svém „testovacím spouštěči“ ještě před první skutečnou událostí.

Odběr je obyčejná adresa webhooku: stejně se podepisuje, opakuje a zapisuje do protokolu a je vidět v seznamu Webhooky. Přestane platit, když token, který ho vytvořil, odvoláte nebo vyprší, nebo když platforma odpoví na doručení kódem 410 Gone.

Takto vypadá 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"
}

Pole šablony

GET /api/v1/templates/{id}/fields (oprávnění templates:read) vypíše, co šablona potřebuje: key každého pole (podle něj se zadávají values v POST /api/v1/documents), jeho label, odkud se vyplňuje, a fillable, které je false u pole, jež DocuTract vyplňuje sám, například data. Formulář v Zapieru nebo Make se staví z tohoto seznamu, takže vždy odpovídá šabloně v její aktuální podobě.

Vyhledávání

Několik volání existuje proto, aby systém nebo no-code platforma našly, co potřebují, bez hádání:

• GET /api/v1/me (bez oprávnění) vrátí pracovní prostor, ke kterému token patří, jeho tarif a název a oprávnění samotného tokenu. Je to nejjednodušší způsob, jak ověřit, že token funguje.
• GET /api/v1/documents (oprávnění documents:read) vypíše dokumenty od nejnovějších. Zúžit ho můžete parametry reference (přesné číslo DOC-…), status nebo template_id; limit je nejvýš 100, výchozí 25.
• GET /api/v1/cases (oprávnění cases:read) vypíše nejnovější případy, případně jen ty s jedním status, se stejným limit. Každý případ má nyní i pole created_at.
• GET /api/v1/case-types (oprávnění cases:read) vypíše typy případů, ze kterých lze případ založit.
• GET /api/v1/templates?name=… ponechá jen šablony, jejichž název obsahuje daný text, bez ohledu na velikost písmen.

Stránkování schválně chybí: tyto seznamy slouží k nalezení nejnovějšího, ne k exportu celého pracovního prostoru.

Který tarif

API a webhooky jsou součástí tarifu Team. V jakémkoli jiném tarifu zůstanou tokeny a adresy, které jste už vytvořili, viditelné a lze je zneplatnit, ale nové se nevydávají a volání s tokenem už nejsou obsluhována. Porovnejte tarify na stránce s cenami.