Skip to main content
Vos équipes reçoivent parfois le document sans que le client soit derrière un écran : une pièce déposée en agence, un fichier déjà présent dans votre GED, une image capturée par votre propre application. Pour ces cas, inutile de faire suivre un lien de parcours — envoyez le document, la réponse porte le résultat.
La réponse (201) est le même objet que la lecture d’un résultat : verdict, points d’attention, cachet 2D-Doc, identifiants — un seul format à intégrer, que le dossier vienne d’un parcours ou d’une analyse directe.

​
Les deux natures de document

Le type réel du fichier est décidé par son contenu, jamais par une déclaration. Limite : 10 Mo par fichier ; le préfixe data URL et les retours à la ligne du base64 sont tolérés et ne comptent pas. Un TIFF de plusieurs pages, un GIF, un BMP ou un HEIC sont refusés (400, invalid_document) : envoyez un PDF. Si l’administrateur de l’entreprise désactive l’IA, toute nouvelle analyse administratif reçoit 403 avec error: "ia_desactivee", sans création de consultation. Les contrôles identite restent accessibles selon le contrat. Les résultats antérieurs, y compris leur rejeu idempotent, restent consultables.

​
Le lieu du contrôle

Si votre entreprise contribue au parcours du document, chaque pièce d’identité analysée y laisse une trace : empreinte du numéro, résultat, date. Ajoutez agencyPostalCode, le code postal de la commune de l’agence qui contrôle, pour que cette trace apparaisse à cet endroit sur la carte du parcours :
Le point est posé au centre de la commune ; un code postal partagé par plusieurs communes désigne la plus peuplée. Un code qu’aucune commune de France ne porte (code CEDEX, faute de frappe) est refusé avant toute analyse (400, invalid_request). Sans ce champ, la trace n’apparaît pas sur la carte.

​
Les verdicts d’une pièce administrative

Une pièce d’identité ne reçoit jamais sans_anomalie. Ce que ces verdicts ne disent pas :
  • Un fichier vaut une pièce. Quand un fichier de plusieurs pages regroupe plusieurs pièces, les contrôles portent sur la première : le résultat le signale et la pièce part à la revue. Présentez chaque pièce séparément.
  • Seul l’émetteur est contrôlé. Le numéro ou l’adresse d’un tiers (client, destinataire, patient, prescripteur) n’est ni confirmé ni mis en cause.
  • sans_anomalie confirme l’émetteur, pas la pièce. Une pièce fabriquée qui reprend fidèlement l’identité d’un émetteur réel, avec un contenu cohérent, n’est pas distinguée d’une vraie. Seuls un cachet 2D-Doc, la mémoire des pièces ou une revue l’arrêtent.
  • conforme peut porter des points d’attention. Le cachet vérifié fait foi ; un point d’attention (fichier réenregistré, pièce déjà présentée) reste listé dans anomalies.
  • Une numérisation très floue peut être lue de travers. La pièce sort alors à vérifier : rien ne confirme un émetteur mal lu.
  • Le détail des contrôles est rendu en français, quelle que soit la langue du compte.

​
« Analyse impossible » est un résultat

Un document qui s’ouvre mais dont rien ne peut être lu (page blanche, photo sans texte) rend un 201 avec verdict: "analyse_impossible" : l’analyse a eu lieu, elle est enregistrée et relisible, elle n’est pas décomptée, et votre système route ce dossier dans son propre processus. Un fichier qui ne s’ouvre pas (abîmé, protégé par un mot de passe, format non pris en charge) est refusé : 400, invalid_document. Les erreurs HTTP portent sur la requête (400, 413), les droits (403) ou la disponibilité du service (502, 503 — réessayez).

​
Un retry ne crée jamais deux analyses

Chaque appel étant un acte, protégez vos retries réseau avec l’en-tête Idempotency-Key : la même clé dans les 24 heures rend le même résultat, sans nouvelle analyse. La réponse rejouée porte Idempotency-Replayed: true. Une clé désigne une seule requête : reprise avec un autre document, une autre référence ou une autre option, elle est refusée (422, idempotency_key_reused). Deux envois simultanés de la même clé : le second reçoit 409 (processing) et se rejoue après le délai indiqué. Après une erreur (400, 500, 502, 503), la même clé peut être rejouée. Si le résultat a été supprimé depuis, la clé répond 410 (consultation_deleted). La clé n’est conservée que sous forme d’empreinte.

​
Le certificat

Ajoutez "includeCertificate": true pour recevoir, dans la même réponse, le certificat PDF en base64 (certificate) — le même document que celui téléchargé depuis le portail, n’affichant que les contrôles réellement effectués. Son QR code pointe vers la page publique de vérification d’authenticité. Il reste retéléchargeable à tout moment :

​
Débit

L’analyse directe a son propre plafond : 20 analyses par minute par entreprise, en plus du débit global. Au-delà, 429 avec Retry-After. Pour un volume important sans contrainte de temps réel, préférez un lot. Si la capacité instantanée du service est occupée, 503 avec Retry-After vous indique quand retenter sans créer de deuxième analyse.