Passer au contenu principal
POST
Python
Envoyez un document et la liste des champs à lire dans ce document. Didit exécute sur le fichier son modèle d’extraction par défaut, renvoie tous les champs avec leur type (text, number ou date au format YYYY-MM-DD), détecte et décode les codes QR et codes-barres pris en charge, vérifie que le fichier n’a pas été manipulé et, si vous le souhaitez, compare le nom figurant sur le document à la personne ou à l’entreprise attendue. Utilisez-le pour les justificatifs de fonds, les fiches de paie, les relevés bancaires, les documents fiscaux, les factures ou tout document qui ne correspond pas à un modèle fixe. Il s’agit de la version serveur à serveur de l’étape Document AI hébergée. La requête est au format multipart/form-data : le fichier est transmis dans document, et les définitions des champs dans fields, sous la forme d’une chaîne contenant un tableau JSON encodé.

Définir les champs à extraire

fields est un tableau JSON de 1 à 30 éléments, envoyé sous la forme d’une seule chaîne. Chaque élément comporte une key (lettres minuscules, chiffres et tirets bas, unique dans la requête), un name lisible, une instruction qui indique au modèle ce qu’il doit rechercher, un type (text, number ou date) et deux indicateurs : required et is_full_name.
Dans une requête multipart, le tableau entier constitue une seule valeur de formulaire :
La réponse reprend les fields normalisés et renvoie extracted_data, indexé par vos valeurs key, avec null pour tout ce que le modèle n’a pas pu trouver. name, instruction et type sont facultatifs pour chaque élément (type vaut text par défaut) ; key est obligatoire. Envoyer fields sous forme de clés de formulaire de type crochets (fields[0][key]=...), ou sous une autre forme qu’un tableau JSON, renvoie 400 avant le lancement de toute extraction. Rien n’est donc facturé.

Codes QR et codes-barres

Chaque réponse réussie inclut document_ai.detected_codes. Chaque élément contient : Le tableau couvre chaque page traitée d’un PDF et reste vide lorsqu’aucun code pris en charge n’est trouvé. Didit ne devine jamais un payload : des codes QR endommagés peuvent être renvoyés avec leur position et parsed_payload: null, tandis que les échecs de détection de codes ne font pas échouer la requête Document AI.

Correspondance de nom

Marquez au plus un champ avec is_full_name: true et indiquez la personne ou l’entreprise à laquelle le document doit appartenir : Envoyez l’un ou l’autre groupe, pas les deux. Lorsqu’un nom est extrait et qu’un nom attendu est présent, la réponse inclut name_match_score (de 0 à 100) et name_on_document. Un score inférieur à document_ai_name_match_score_threshold (par défaut 80) déclenche l’avertissement DOCUMENT_AI_NAME_MISMATCH et applique document_ai_name_mismatch_action. Si aucun champ n’est marqué is_full_name, Didit utilise le premier champ de type texte dont la clé ressemble à un nom (name, holder, full_name, account_holder) ; marquez explicitement le champ lorsque vous voulez contrôler la valeur comparée. Lorsqu’aucune valeur de nom ne peut être trouvée sur le document, ou qu’aucun nom attendu n’est envoyé, la vérification du nom est ignorée et name_match_score vaut null.

Risques et actions

Chaque risque ci-dessous correspond à un paramètre d’action que vous pouvez définir par requête : DECLINE, REVIEW ou NO_ACTION. L’action la plus stricte déclenchée détermine document_ai.status (Declined > In Review > Approved), et chaque risque déclenché est listé dans document_ai.warnings. Les valeurs par défaut correspondent à celles de l’étape de workflow hébergée ; consultez Règles et avertissements Document AI pour savoir comment chaque risque est détecté.

Fichiers, sauvegarde et facturation

  • Fichiers acceptés : PDF (plusieurs pages prises en charge), JPG, JPEG, PNG, TIFF, WebP, ou un ZIP contenant le document, jusqu’à 30 Mo. Les PDF chiffrés renvoient 400 ; importez à la place un PDF déchiffré ou une photo.
  • save_api_request (par défaut true) : la requête, les champs extraits et les codes détectés apparaissent dans la Business Console, sous Vérifications manuelles, où votre équipe peut les examiner. Définissez-le sur false pour ne pas les sauvegarder.
  • vendor_data et metadata sont renvoyés sans modification dans la réponse, afin que vous puissiez relier le résultat à vos propres enregistrements.
  • Prix : $0.20 par document, facturé lorsque le document est traité et qu’un statut est renvoyé. La remise de votre forfait s’applique. Voir Tarifs.
