> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sahlfinancial.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Types de documents et champs

> Les types de documents renvoyés par le lecteur, les champs qu'il lit, les champs dont chaque contrôle a besoin, et les clés d'étape.

Le lecteur est un lecteur de documents généraliste. Il regarde le fichier, nomme le type de document, et renvoie ceux d'un ensemble fixe de champs qu'il parvient à lire. Il n'y a pas de schéma distinct par type de document dans le code. Ce qui change selon le type, ce sont les champs que les contrôles attendent et les champs qui sont retenus. Cette page liste les deux.

## Types de documents renvoyés par le lecteur

`documents[].doc_type` est l'un de ces codes, ou une autre chaîne en minuscules, ou null.

| `doc_type` | Ce que c'est | Contrôles propres au type |
| - | - | - |
| `national_id` | Carte d'identité nationale ou provinciale (CIN marocaine, carte photo provinciale) | legible, expiry, adult, MRZ si imprimée, format CIN (Maroc) |
| `passport` | Passeport | legible, expiry, adult, MRZ |
| `drivers_license` | Permis de conduire | legible, expiry, adult, format du numéro de permis par province ou État |
| `pr_card` | Carte de résident permanent canadien | legible, expiry, adult, MRZ si imprimée |
| `residence_permit` | Tout autre titre de séjour (carte de séjour, green card américaine) | legible, expiry, adult, MRZ si imprimée |
| `utility_bill` | Facture d'un fournisseur d'électricité, de gaz, d'eau, de mazout, d'internet, de câble ou de téléphone | legible, recency |
| `proof_of_address` | Tout autre document montrant une adresse (bail, assurance, courrier administratif) | legible, recency. L'étape `proof_of_address` ne l'accepte pas. |
| `bank_statement` | Relevé de compte avec opérations et soldes | legible, recency |
| `void_cheque` | Un chèque seul. Jamais un justificatif de domicile. | legible. Une mention VOID est ignorée sur une étape `banking` ou `rib`. |
| `bank_letter` | Lettre de la banque confirmant le compte | aucun |
| `invoice` | Facture d'un fournisseur qui n'est pas un service public | aucun |
| `payslip` | Bulletin de paie | aucun. Champs seulement. |
| `articles_of_incorporation` | Statuts constitutifs, lettres patentes | legible |
| `business_registration` | Lettre de numéro d'entreprise ou extrait de registre | legible |
| `bylaws` | Règlements, convention d'exploitation ou de société | aucun |
| `beneficial_ownership` | Déclaration nommant les propriétaires de 25 % ou plus | aucun |
| `directors_register` | Registre des administrateurs et dirigeants | aucun |
| `board_resolution` | Résolution du conseil, par exemple pour l'ouverture du compte | aucun |
| `financial_statements` | Bilan et état des résultats | aucun |
| `trust_deed` | Acte ou déclaration de fiducie | aucun |
| `beneficiary_list` | Liste des bénéficiaires d'une fiducie | aucun |
| `other` | Tout ce dont le lecteur n'est pas sûr | aucun |

Chaque document reçoit aussi les contrôles qui ne dépendent pas de son type : le filtre `doctype:` quand une étape ou une indication filtre (voir plus bas), `expiry:` quand un `id_expiry` a été lu, un contrôle MRZ quand des lignes MRZ ont été lues, les contrôles de fichier `provenance:` et le contrôle `authenticity:specimen:`. Le [guide de vérification](/fr/guides/verification) explique chacun.

Le lecteur a pour consigne de répondre `other` en cas de doute, car une étiquette fausse donnée avec assurance fait refuser le document d'un client. Les documents juridiques libres (le dernier groupe) sont acceptés avec `other` par les étapes qui les attendent. Le texte libre du lecteur est ramené à ces codes par radical, donc "Driver License", "PR Card" et "Void Cheque" arrivent sous les formes `drivers_license`, `pr_card` et `void_cheque`.

Deux documents d'adresse sont acceptés comme justificatif de domicile : `utility_bill` et `bank_statement`. Un chèque n'en est jamais un.

## Clés de champs

Toutes les clés que le lecteur peut renvoyer, par groupe. Une clé absente de cette liste est écartée.

