Ce que voit un développeur qui intègre cette API
La documentation marketing d'un outil de reconnaissance de documents promet toujours une extraction parfaite. Un développeur qui doit réellement l'intégrer dans un logiciel de production pose d'autres questions : quelle est la forme exacte de la réponse, comment sait-on qu'un champ est fiable, que se passe-t-il quand un document est illisible, et combien de temps faut-il attendre une réponse sous charge réelle. Cette page répond à ces questions-là, pas à celles d'une plaquette commerciale.
Le problème que résout ce moteur
Un document financier réel — facture, relevé bancaire, reçu — n'est pas un formulaire structuré. La mise en page varie d'un émetteur à l'autre, la qualité de numérisation varie d'un dépôt à l'autre, et un même champ (le montant total, par exemple) peut apparaître à des endroits complètement différents selon le document. Un moteur de reconnaissance doit généraliser au-delà d'un jeu d'exemples fixe, ce qu'un simple gabarit de positions ne peut pas faire dès qu'un nouveau format apparaît.
Comment fonctionne la reconnaissance
Le document envoyé est d'abord analysé pour en identifier la structure générale — en-tête, corps, tableau de lignes le cas échéant — puis chaque champ est localisé et extrait avec son propre niveau de certitude. Cette approche par champ, plutôt qu'un score unique pour tout le document, est ce qui permet à votre intégration de faire des choix fins : accepter automatiquement un montant extrait avec un score de 0,98 tout en signalant un numéro de facture extrait à 0,61 pour confirmation humaine.
La forme de la réponse
Un appel réussi renvoie un objet JSON contenant les champs d'en-tête du document (émetteur, date, numéro de pièce, montant total, devise), un tableau line_items quand le document en contient, et un objet confidencequi reflète chaque champ individuellement. La documentation technique complète des endpoints figure dans la documentation API, en anglais ; l'équipe support répond en français pour toute question d'intégration.
Le score de confiance, champ par champ
| Plage de score | Comportement recommandé |
|---|---|
| 0,90 – 1,00 | Accepter automatiquement sans intervention humaine |
| 0,70 – 0,89 | Accepter, mais afficher le champ en évidence pour une relecture rapide |
| Sous 0,70 | Router vers une vérification humaine explicite avant intégration |
Ces seuils sont indicatifs, pas imposés — chaque intégration ajuste sa propre tolérance selon la criticité du champ concerné : un montant total mérite souvent un seuil plus strict qu'un libellé de ligne secondaire.
Formats de documents supportés
| Format en entrée | Remarque |
|---|---|
| PDF natif | Traité directement, y compris multi-pages |
| PDF scanné | Traité comme une image, sans texte sélectionnable requis |
| JPEG / PNG | Photo prise au téléphone, y compris légèrement inclinée |
| HEIC | Format natif iPhone, converti automatiquement côté serveur |
Latence et traitement asynchrone
Un document court revient généralement en quelques secondes en appel synchrone. Pour un import par lot — plusieurs centaines de documents historiques à traiter d'un coup, par exemple lors d'une migration — un mode asynchrone évite de maintenir une connexion ouverte : chaque document est traité en file d'attente et une notification est envoyée par webhook à chaque résultat disponible, plutôt que de faire attendre le client sur un appel bloquant.
Avant et après l'intégration
Avant
Un utilisateur dépose un document, puis ressaisit manuellement chaque champ dans votre logiciel — une étape lente et source d'erreurs de saisie.
Après
Le document est déposé, les champs apparaissent préremplis avec leur score de confiance, et l'utilisateur ne corrige que ce qui est réellement signalé comme incertain.
Cas d'usage concrets
Préremplissage d'écritures comptables
Facture fournisseur déposée, champs extraits, écriture proposée avant validation par l'utilisateur.
Rapprochement bancaire
Relevé bancaire multi-pages transformé en lignes de mouvement structurées pour rapprochement automatique.
Note de frais mobile
Photo de reçu prise au téléphone, ligne de dépense structurée disponible en quelques secondes.
Import massif à la migration
Plusieurs centaines de documents historiques traités par lot avec notification par webhook à chaque résultat.
Notifications et webhooks
Un document soumis en mode asynchrone déclenche une notification vers une URL de webhook que vous configurez, avec le résultat complet de l'extraction en corps de requête. Cela évite à votre intégration d'interroger l'API en boucle pour savoir si un document est prêt — votre système est notifié dès que le résultat existe.
Gestion des erreurs et des documents illisibles
Un document réellement illisible — trop flou, tronqué, corrompu — renvoie un statut d'échec explicite plutôt qu'une donnée inventée qui semblerait plausible. Aucun document en échec n'est facturé. Côté intégration, ce cas est généralement géré en proposant à l'utilisateur de reprendre la photo ou de saisir le document manuellement, plutôt que de laisser une donnée incorrecte entrer silencieusement dans le système.
Limites et volumétrie
Une limite de débit par défaut protège l'infrastructure partagée entre tous les clients ; elle est ajustée à la hausse sur demande pour une intégration en production à fort volume. Il n'existe pas de limite dure sur le volume mensuel total — le tarif suit simplement le nombre de pages traitées avec succès, décrit en détail sur la page tarifs.
Authentification et sécurité
Chaque appel est authentifié par une clé API propre à votre compte, révocable et régénérable indépendamment depuis le tableau de bord. Les documents transitent chiffrés en TLS et sont traités sur des serveurs situés en Union européenne — le détail complet figure sur la page sécurité.
Comparé à un moteur OCR générique
Un moteur d'OCR générique renvoie généralement du texte brut, ligne par ligne, sans comprendre qu'un groupe de chiffres est un montant total plutôt qu'un numéro de téléphone. Ce moteur va plus loin : il identifie la structure du document — quels champs appartiennent à l'en-tête, lesquels forment une ligne de détail — et renvoie une réponse déjà structurée, prête à être mappée vers votre modèle de données, sans étape de post-traitement supplémentaire côté client.
Tester et valider avant la mise en production
La méthode la plus fiable pour valider une intégration avant de l'exposer à de vrais utilisateurs consiste à rejouer un lot de documents historiques déjà connus — dont vous connaissez déjà les valeurs attendues — et à comparer champ par champ la réponse de l'API à ces valeurs de référence. Cette comparaison révèle immédiatement les écarts de mapping côté intégration, avant qu'ils n'affectent un utilisateur réel.
Un environnement de test utilisant les mêmes identifiants qu'un compte de production, mais avec un suivi de consommation séparé, permet de faire cette validation sans mélanger les chiffres de test avec le volume réellement facturé. La plupart des équipes gardent ce jeu de test comme suite de non-régression, rejouée à chaque évolution significative de leur propre code d'intégration.
Idempotence et déduplication
Un document envoyé deux fois par erreur — un double clic, une requête retentée après un timeout réseau côté client — ne doit pas produire deux résultats divergents ni facturer deux fois le même document. Un identifiant de requête que vous générez côté client et transmettez à chaque appel permet à l'API de reconnaître un doublon et de renvoyer le résultat déjà calculé plutôt que de relancer un traitement complet.
Cette protection compte particulièrement pour une intégration qui retente automatiquement un appel en cas d'échec réseau temporaire — un comportement recommandé pour la robustesse, mais qui, sans idempotence, risquerait de multiplier les traitements d'un même document.
Champs personnalisés et cas particuliers
Le schéma de réponse standard couvre les champs les plus communément utilisés par un logiciel de gestion — mais un secteur particulier peut avoir besoin d'un champ additionnel spécifique, par exemple un numéro de dossier interne présent sur certains documents d'un client donné. Ce type de besoin se traite généralement par un mapping personnalisé côté intégration plutôt que par une modification du schéma standard, ce qui garde ce dernier stable pour tous les autres clients.
Un document qui ne correspond à aucun des types couverts nativement — un cas rare mais réel pour un éditeur au périmètre très large — remonte les champs génériques qu'il a pu identifier, avec un score de confiance reflétant cette incertitude structurelle, plutôt qu'un refus pur et simple de traiter le document.
Performance à grande échelle
Un pic de dépôts — une fin de mois pour un logiciel de note de frais, une fin d'exercice fiscal pour un logiciel de comptabilité — multiplie parfois le volume quotidien par plusieurs fois sur une courte période. L'infrastructure est dimensionnée pour absorber ce type de variation sans dégradation notable du temps de réponse, contrairement à une infrastructure interne dimensionnée pour un volume moyen et mise sous tension lors de ces pics.
Pour un import massif planifié à l'avance — une migration de plusieurs dizaines de milliers de documents historiques, par exemple — le mode asynchrone avec notification par webhook reste la méthode recommandée plutôt que d'envoyer ce volume en appels synchrones successifs.
| Situation | Mode recommandé |
|---|---|
| Dépôt unitaire par un utilisateur | Appel synchrone |
| Import de quelques dizaines de documents | Appels synchrones en série |
| Import de plusieurs centaines à milliers de documents | Mode asynchrone avec webhook |
| Pic saisonnier imprévisible | Aucune adaptation requise côté intégration |
Versionnage et stabilité dans le temps
Le schéma de réponse est versionné explicitement, ce qui signifie qu'une évolution du moteur — l'ajout d'un nouveau champ, une amélioration de la précision sur un type de document — n'altère jamais silencieusement la structure que votre intégration attend déjà. Un changement structurel, plus rare, est annoncé à l'avance plutôt que déployé sans préavis sur une intégration en production.
Surveiller la qualité d'extraction dans le temps
Une intégration qui fonctionne bien le premier mois ne garantit pas qu'elle continuera de bien fonctionner le douzième — un nouveau format de facture chez un fournisseur, une nouvelle banque utilisée par un client, ou simplement une évolution du mix de documents traités peuvent faire dériver silencieusement le taux de champs signalés à faible confiance. Suivre ce taux dans le temps, même sommairement, permet de détecter cette dérive avant qu'elle ne devienne visible pour les utilisateurs finaux.
Un tableau simple, mis à jour chaque semaine — nombre de documents traités, taux de champs acceptés automatiquement, taux routé vers vérification humaine — suffit pour la plupart des intégrations à repérer une anomalie avant qu'un utilisateur ne la signale lui-même en support.
| Indicateur suivi | Fréquence recommandée |
|---|---|
| Volume de documents traités | Quotidienne ou hebdomadaire |
| Taux de champs acceptés automatiquement | Hebdomadaire |
| Taux routé vers vérification humaine | Hebdomadaire |
| Taux d'échec complet d'extraction | Hebdomadaire, avec alerte si anormalement haut |
Environnements de développement, recette et production
Une clé distincte par environnement — développement, recette, production — évite qu'un appel de test n'affecte les statistiques de production ou n'apparaisse dans la facturation réelle. Chaque clé peut être révoquée et régénérée indépendamment depuis le tableau de bord, ce qui limite l'impact si l'une d'entre elles fuite accidentellement dans un dépôt de code ou un journal applicatif partagé.
La plupart des équipes gardent un environnement de recette permanent, séparé de la production, pour tester chaque évolution de leur propre code d'intégration avant de la déployer — exactement la même discipline que pour n'importe quel autre service externe dont le logiciel dépend.
Cette séparation par environnement compte aussi pour la conformité : un questionnaire de sécurité d'un client demande parfois explicitement comment sont isolées les données de test des données réelles de production, une question à laquelle une architecture à clés séparées répond directement, sans négociation particulière au moment de la revue.
Cas limites rencontrés en pratique
Un document composite avec plusieurs pièces différentes
Une facture et son bon de livraison scannés ensemble dans un seul fichier reviennent avec les champs de chaque pièce identifiés séparément lorsque c'est détectable.
Une écriture manuscrite partielle sur un document imprimé
Un montant corrigé à la main sur une facture imprimée peut faire baisser la confiance sur ce champ précis, signalant correctement l'incertitude plutôt que de choisir arbitrairement une valeur.
Un document pivoté à 90 degrés
L'orientation est détectée et corrigée automatiquement avant extraction dans la grande majorité des cas.
Un filigrane ou un tampon superposé au texte
Le texte sous-jacent reste généralement lisible ; un score de confiance plus bas signale les cas où le recouvrement est trop important.
Aucun de ces cas limites n'est traité en le rejetant purement et simplement : chacun revient avec les champs que le moteur a pu identifier, accompagnés d'un score de confiance qui reflète honnêtement le niveau d'incertitude réel, plutôt que de forcer une réponse binaire entre succès parfait et échec total. C'est cette nuance, plus que la gestion d'un cas particulier isolé, qui distingue un moteur pensé pour la production d'un prototype testé uniquement sur des documents propres.