Vous avez besoin que l’utilisateur téléverse lui-même le document, que vous collectiez jusqu’à 3 documents dans un même parcours, que l’écran de téléversement soit traduit automatiquement, ou que vous croisiez les champs extraits avec des données d’identité ou de questionnaire ? Utilisez plutôt l’étape de workflow Document AI hébergée.

Autorisations

x-api-key
string
header
requis

La clé API de votre application, issue de Développeurs -> Clés API dans la Business Console. La clé principale dispose d'un accès complet. Une clé nommée peut être restreinte : aucun, lecture ou écriture par ressource, limitée à certains workflows ou aux sessions approuvées, à une liste d'adresses IP et à une date d'expiration. 401 signifie que la clé est incorrecte, révoquée ou expirée ; 403 signifie qu'aucune clé n'a été envoyée, que la clé n'a pas accès à cette ressource ou action, ou que la requête provient d'une adresse hors de sa liste d'IP ; 404 sur une route de session signifie que la session est hors des workflows ou des statuts de la clé. Une clé sans accès aux médias reçoit les URL d'images, de vidéos et de PDF à null, et une clé sans accès en écriture aux sessions reçoit les liens et tokens de session à null. Voir https://docs.didit.me/console/api-keys.

Corps

multipart/form-data
document
file
requis

Le document à lire. Extensions autorisées : tiff, jpg, jpeg, png, pdf, webp, zip. Taille maximale de téléversement : 30 MB (les fichiers plus volumineux sont rejetés avec une erreur 400). Les fichiers PDF multipages sont pris en charge (prévoyez une latence plus élevée) ; les PDF chiffrés sont rejetés avec une erreur 400. Les images sont automatiquement compressées avant le traitement.

fields
string
requis

Une chaîne de tableau encodée en JSON avec 1–30 définitions de champs (maximum 16 KB). Chaque élément : key (obligatoire, ^[a-z0-9_]{1,64}$, unique — la clé renvoyée dans extracted_data), name (≤ 100 caractères, affiché dans les messages), instruction (≤ 500 caractères, ce que le modèle doit lire), type (text par défaut | number | date), required (booléen, par défaut false), is_full_name (booléen, par défaut false, au maximum un par requête). Les tableaux de formulaires de type crochets, le JSON invalide, les clés dupliquées ou plus d'un is_full_name renvoient 400 avant tout traitement ou facturation.

Exemple:

"[{\"key\": \"employer_name\", \"name\": \"Employer name\", \"instruction\": \"The employer or company issuing the payslip.\", \"type\": \"text\", \"required\": true, \"is_full_name\": false}, {\"key\": \"employee_name\", \"name\": \"Employee name\", \"instruction\": \"The full name of the employee as printed on the payslip.\", \"type\": \"text\", \"required\": true, \"is_full_name\": true}, {\"key\": \"net_pay\", \"name\": \"Net pay\", \"instruction\": \"The net amount paid to the employee for the period.\", \"type\": \"number\", \"required\": true, \"is_full_name\": false}, {\"key\": \"pay_date\", \"name\": \"Pay date\", \"instruction\": \"The payment date shown on the payslip.\", \"type\": \"date\", \"required\": false, \"is_full_name\": false}]"

expected_first_name
string

Prénom à vérifier par rapport au champ du nom du document (recherche floue, tenant compte de la translittération). À utiliser conjointement avec expected_last_name ; ne peut pas être combiné avec expected_company_name.

Exemple:

"Sophia"

expected_last_name
string

Nom de famille à vérifier par rapport au champ du nom du document, combiné avec expected_first_name pour name_match_score.

Exemple:

"Martinez"

expected_company_name
string