| Groupe | Clés |
| - | - |
| Identité | `first_name`, `middle_name`, `last_name`, `date_of_birth`, `sex`, `citizenship`, `id_type`, `id_number`, `id_expiry`, `id_country`, `id_province`, `sin`, `ssn` |
| MRZ | `mrz_line1`, `mrz_line2`, `mrz_line3`. Passeport : 2 lignes de 44. Carte d'identité : 3 lignes de 30. Telles quelles, avec les caractères de remplissage `<`. |
| Adresse résidentielle | `street1`, `city`, `province`, `postal_code`, `country`, `phone`, `email` |
| Emploi | `occupation`, `employer_name`, `type_of_business`, `employer_address`, `employer_city`, `employer_province`, `employer_postal`, `business_phone` |
| Situation financière | `annual_income`, `net_liquid_assets`, `net_fixed_assets`, `total_net_worth` |
| Banque | `bank_name`, `bank_number` (institution canadienne, 3 chiffres), `bank_transit` (succursale canadienne, 5 chiffres), `bank_routing` (ABA américain, 9 chiffres), `bank_account`, `iban` |
| Entité | `legal_name`, `business_number`, `registration_number`, `ice`, `if_number`, `tax_id`, `incorporation_date`, `incorporation_jurisdiction`, `entity_address`, `entity_city`, `entity_province`, `entity_postal`, `entity_phone` |
| Personnes qui exercent le contrôle | `rp_first_name`, `rp_last_name`, `rp_occupation`, `director_names`, `beneficial_owners` (noms complets séparés par des virgules) |
| À propos du document | `document_date` (la date imprimée dessus), `document_holder_name` (à qui appartient le document), `specimen_markings` (signes d'échantillon séparés par des virgules, conservés uniquement sur l'entrée du document) |

`id_type` est l'une de ces valeurs : `Passport`, `Driver License`, `National ID`, `Residence Permit` (une carte de résident permanent et une green card sont `Residence Permit`).

Le lecteur sait quel côté d'un document est celui du client. Sur une facture, une note ou un relevé, le client est le destinataire (la partie "facturée à"), jamais l'émetteur. `document_holder_name`, `legal_name`, l'adresse et les clés de contact décrivent le destinataire.

## Champs par type de document

Ce que le lecteur doit chercher sur chaque type, et ce dont les contrôles ont besoin. Le lecteur ne renvoie que ce qui est imprimé et lisible. Rien ci-dessous n'est garanti.

| `doc_type` | Champs à attendre | Champs dont le contrôle a besoin (`legible:`) |
| - | - | - |
| `passport` | `first_name`, `last_name`, `date_of_birth`, `sex`, `citizenship`, `id_type`, `id_number`, `id_expiry`, `id_country`, `mrz_line1`, `mrz_line2`, `document_holder_name` | `first_name`, `last_name`, `date_of_birth`, `id_number` |
| `national_id` | Noms, `date_of_birth`, `sex`, `id_number`, `id_expiry`, `id_country`, champs d'adresse au verso, `mrz_line1` à `mrz_line3` | `first_name`, `last_name`, `id_number` |
| `drivers_license` | Noms, `date_of_birth`, `id_number`, `id_expiry`, `id_province`, `id_country`, champs d'adresse, `sex` | `first_name`, `last_name`, `id_number` |
| `pr_card`, `residence_permit` | Noms, `date_of_birth`, `id_number`, `id_expiry`, `citizenship`, lignes MRZ | `first_name`, `last_name`, `id_number` |
| `utility_bill`, `proof_of_address` | `street1`, `city`, `province`, `postal_code`, `country`, `document_holder_name`, `document_date` | `street1`, `city`, `postal_code`, `document_holder_name` |
| `bank_statement` | `bank_name`, `document_holder_name`, `document_date`, `bank_number`, `bank_transit`, `bank_routing`, `bank_account`, `iban`, champs d'adresse | `bank_name`, `document_holder_name` |
| `void_cheque` | `bank_number`, `bank_transit`, `bank_account` (Canada) ou `bank_routing`, `bank_account` (États-Unis) | `bank_account` |
| `bank_letter` | `bank_name`, `bank_number` et `bank_transit` (Canada) ou `bank_routing` (États-Unis), `bank_account`, `document_holder_name` | aucun |
| `invoice` | Destinataire : `document_holder_name`, champs d'adresse. Les champs de l'émetteur sont retenus, les champs bancaires aussi. | aucun |
| `payslip` | `document_holder_name`, `first_name`, `last_name`, `employer_name`, `occupation`, `document_date`, champs d'adresse de l'employeur. `annual_income` seulement si le bulletin l'indique. | aucun |
| `articles_of_incorporation` | `legal_name`, `incorporation_date`, `incorporation_jurisdiction`, `registration_number`, `director_names` | `legal_name` |
| `business_registration` | `business_number`, `legal_name`, `registration_number`, `ice`, `if_number`, `tax_id`, champs d'adresse de l'entité | `business_number`, `legal_name` |
| Autres pièces d'entité | `legal_name`, `director_names`, `beneficial_owners` quand le document les liste | aucun |

