API und Webhooks

Wo Sie es finden

Wenn Dokumente in Ihrem Büro nicht in DocuTract, sondern anderswo entstehen, kann dieses System direkt mit uns sprechen. Öffnen Sie oben rechts das Menü mit Ihrer Adresse und wählen Sie Integrationen: Dort wird ein Token ausgestellt, mit dem Ihr System uns aufruft, und dort fügen Sie die Adresse hinzu, über die wir es über fertige Dokumente informieren.

Der Bildschirm beginnt mit den fertigen CRM-Verbindungen (CRM-Integrationen); die hier beschriebenen Tokens und Webhooks stehen darunter, im Bereich API und Webhooks.

Der Token

Klicken Sie auf Token erstellen, geben Sie ihm einen Namen, den Sie später wiedererkennen (damit Sie wissen, welches System ihn nutzt), und haken Sie an, was er darf: Vorlagen lesen, Dokumente erstellen, mit Vorgängen arbeiten.

Der Token selbst wird einmal angezeigt, direkt nach dem Erstellen: Wir speichern nur einen Hash davon, ihn ein zweites Mal anzuzeigen, können also nicht einmal wir. Kopieren Sie ihn direkt in die Einstellungen Ihres Systems.

Die Liste zeigt die ersten Zeichen jedes Tokens, was er darf und wann er zuletzt verwendet wurde. Widerrufen schaltet einen Token sofort ab; der Eintrag bleibt bestehen, sodass sichtbar ist, dass es ihn gab und wann er aufgehört hat zu funktionieren.

Was die API kann

Ihr System kann:

• einen Vorgang eröffnen und Scans hineinladen;
• ein Dokument aus einer Vorlage mit bereits ausgefüllten Werten erstellen;
• abfragen, in welchem Stadium sich ein Dokument befindet;
• alle Werte zusammen mit dem Scan abrufen, aus dem jeder gelesen wurde;
• einen kurzlebigen Link zur fertigen Datei erhalten.

Die vollständige Beschreibung aller Adressen und Felder wird direkt aus dem Code erzeugt und offen veröffentlicht: die API-Beschreibung.

Webhooks

Statt uns zu fragen, ob ein Dokument fertig ist, geben Sie uns eine Adresse, und wir schreiben Ihnen. Fügen Sie sie unter Webhooks hinzu und haken Sie die Ereignisse an: Dokument fertig, Dokument fehlgeschlagen, Vorgang fertig, eine Abweichung gefunden, ein Kunde hat eine Datei gesendet.

Jede Anfrage ist mit dem Header X-DocuTract-Signature signiert, und das Secret zur Prüfung der Signatur wird wie der Token nur einmal angezeigt. Ihr System muss die Signatur prüfen und mit einem 2xx-Code antworten. Antwortet es anders oder gar nicht, versuchen wir es erneut: nach einer Minute, nach fünf, nach einer halben Stunde, nach zwei Stunden und nach zehn, und dann hören wir auf.

Wenn etwas nicht angekommen ist

Die Schaltfläche Zustellungen zeigt das Protokoll: welches Ereignis wir wann und wie oft gesendet haben, welcher Antwortcode zurückkam und der Anfang des Antworttexts. Das ist die Antwort auf „Unser System hat nichts erhalten“: Dort steht schwarz auf weiß, dass es um 14:12 viermal mit 500 geantwortet hat.

Test senden schickt sofort ein ping an die Adresse, ohne auf ein echtes Ereignis zu warten, damit ein Empfänger eingerichtet werden kann, bevor echte Arbeit darüber läuft. Erneut versuchen neben einer fehlgeschlagenen Zustellung unternimmt sofort einen weiteren Versuch.

Zapier, Make und n8n

No-Code-Plattformen (Dienste, in denen man Integrationen ohne Programmieren baut) abonnieren unsere Ereignisse selbst, über den REST-Hooks-Teil der API, sodass niemand ihre Adressen in DocuTract kopieren muss. Geben Sie der Plattform einen Token mit den Berechtigungen webhooks:read und webhooks:write sowie denen, die ihre Aktionen brauchen (zum Beispiel templates:read und documents:write).

• POST /api/v1/hooks mit {"event": "document.ready", "target_url": "https://…"} abonniert eine Adresse für ein Ereignis. Die Antwort enthält die id des Abonnements und, einmalig, sein Signatur-secret.
• GET /api/v1/hooks listet die so angelegten Abonnements; DELETE /api/v1/hooks/{id} entfernt eines.
• GET /api/v1/hooks/events listet die Ereignisse: document.ready, document.failed, case.ready, finding.raised, intake.uploaded.
• GET /api/v1/hooks/samples/{event} liefert ein Beispiel des Inhalts, das die Plattform in ihrem „Test-Trigger“ zeigt, noch bevor ein echtes Ereignis eingetreten ist.

Ein Abonnement ist eine gewöhnliche Webhook-Adresse: genauso signiert, wiederholt und protokolliert und in der Liste unter Webhooks sichtbar. Es endet, wenn der Token, der es angelegt hat, widerrufen wird oder abläuft, oder wenn die Plattform eine Zustellung mit 410 Gone beantwortet.

So sieht document.ready aus:

{
  "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"
}

und so 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"
}

Die Felder einer Vorlage

GET /api/v1/templates/{id}/fields (Berechtigung templates:read) listet, was eine Vorlage braucht: den key jedes Feldes (danach richten sich die values in POST /api/v1/documents), sein label, woher es gefüllt wird, und fillable, das false ist für ein Feld, das DocuTract selbst füllt, etwa ein Datum. Ein Formular in Zapier oder Make wird aus dieser Liste gebaut und passt deshalb immer zur aktuellen Fassung der Vorlage.

Nachschlagen

Einige Aufrufe gibt es, damit ein System oder eine No-Code-Plattform findet, was es braucht, ohne zu raten:

• GET /api/v1/me (ohne Berechtigung) liefert den Arbeitsbereich, zu dem das Token gehört, seinen Tarif sowie Namen und Berechtigungen des Tokens selbst. So prüfen Sie am einfachsten, ob ein Token funktioniert.
• GET /api/v1/documents (Berechtigung documents:read) listet die neuesten Dokumente zuerst. Eingrenzen lässt sich die Liste mit reference (die genaue DOC-…-Referenz), status oder template_id; limit erlaubt bis zu 100, Standard ist 25.
• GET /api/v1/cases (Berechtigung cases:read) listet die neuesten Vorgänge, auf Wunsch nur die mit einem bestimmten status, mit demselben limit. Jeder Vorgang enthält jetzt auch created_at.
• GET /api/v1/case-types (Berechtigung cases:read) listet die Vorgangstypen, aus denen sich ein Vorgang anlegen lässt.
• GET /api/v1/templates?name=… behält nur die Vorlagen, deren Name den Text enthält, ohne auf Groß- und Kleinschreibung zu achten.

Seitenweises Blättern gibt es mit Absicht nicht: Diese Listen dienen dazu, das Neueste zu finden, nicht dazu, einen ganzen Arbeitsbereich zu exportieren.

Welcher Tarif

API und Webhooks gehören zum Tarif Team. In jedem anderen Tarif bleiben bereits erstellte Tokens und Adressen sichtbar und können widerrufen werden, aber neue werden nicht ausgestellt, und Aufrufe mit einem Token werden nicht mehr bedient. Vergleichen Sie die Tarife auf der Preisseite.