API en webhooks

Waar je het vindt

Beginnen documenten op je kantoor ergens anders dan in DocuTract, dan kan dat systeem rechtstreeks met ons praten. Open het menu met je adres rechtsboven en kies Integraties: daar maak je een token aan waarmee je systeem ons aanroept, en voeg je het adres toe waarop we het over kant-en-klare documenten informeren.

Het scherm begint met kant-en-klare koppelingen met CRM's (CRM-integraties); de tokens en webhooks die hier beschreven staan, vind je eronder, in het gedeelte API en webhooks.

Het token

Klik op Token aanmaken, geef het een naam die je later herkent (zodat je weet welk systeem het gebruikt), en vink aan wat het mag doen: sjablonen lezen, documenten aanmaken, met dossiers werken.

Het token zelf wordt één keer getoond, direct na het aanmaken: we bewaren alleen een hash ervan, dus het een tweede keer tonen kunnen zelfs wij niet. Kopieer het meteen naar de instellingen van je systeem.

De lijst toont de eerste tekens van elk token, wat het mag doen en wanneer het voor het laatst is gebruikt. Intrekken schakelt een token direct uit; de registratie ervan blijft, zodat zichtbaar is dat het bestond en wanneer het ophield te werken.

Wat de API kan

Je systeem kan:

• een dossier openen en er scans in uploaden;
• een document aanmaken vanuit een sjabloon met de waarden al ingevuld;
• vragen in welke fase een document zit;
• alle waarden ophalen, samen met de scan waaruit elke waarde is gelezen;
• een kortlevende link naar het kant-en-klare bestand krijgen.

De volledige beschrijving van elk adres en veld wordt uit de code zelf gegenereerd en openbaar gepubliceerd: de API-beschrijving.

Webhooks

In plaats van ons te vragen of een document klaar is, geef je ons een adres en schrijven wij jou. Voeg het toe onder Webhooks en vink de gebeurtenissen aan: document klaar, document mislukt, dossier klaar, een afwijking gevonden, een klant heeft een bestand gestuurd.

Elk verzoek is ondertekend met de header X-DocuTract-Signature, en het geheim waarmee je de handtekening verifieert, wordt net als het token één keer getoond. Je systeem moet de handtekening controleren en antwoorden met een 2xx-code. Antwoordt het iets anders, of helemaal niet, dan proberen we het opnieuw: na een minuut, na vijf, na een halfuur, na twee uur en na tien, en daarna stoppen we.

Als er iets niet is aangekomen

De knop Afleveringen toont het logboek: welke gebeurtenis we hebben verstuurd, wanneer, hoe vaak, welke responscode terugkwam en het begin van de responsinhoud. Dat is het antwoord op «ons systeem heeft niets ontvangen»: zwart op wit staat dat het om 14:12 vier keer met 500 antwoordde.

Test versturen stuurt nu meteen een ping naar het adres, zonder op een echte gebeurtenis te wachten, zodat een ontvanger kan worden ingericht voordat er echt werk doorheen gaat. Opnieuw proberen, naast een mislukte aflevering, doet direct nog een poging.

Zapier, Make en n8n

No-codeplatforms (diensten waarin je een integratie zonder programmeren bouwt) abonneren zichzelf op onze gebeurtenissen, via het REST-hooksdeel van de API, zodat niemand hun adressen in DocuTract hoeft over te nemen. Geef het platform een token met de rechten webhooks:read en webhooks:write, plus wat zijn acties nodig hebben (bijvoorbeeld templates:read en documents:write).

• POST /api/v1/hooks met {"event": "document.ready", "target_url": "https://…"} abonneert een adres op één gebeurtenis. Het antwoord bevat de id van het abonnement en, eenmalig, het secret voor de handtekening.
• GET /api/v1/hooks toont de abonnementen die zo zijn gemaakt; DELETE /api/v1/hooks/{id} verwijdert er één.
• GET /api/v1/hooks/events toont de gebeurtenissen: document.ready, document.failed, case.ready, finding.raised, intake.uploaded.
• GET /api/v1/hooks/samples/{event} geeft een voorbeeld van de inhoud, die het platform in zijn „testtrigger” laat zien voordat er een echte gebeurtenis is geweest.

Een abonnement is een gewoon webhookadres: op dezelfde manier ondertekend, opnieuw geprobeerd en gelogd, en zichtbaar in de lijst onder Webhooks. Het stopt als het token dat het maakte wordt ingetrokken of verloopt, of als het platform een aflevering beantwoordt met 410 Gone.

Zo ziet document.ready eruit:

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

en zo 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"
}

De velden van een sjabloon

GET /api/v1/templates/{id}/fields (recht templates:read) toont wat een sjabloon nodig heeft: de key van elk veld (waarmee de values in POST /api/v1/documents worden aangeduid), het label, waar het vandaan wordt ingevuld, en fillable, dat false is voor een veld dat DocuTract zelf invult, zoals een datum. Een formulier in Zapier of Make wordt uit deze lijst opgebouwd en past dus altijd bij het sjabloon zoals het nu is.

Opzoeken

Een paar aanroepen bestaan zodat een systeem, of een no-codeplatform, vindt wat het nodig heeft zonder te raden:

• GET /api/v1/me (geen recht nodig) geeft de werkruimte waar het token bij hoort, het abonnement en de naam en rechten van het token zelf. Zo controleer je het makkelijkst of een token werkt.
• GET /api/v1/documents (recht documents:read) toont de nieuwste documenten eerst. Verfijn met reference (de exacte DOC-…-referentie), status of template_id; limit gaat tot 100, standaard 25.
• GET /api/v1/cases (recht cases:read) toont de nieuwste dossiers, desgewenst alleen die met één status, met dezelfde limit. Elk dossier heeft nu ook een created_at.
• GET /api/v1/case-types (recht cases:read) toont de dossiertypes waarmee je een dossier kunt openen.
• GET /api/v1/templates?name=… houdt alleen de sjablonen over waarvan de naam de tekst bevat, ongeacht hoofdletters.

Paginering is er bewust niet: deze lijsten zijn om het nieuwste te vinden, niet om een hele werkruimte te exporteren.

Welk abonnement

De API en webhooks zijn onderdeel van het Team-abonnement. In elk ander abonnement blijven de tokens en adressen die je al hebt aangemaakt zichtbaar en kunnen ze worden ingetrokken, maar er worden geen nieuwe uitgegeven, en aanroepen met een token worden niet meer bediend. Vergelijk abonnementen op de prijspagina.