Si tous les champs attendus d'un type manquent, `legible:` est critical. Si certains seulement manquent, c'est un warning qui les nomme (`could not read: id_number`).

<Note>
  Les montants ne sont lus que dans un document qui les indique. Un bulletin de paie montre la paie d'une période. Le lecteur a pour consigne de ne jamais estimer, donc `annual_income` est absent sauf s'il est imprimé. Ne vous fiez pas à un bulletin de paie seul pour le revenu annuel. Voir le [parcours pas à pas](/fr/guides/walkthrough).
</Note>

## Quels champs arrivent dans `fields`

| Règle | Effet |
| - | - |
| Clés bancaires d'un document non bancaire | Retirées. Seuls `void_cheque`, `bank_statement`, `bank_letter` et `rib` gardent `bank_*`. Pour un type sans nom, une indication `doc_type` qui nomme un document bancaire (chèque, relevé bancaire, lettre de banque, relevé, RIB) les conserve. |
| Identité de l'émetteur sur une `invoice` | Retirée de la fusion, sauf si le nom du destinataire et la dénomination légale concordent. |
| `specimen_markings` | Entrée du document seulement. |
| Même clé dans plusieurs fichiers | La première valeur non vide l'emporte dans `fields` fusionné. Chaque document garde sa propre valeur dans `documents[].fields`. |

## Filtrage : `step_key` et `doc_type`

`step_key` fait vérifier par l'appel que le document est de ceux que l'étape attend. Le contrôle `doctype:` est critical : si le lecteur dit "facture de services" et que l'étape prend une pièce d'identité avec photo, la réponse dit `this is a utility bill; this step takes a passport, a national ID card, a driver's licence...` et l'entrée échoue.

Si vous n'envoyez pas de `step_key`, le texte de `doc_type` sert aussi de filtre quand il contient l'une de ces expressions (en minuscules, les espaces comptent) : `photo id`, `passport`, `pr card`, `proof of address`, `bank`, `articles of incorporation`, `business registration`. Par exemple `doc_type=passport` accepte un passeport, une carte d'identité nationale, un permis de conduire ou un titre de séjour. `doc_type=bank_statement` contient `bank` et accepte un relevé bancaire, une facture de services ou un chèque annulé. `doc_type=payslip` ne correspond à rien et n'est pas filtré. Utilisez `step_key` quand vous voulez un filtre précis.

Une étape connue sans filtre de type (`banking`, `rib` et quelques autres) accepte n'importe quel document.

### Clés d'étape

