POST /v1/kyc/extract lit les fichiers d’une étape d’envoi et renvoie les champs trouvés, les contrôles propres à chaque document et, avec une reference, un identifiant de dossier et des identifiants de documents. Scope : kyc:extract. C’est le seul appel qui utilise le modèle de vision, donc le seul qui compte dans votre quota mensuel de lectures.
Requête
Formulaire multipart (multipart/form-data). Seul files est obligatoire.
Envoyez un seul type de document par appel.
doc_type et step_key s’appliquent à tous les fichiers de l’appel, et le recto et le verso d’une même carte sont le cas normal pour deux fichiers.
Règles sur les fichiers
Le type de contenu vient de l’en-tête de votre partie multipart, pas du nom du fichier. Envoyez le bon
Content-Type pour chaque partie de fichier. La plupart des bibliothèques HTTP et curl -F le déduisent de l’extension.
Ce qui se passe pendant un appel
L’ordre compte à deux endroits. Les erreurs de validation (400, 413, 422) surviennent avant la réservation de la lecture, donc elles ne coûtent rien. La réservation a lieu avant l’exécution du modèle, donc une lecture qui échoue ensuite compte quand même.Réponse
Clés de premier niveau
Clés de chaque entrée documents[]
Clés de
meta_provenance : pour un PDF, producer et creator (le logiciel, jusqu’à 200 caractères), modified (le ModDate au format YYYY-MM-DD, quand il diffère de la date de création), revisions (combien de fois le fichier a été enregistré de façon incrémentale). Pour une image, creator (la balise EXIF Software) et camera (la balise EXIF Make). L’absence de bloc EXIF n’est pas signalée, car WhatsApp et la plupart des navigateurs le suppriment.
Valeurs des champs
Chaque valeur defields est une string. Le lecteur a pour consigne d’omettre un champ qu’il ne peut pas lire, donc une clé absente signifie “non lu”, jamais “vide”. Le serveur normalise ensuite :
Corrections que le serveur apporte après la lecture, chacune listée dans
notes :
- Les coordonnées bancaires ne sont conservées que si le document est un document bancaire (chèque annulé, relevé bancaire, lettre de banque, RIB). Sur tout autre document, elles sont retirées, car le numéro de compte d’une facture de services ou l’IBAN d’une facture ne sont pas ceux du client.
bank_numberetbank_transitsont des codes canadiens. Ils sont écartés quand le document vient d’un autre pays, ou quand la longueur est fausse (3 chiffres et 5 chiffres). Unbank_numberde 9 chiffres est déplacé versbank_routing, puisque 9 chiffres correspondent à un numéro de routage américain.- Un nom qui se lit comme celui d’un parent sur une carte marocaine (
... ben ...,fils de,bent) est retiré defirst_name,last_nameetdocument_holder_name. - Sur une facture, la dénomination légale, l’adresse et les numéros d’immatriculation du fournisseur ne sont pas fusionnés dans
fields, sauf si le destinataire est la même entité. specimen_markingsreste sur l’entrée du document et n’est jamais fusionné dansfields.
Confiance
L’API ne renvoie ni confiance par champ ni score par document. Le lecteur donne des valeurs, pas des probabilités. Ne cherchez pas de clé de confiance. Vous pouvez tout de même juger une lecture :
La console affiche une valeur fixe de 0.9 pour chaque champ renvoyé par le lecteur. C’est une étiquette pour “lu par le modèle, pas encore relu”, pas une mesure, et la validation du champ reste
pending jusqu’à la relecture par une personne.
reader_unavailable
reader_unavailable: true signifie qu’au moins un fichier n’a jamais été lu : pas d’identifiants côté Sahl, un quota ou un délai dépassé, ou une réponse impossible à analyser. Cela ne veut pas dire que le document était vierge. Un document vierge ou recadré renvoie reader_unavailable: false et peu de champs, voire aucun.
L’appel renvoie quand même 200. La lecture compte quand même. Réessayez le fichier plus tard, et si le problème persiste, communiquez à Sahl l’en-tête X-Request-ID.
Avec une reference, chaque fichier est classé sur le dossier avec un statut que vous voyez dans la console sous Documents :
Contrôles de documents dans la réponse
Chaque fichier reçoit les contrôles adaptés à son type. Ce sont les mêmes contrôles que/verify répète sur les entrées que vous renvoyez. La liste complète avec leur sens est dans Vérifier un profil.
En bref : le document est du type attendu par l’étape (doctype:), ses champs clés ont été lus (legible:), une pièce d’identité n’est pas expirée (expiry:) ou sur le point de l’être (expiry_soon:), le titulaire a 18 ans ou plus (adult:), les chiffres de contrôle de la MRZ d’un passeport ou d’une carte d’identité sont valides (mrz:), un justificatif de domicile est récent (recency:), le fichier n’a pas été réenregistré depuis un éditeur (provenance:), et le document n’est pas un spécimen ou un échantillon (authenticity:specimen:).
Un bulletin de paie ne reçoit aucun contrôle de document. Son entrée ne porte que des champs.