API és webhookok

Hol találod

Ha az irodádban a dokumentumok nem a DocuTractban születnek, az a rendszer közvetlenül is kommunikálhat velünk. Nyisd meg a jobb felső sarokban az e-mail-címeddel jelölt menüt, és válaszd az Integrációk pontot: itt adhatsz ki tokent, amellyel a rendszered minket hív, és itt adhatod meg a címet, ahová a kész dokumentumokról értesítést küldünk.

A képernyő a kész CRM-kapcsolatokkal kezdődik (CRM-integrációk); az itt leírt tokenek és webhookok alattuk, az API és webhookok szakaszban vannak.

A token

Kattints a Token létrehozása gombra, adj neki olyan nevet, amelyet később felismersz (hogy tudd, melyik rendszer használja), és jelöld be, mit tehet: sablonokat olvashat, dokumentumokat hozhat létre, ügyekkel dolgozhat.

Magát a tokent egyszer mutatjuk meg, közvetlenül a létrehozása után: csak a hash-ét tároljuk, így másodszor még mi sem tudnánk megmutatni. Másold be azonnal a rendszered beállításaiba.

A lista mutatja az egyes tokenek első karaktereit, azt, hogy mit tehetnek, és mikor használták őket utoljára. A Visszavonás azonnal kikapcsolja a tokent; a nyilvántartás megmarad róla, így látható, hogy létezett, és mikor szűnt meg működni.

Mit tud az API

A rendszered:

• megnyithat egy ügyet, és szkeneket tölthet fel bele;
• létrehozhat egy dokumentumot egy sablonból a már kitöltött értékekkel;
• lekérdezheti, melyik szakaszban tart egy dokumentum;
• lekérheti az összes értéket azzal a szkennel együtt, amelyből az egyes értékeket kiolvastuk;
• rövid élettartamú linket kaphat a kész fájlhoz.

Minden cím és mező teljes leírása magából a kódból generálódik, és nyilvánosan elérhető: az API leírása.

Webhookok

Ahelyett, hogy megkérdeznéd tőlünk, kész-e egy dokumentum, adj meg egy címet, és mi írunk neked. Add hozzá a Webhookok résznél, és jelöld be az eseményeket: elkészült a dokumentum, nem sikerült a dokumentum, elkészült az ügy, eltérést találtunk, egy ügyfél fájlt küldött.

Minden kérést az X-DocuTract-Signature fejléc ír alá, és az aláírást ellenőrző titkos kulcsot a tokenhez hasonlóan egyszer mutatjuk meg. A rendszerednek ellenőriznie kell az aláírást, és 2xx kóddal kell válaszolnia. Ha bármi mással válaszol, vagy egyáltalán nem válaszol, újrapróbálkozunk: egy perc, öt perc, fél óra, két óra és tíz óra múlva, aztán abbahagyjuk.

Ha valami nem érkezett meg

A Kézbesítések gomb megmutatja a naplót: melyik eseményt küldtük, mikor, hányszor, milyen válaszkód jött vissza, és a válasz törzsének elejét. Ez a válasz arra, hogy „a rendszerünk semmit sem kapott”: írásban ott áll, hogy 14:12-kor négyszer 500-zal válaszolt.

A Teszt küldése azonnal küld egy ping kérést a címre, valódi eseményre várás nélkül, így a fogadó oldal még azelőtt beállítható, hogy bármilyen munka átmenne rajta. A sikertelen kézbesítés melletti Újra gomb azonnal még egy kísérletet tesz.

Zapier, Make és n8n

A no-code platformok (olyan szolgáltatások, ahol programozás nélkül raknak össze integrációt) maguk iratkoznak fel az eseményeinkre az API REST hooks részén keresztül, így senkinek sem kell a címeiket a DocuTractba másolnia. Adj a platformnak egy tokent a webhooks:read és webhooks:write jogosultsággal, valamint azokkal, amelyekre a műveleteinek szüksége van (például templates:read és documents:write).

• A POST /api/v1/hooks a {"event": "document.ready", "target_url": "https://…"} tartalommal feliratkoztat egy címet egy eseményre. A válasz tartalmazza a feliratkozás id értékét és egyszer az aláíráshoz szükséges secret értékét.
• A GET /api/v1/hooks felsorolja az így létrehozott feliratkozásokat; a DELETE /api/v1/hooks/{id} töröl egyet.
• A GET /api/v1/hooks/events felsorolja az eseményeket: document.ready, document.failed, case.ready, finding.raised, intake.uploaded.
• A GET /api/v1/hooks/samples/{event} mintatartalmat ad vissza, amelyet a platform a „teszt triggerében” mutat meg, még mielőtt valódi esemény történt volna.

A feliratkozás közönséges webhookcím: ugyanúgy aláírjuk, újrapróbáljuk és naplózzuk, és látható a Webhookok listában. Megszűnik, ha az azt létrehozó tokent visszavonják vagy lejár, illetve ha a platform egy kézbesítésre 410 Gone kóddal válaszol.

Így néz ki a 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"
}

és így a 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"
}

Egy sablon mezői

A GET /api/v1/templates/{id}/fields (jogosultság: templates:read) felsorolja, mire van szüksége egy sablonnak: minden mező key értékét (ezzel kulcsolódnak a values a POST /api/v1/documents hívásban), a label értékét, hogy honnan töltődik ki, valamint a fillable értékét, amely false az olyan mezőnél, amelyet a DocuTract maga tölt ki, például egy dátumnál. A Zapier vagy a Make űrlapja ebből a listából épül fel, így mindig a sablon aktuális állapotának felel meg.

Lekérdezések

Néhány hívás azért létezik, hogy egy rendszer vagy no-code platform találgatás nélkül megtalálja, amire szüksége van:

• GET /api/v1/me (jogosultság nélkül) visszaadja a munkaterületet, amelyhez a token tartozik, a csomagját, valamint magának a tokennek a nevét és jogosultságait. Ez a legegyszerűbb módja annak, hogy ellenőrizd, működik-e egy token.
• GET /api/v1/documents (jogosultság: documents:read) a legújabb dokumentumokat mutatja előre. Szűkítheted reference (a pontos DOC-… azonosító), status vagy template_id paraméterrel; a limit legfeljebb 100, alapértelmezetten 25.
• GET /api/v1/cases (jogosultság: cases:read) a legújabb ügyeket mutatja, igény szerint csak egy adott status szerint, ugyanazzal a limit-tel. Minden ügy most már a created_at mezőt is tartalmazza.
• GET /api/v1/case-types (jogosultság: cases:read) felsorolja az ügytípusokat, amelyekből ügy nyitható.
• GET /api/v1/templates?name=… csak azokat a sablonokat hagyja meg, amelyek neve tartalmazza a szöveget, kis- és nagybetűtől függetlenül.

Lapozás szándékosan nincs: ezek a listák a legfrissebb elemek megtalálására valók, nem egy teljes munkaterület exportálására.

Melyik díjcsomag

Az API és a webhookok a Team díjcsomag részei. Bármely más díjcsomagban a már létrehozott tokenek és címek láthatók maradnak, és visszavonhatók, de újakat nem adunk ki, és a tokennel indított hívásokat már nem szolgáljuk ki. Hasonlítsd össze a díjcsomagokat az árak oldalán.