| `step_key` | Classe de champs | Valeurs `doc_type` acceptées |
| - | - | - |
| `photo_id` | identity | `drivers_license`, `national_id`, `passport`, `pr_card`, `residence_permit` |
| `proof_of_address` | address | `bank_statement`, `utility_bill` |
| `banking` | entity | tous (pas de filtre de type) |
| `cin` | identity | `drivers_license`, `national_id`, `passport`, `residence_permit` |
| `rib` | entity | tous (pas de filtre de type) |
| `bulletin_paie` | entity | `other`, `payslip` |
| `articles_of_incorporation` | entity | `articles_of_incorporation` |
| `business_registration` | entity | `business_registration` |
| `bylaws` | entity | `bylaws`, `other` |
| `beneficial_ownership` | entity | `beneficial_ownership`, `other` |
| `directors_register` | entity | `directors_register`, `other` |
| `director_photo_id` | identity | `drivers_license`, `national_id`, `passport`, `pr_card`, `residence_permit` |
| `business_address` | address | `bank_statement`, `business_registration`, `proof_of_address`, `utility_bill` |
| `board_resolution` | entity | `board_resolution`, `other` |
| `financial_statements` | entity | `financial_statements`, `other` |
| `partnership_agreement` | entity | `other`, `partnership_agreement` |
| `trust_deed` | entity | `other`, `trust_deed` |
| `trustee_photo_id` | identity | `drivers_license`, `national_id`, `passport`, `pr_card`, `residence_permit` |
| `settlor_id` | identity | `drivers_license`, `national_id`, `passport`, `pr_card`, `residence_permit` |
| `beneficiary_list` | entity | `beneficiary_list`, `other` |
| `trust_address` | address | `bank_statement`, `proof_of_address`, `utility_bill` |
| `trust_tax_id` | entity | tous (pas de filtre de type) |
| `trust_financial_statements` | entity | `financial_statements`, `other` |
| `estate_authority` | entity | `estate_authority`, `other` |
| `liquidator_id` | identity | `drivers_license`, `national_id`, `passport`, `pr_card`, `residence_permit` |
| `ein_letter` | entity | `business_registration`, `other` |
| `good_standing` | entity | `business_registration`, `other` |
| `registre_commerce` | entity | `business_registration`, `other` |
| `statuts` | entity | `articles_of_incorporation`, `bylaws`, `other` |
| `manager_cin` | identity | `drivers_license`, `national_id`, `passport`, `pr_card`, `residence_permit` |
| `attestation_ice` | entity | `business_registration`, `other` |
| `attestation_if` | entity | `business_registration`, `other` |
| `cni_ci` | identity | `drivers_license`, `national_id`, `passport`, `pr_card`, `residence_permit` |
| `iban_ci` | entity | tous (pas de filtre de type) |
| `cni_sn` | identity | `drivers_license`, `national_id`, `passport`, `pr_card`, `residence_permit` |
| `iban_sn` | entity | tous (pas de filtre de type) |
| `cin_tn` | identity | `drivers_license`, `national_id`, `passport`, `pr_card`, `residence_permit` |
| `iban_tn` | entity | tous (pas de filtre de type) |
| `nid_eg` | identity | `drivers_license`, `national_id`, `passport`, `pr_card`, `residence_permit` |
| `iban_eg` | entity | tous (pas de filtre de type) |
| `nid_sa` | identity | `drivers_license`, `national_id`, `passport`, `pr_card`, `residence_permit` |
| `iban_sa` | entity | tous (pas de filtre de type) |
| `rccm_extract` | entity | `business_registration`, `other` |
| `dfe_ci` | entity | `business_registration`, `other` |
| `manager_id` | identity | `drivers_license`, `national_id`, `passport`, `pr_card`, `residence_permit` |
| `ninea_sn` | entity | `business_registration`, `other` |
| `rne_extract_tn` | entity | `business_registration`, `other` |
| `mf_tn` | entity | `business_registration`, `other` |
| `beneficial_ownership_tn` | entity | `beneficial_ownership`, `other` |
| `cr_eg` | entity | `business_registration`, `other` |
| `tax_card_eg` | entity | `business_registration`, `other` |
| `cr_sa` | entity | `business_registration`, `other` |
| `vat_sa` | entity | `business_registration`, `other` |
| `proof_of_address_abroad` | address | `bank_statement`, `proof_of_address`, `utility_bill` |

Une étape marquée `address` est une étape de justificatif de domicile. Une `utility_bill`, un `proof_of_address` ou un `bank_statement` lu à cet endroit subit un contrôle de récence bloquant (critical, 90 jours par défaut). Sur toute autre étape, le même contrôle est un warning.

## Contrôles de format par pays

Warnings seulement. Un numéro mal formé est plus souvent une erreur de lecture qu'un faux, donc aucun de ces contrôles ne bloque un fichier.

| Document | Contrôle | S'applique à |
| - | - | - |
| CIN marocaine | `format:cin:` 1 ou 2 lettres puis 5 à 7 chiffres | `national_id` avec le pays `MA` |
| Permis de conduire | `format:licence:` par province ou État ; une juridiction sans règle est signalée comme non contrôlée | `drivers_license` |
| Permis de l'Ontario | `consistency:licence:` le numéro concorde avec le nom de famille et la date de naissance | `drivers_license`, ON |
| Carte d'identité nationale | contrôles de style `format:national_id` pour la Côte d'Ivoire, le Sénégal, la Tunisie, l'Égypte, l'Arabie saoudite (les numéros égyptiens et saoudiens encodent aussi la date de naissance, le sexe ou le statut de citoyen) | `national_id`, `residence_permit` |
| IBAN | `format:iban:` | tout document qui renvoie un `iban` |
| Numéros d'entreprise | `format:ice`, `format:if_number`, `format:rc` (Maroc) ; `format:business_number` (Canada) ; `format:ein` (États-Unis) ; `format:registration_number`, `format:tax_id` (CI, SN, TN, EG, SA) | `/verify` sur un profil d'entité |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.