API et webhooks

Où le trouver

Si les documents de votre cabinet naissent ailleurs que dans DocuTract, ce système peut communiquer directement avec nous. Ouvrez le menu avec votre adresse en haut à droite et choisissez Intégrations : c’est là qu’est émis le jeton avec lequel votre système nous appelle, et là que vous ajoutez l’adresse à laquelle nous signalons les documents finalisés.

L’écran commence par les connexions CRM prêtes à l’emploi (Intégrations CRM) ; les jetons et webhooks décrits ici se trouvent en dessous, dans la section API et webhooks.

Le jeton

Appuyez sur Créer un jeton, donnez-lui un nom que vous reconnaîtrez plus tard (pour savoir quel système l’utilise), et cochez ce qu’il est autorisé à faire : lire les modèles, créer des documents, travailler avec les dossiers.

Le jeton lui-même n’est affiché qu’une fois, juste après sa création : nous n’en conservons qu’une empreinte (hash), donc l’afficher une seconde fois est impossible, même pour nous. Copiez-le directement dans les paramètres de votre système.

La liste affiche les premiers caractères de chaque jeton, ce qu’il peut faire et sa dernière utilisation. Révoquer désactive un jeton immédiatement ; sa trace est conservée, pour qu’on voie qu’il a existé et quand il a cessé de fonctionner.

Ce que permet l’API

Votre système peut :

• ouvrir un dossier et y importer des scans ;
• créer un document à partir d’un modèle avec les valeurs déjà remplies ;
• demander à quelle étape se trouve un document ;
• récupérer chaque valeur avec le scan sur lequel elle a été lue ;
• obtenir un lien temporaire vers le fichier finalisé.

La description complète de chaque adresse et de chaque champ est générée à partir du code lui-même et publiée ouvertement : la description de l’API.

Webhooks

Au lieu de nous demander si un document est prêt, donnez-nous une adresse et nous vous écrirons. Ajoutez-la sous Webhooks et cochez les événements : document prêt, document en échec, dossier prêt, divergence détectée, fichier envoyé par un client.

Chaque requête est signée avec l’en-tête X-DocuTract-Signature, et le secret qui permet de vérifier la signature n’est affiché qu’une fois, comme le jeton. Votre système doit vérifier la signature et répondre avec un code 2xx. S’il répond autre chose, ou ne répond pas du tout, nous réessayons : au bout d’une minute, de cinq, d’une demi-heure, de deux heures et de dix heures, puis nous arrêtons.

Quand quelque chose n’est pas arrivé

Le bouton Envois affiche le journal : quel événement nous avons envoyé, quand, combien de fois, quel code de réponse est revenu et le début du corps de la réponse. C’est la réponse à « notre système n’a rien reçu » : il est écrit noir sur blanc qu’il a répondu 500 quatre fois à 14:12.

Envoyer un test envoie immédiatement un ping à l’adresse, sans attendre un vrai événement, pour qu’un récepteur puisse être configuré avant que du vrai travail ne passe par lui. Réessayer, à côté d’un envoi en échec, fait une nouvelle tentative immédiatement.

Zapier, Make et n8n

Les plateformes no-code (des services où l’on monte une intégration sans programmer) s’abonnent d’elles-mêmes à nos événements, par la partie REST hooks de l’API : personne n’a à copier leurs adresses dans DocuTract. Donnez à la plateforme un jeton avec les autorisations webhooks:read et webhooks:write, plus celles dont ses actions ont besoin (par exemple templates:read et documents:write).

• POST /api/v1/hooks avec {"event": "document.ready", "target_url": "https://…"} abonne une adresse à un événement. La réponse contient l’id de l’abonnement et, une seule fois, son secret de signature.
• GET /api/v1/hooks liste les abonnements créés de cette façon ; DELETE /api/v1/hooks/{id} en supprime un.
• GET /api/v1/hooks/events liste les événements : document.ready, document.failed, case.ready, finding.raised, intake.uploaded.
• GET /api/v1/hooks/samples/{event} renvoie un exemple de contenu, que la plateforme montre dans son « déclencheur de test » avant tout événement réel.

Un abonnement est une adresse de webhook ordinaire : signée, relancée et journalisée de la même manière, et visible dans la liste Webhooks. Il prend fin quand le jeton qui l’a créé est révoqué ou expire, ou quand la plateforme répond à un envoi par 410 Gone.

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

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

Les champs d’un modèle

GET /api/v1/templates/{id}/fields (autorisation templates:read) liste ce dont un modèle a besoin : la key de chaque champ (celle qui sert de clé aux values de POST /api/v1/documents), son label, d’où il est rempli, et fillable, qui vaut false pour un champ que DocuTract remplit lui-même, comme une date. Un formulaire dans Zapier ou Make est construit à partir de cette liste et correspond donc toujours au modèle tel qu’il est.

Recherches

Quelques appels existent pour qu’un système, ou une plateforme no-code, trouve ce qu’il lui faut sans deviner :

• GET /api/v1/me (sans autorisation) renvoie l’espace de travail auquel appartient le jeton, son offre, ainsi que le nom et les autorisations du jeton lui-même. C’est le moyen le plus simple de vérifier qu’un jeton fonctionne.
• GET /api/v1/documents (autorisation documents:read) liste les documents, les plus récents d’abord. Affinez avec reference (la référence DOC-… exacte), status ou template_id ; limit va jusqu’à 100, 25 par défaut.
• GET /api/v1/cases (autorisation cases:read) liste les dossiers les plus récents, au besoin seulement ceux d’un status donné, avec le même limit. Chaque dossier porte désormais aussi son created_at.
• GET /api/v1/case-types (autorisation cases:read) liste les types de dossier à partir desquels on peut ouvrir un dossier.
• GET /api/v1/templates?name=… ne garde que les modèles dont le nom contient le texte, sans tenir compte de la casse.

Il n’y a volontairement pas de pagination : ces listes servent à trouver les éléments récents, pas à exporter tout un espace de travail.

Quel forfait

L’API et les webhooks font partie du forfait Team. Avec tout autre forfait, les jetons et adresses que vous avez déjà créés restent visibles et peuvent être révoqués, mais aucun nouveau n’est émis, et les appels effectués avec un jeton ne sont plus servis. Comparez les forfaits sur la page des tarifs.