Quand les documents naissent dans un autre système

La question qui revient lors du deuxième rendez-vous : « vous vous intégrez à notre système ? ». Jusqu’à présent, la réponse honnête était non. Désormais, la réponse est la suivante : vous avez un portail, un CRM ou un logiciel de comptabilité où la transaction existe déjà, et DocuTract peut fonctionner comme une partie de celui-ci.

La sixième fonctionnalité de la vague est la porte de sortie. Un jeton avec lequel votre système nous appelle, une adresse à laquelle nous écrivons de nous-mêmes, et une description ouverte de tout ce qui se trouve entre les deux.

Un jeton que nous ne pouvons pas vous montrer deux fois

Un jeton se crée sur l’écran Intégrations : un nom que vous reconnaîtrez plus tard, pour savoir quel système l’utilise, et une liste de ce qu’il est autorisé à faire. Ensuite, il est affiché une seule fois.

Ce n’est pas un oubli, c’est ainsi que doit fonctionner un produit qui détient la clé de quelqu’un d’autre. Nous ne conservons qu’une empreinte (hash) : afficher le jeton une seconde fois est impossible, même pour nous, ce qui signifie qu’on ne peut pas nous le voler. La liste conserve les premiers caractères, les permissions et la date de dernière utilisation, pour qu’on voie quel jeton est actif et si quelqu’un l’utilise encore.

Révoquer le désactive instantanément. Sa trace reste : qu’il a existé et quand il a cessé de fonctionner fait partie de l’historique de l’espace de travail, ce n’est pas du désordre.

Les permissions sont vérifiées séparément pour chaque adresse. Un jeton autorisé uniquement à lire les modèles reçoit un simple « the documents:write scope is missing » (la portée documents:write manque) lorsqu’il tente de créer un document, et non un « not found » vide. Nous partons du principe qu’une personne réelle met en place l’intégration, et une réponse qui n’explique rien lui coûte une soirée.

Ce que permet l’API

Tout ce que vous pouvez faire à l’écran, simplement sans l’écran : 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 il en est, récupérer chaque valeur avec le scan sur lequel elle a été lue, et obtenir un lien temporaire vers le fichier finalisé.

C’est ce dernier point qui distingue cette intégration des autres. Votre système reçoit non seulement un fichier rempli mais aussi chaque valeur avec son origine : le scan, le champ, le degré de fiabilité de la lecture. La même source que celle qu’une personne voit sur l’écran de vérification est accessible au code.

La description de chaque adresse et de chaque champ est générée à partir du code lui-même et publiée ouvertement, sans jeton : /api/v1/openapi.json. Une documentation qu’il faut d’abord demander est une documentation que personne ne lit.

Des webhooks et un journal honnête

Vous n’avez pas à nous demander si un document est prêt. Donnez-nous une adresse 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, et le secret qui permet de vérifier la signature n’est affiché qu’une fois, comme le jeton. Si votre serveur a répondu autre chose, ou n’a pas répondu 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, car une intégration que personne n’entretient ne devrait pas consommer indéfiniment les ressources de quelqu’un.

Et voici la partie pour laquelle tout cela a été écrit. Quand l’autre partie dit « notre système n’a rien reçu », la réponse est à l’écran : l’événement, l’heure, le nombre de tentatives, le code de réponse renvoyé et le début du corps de la réponse. On voit qu’il a répondu 500 cinq fois. Ce n’est pas un outil de débogage pour nous, c’est une réponse pour votre ingénieur.

À côté, deux boutons pour le moment où une intégration est encore en cours de configuration. Envoyer un test envoie immédiatement une requête d’essai, sans attendre un vrai événement, pour qu’un récepteur puisse être vérifié avant que du vrai travail ne passe par lui. Réessayer, à côté d’un envoi en échec, fait une nouvelle tentative immédiatement et ne réinitialise pas l’historique : les quatre tentatives échouées restent consignées, car c’est la vérité sur ce que cette notification a coûté.

Les limites que nous nous imposons

Un webhook ne part que vers une adresse https et uniquement publique : une adresse située dans un réseau privé est refusée à la fois lors de l’enregistrement et avant chaque tentative, car un nom d’hôte qui pointait vers l’extérieur hier peut pointer vers l’intérieur aujourd’hui. La limite de fréquence est comptée par jeton plutôt que par adresse, pour qu’un voisin sur le même serveur ne consomme pas votre quota, et la dépasser vous vaut un honnête « revenez dans tant de secondes ».

L’API et les webhooks font partie du forfait Team. Si un espace de travail passe à un autre forfait, ce qui a déjà été créé reste visible et peut être révoqué : des clés que personne ne peut atteindre sont pires qu’une fonctionnalité payante.

Ce qui ne figure pas dans cette version

Le cahier des charges de cette phase décrivait deux autres parties : l’export d’un document finalisé vers Google Drive, OneDrive ou Dropbox, et son envoi pour signature via DocuSign ou Dropbox Sign. Les deux nécessitent des identifiants de ces fournisseurs, que nous n’avons pas pour le moment, et écrire une intégration qui ne peut être testée nulle part reviendrait à faire passer du code non écrit pour du code terminé. Elles restent au programme en tant que versions à part entière.

La suite

La septième et dernière fonctionnalité de la vague est la génération par lots : une liste de cinquante lignes ou une archive de scans au lieu de cinquante remplissages identiques à la main, avec une progression visible et la possibilité de ne relancer que ceux qui n’ont pas fonctionné.

La liste complète se trouve dans ce que nous construisons ensuite, et les instructions pas à pas pour les intégrations dans le centre d’aide.