Nom de l'entreprise à vérifier par rapport au champ de nom du document (pour les documents d'entreprise). Ne peut pas être combiné avec expected_first_name / expected_last_name (aucun exemple de valeur fourni intentionnellement — l'exemple de requête généré utilise les champs de personne physique ; remplacez-les par celui-ci lors de la vérification d'un document d'entreprise).

expected_company_country
string

Code pays ISO 3166-1 alpha-2 optionnel (deux lettres ASCII, par ex. FR) qui ajuste la normalisation du nom de l'entreprise pour expected_company_name. Utilisé uniquement avec expected_company_name.

document_ai_name_match_score_threshold
integer
défaut:80

Valeur minimale de name_match_score (0–100) pour considérer le nom comme correspondant. Un score inférieur ajoute DOCUMENT_AI_NAME_MISMATCH, régi par document_ai_name_mismatch_action.

Plage requise: 0 <= x <= 100
Exemple:

80

document_ai_unreadable_document_action
enum<string>
défaut:REVIEW

Ce qu'il faut faire lorsqu'aucun champ n'a pu être lu à partir du document (DOCUMENT_AI_UNREADABLE_DOCUMENT).

Options disponibles:
DECLINE,
REVIEW,
NO_ACTION
document_ai_missing_required_fields_action
enum<string>
défaut:REVIEW

Ce qu'il faut faire lorsqu'au moins un champ required n'a pas pu être lu (DOCUMENT_AI_MISSING_REQUIRED_FIELDS ; additional_data.missing_fields les énumère).

Options disponibles:
DECLINE,
REVIEW,
NO_ACTION
document_ai_document_tampering_action
enum<string>
défaut:DECLINE

Ce qu'il faut faire lorsque l'analyse médico-légale PDF/EXIF suspecte une manipulation — modification après signature numérique, éditeur PDF connu, manipulation par texte superposé, réexportation suspecte, anomalies d'image (DOCUMENT_AI_SUSPECTED_MANIPULATION).

Options disponibles:
DECLINE,
REVIEW,
NO_ACTION
document_ai_name_mismatch_action
enum<string>
défaut:NO_ACTION

Ce qu'il faut faire lorsque name_match_score est inférieur au seuil (DOCUMENT_AI_NAME_MISMATCH).

Options disponibles:
DECLINE,
REVIEW,
NO_ACTION
document_ai_unsupported_file_action
enum<string>
défaut:REVIEW

Que faire lorsque le fichier importé est vide ou n'est pas un fichier traitable (DOCUMENT_AI_UNSUPPORTED_FILE).

Options disponibles:
DECLINE,
REVIEW,
NO_ACTION
save_api_request
boolean
défaut:true

Lorsque la valeur est true (par défaut), conserve l'appel sous la forme d'une session de type API — visible dans la Business Console, récupérable via GET /v3/session/{sessionId}/decision/ à l'aide du request_id renvoyé, avec le document importé, les valeurs extraites, les définitions de champs et l'instantané de correspondance de nom stockés. Lorsque la valeur est false, rien n'est stocké et request_id est un UUID éphémère servant uniquement à la corrélation des réponses ; l'appel reste facturé.

Exemple:

true

vendor_data
string

Chaîne opaque optionnelle (votre identifiant d'utilisateur interne, e-mail, UUID…) stockée sur la session persistée et renvoyée dans la réponse. Utilisez-la pour corréler les appels d'API avec vos propres enregistrements et pour filtrer les sessions ultérieurement.

Exemple:

"user-123"

metadata
object

Objet JSON optionnel stocké avec la session (lorsque save_api_request=true) et renvoyé dans la réponse. Dans les requêtes multipart, envoyez-le sous forme de champ textuel encodé en JSON (par ex. metadata={"flow":"onboarding"}) — il est analysé sous forme d'objet.

Exemple:

Réponse

Document traité. document_ai.status est Approved, Declined ou In Review ; chaque problème détecté est détaillé dans document_ai.warnings. Un document problématique renvoie tout de même 200 — inspectez le corps de la réponse, pas seulement le code HTTP. Lorsque save_api_request=true, request_id est l'identifiant de la session enregistrée.

request_id
string<uuid>

Identifiant de session persistante lorsque save_api_request=true (utilisable avec GET /v3/session/{sessionId}/decision/) ; sinon un UUID de corrélation temporaire.

document_ai
object
vendor_data
string | null

Écho des vendor_data que vous avez envoyées, ou null.

metadata
object | null

Écho de l'objet metadata que vous avez envoyé, ou null.

created_at
string<date-time>

Moment où la requête a été traitée (UTC, ISO 8601).

Dernière modification le 7 novembre 2026