> ## Documentation Index > Fetch the complete documentation index at: https://docs.didit.me/llms.txt > Use this file to discover all available pages before exploring further. # Justificatif de domicile : avertissements, codes d'erreur > Codes d'avertissement de justificatif de domicile Didit : discordance de nom, document expiré, métadonnées. Configurez le refus automatique. ## Vue d'ensemble La vérification de justificatif de domicile (POA) émet des avertissements sur `poa_verifications[].warnings[]` pour chaque problème de qualité, d'authenticité ou de correspondance détecté lors de l'extraction et de l'analyse forensique. Chaque avertissement est un [objet Warning](https://docs.didit.me/fr/reference/data-models.md#objet-d’avertissement) avec `feature` défini sur `"PROOF_OF_ADDRESS"`. Une poignée de risques force systématiquement le statut `Declined` ; les autres suivent une action par risque (`DECLINE` / `REVIEW` / `NO_ACTION`) configurée sur votre workflow. Chaque risque ci-dessous est vérifié par rapport au pipeline de décision en production ; les chaînes exactes de description courte et longue sont reproduites textuellement dans les tableaux. > [!NOTE] > > L'extraction POA introduit une latence de **5 à 15 secondes** par document. Les avertissements ne sont écrits que lorsque l'étape du workflow est terminée ; n'interrogez pas plus souvent qu'une fois toutes les 5 s. ## Deux parcours en production Les avertissements POA sont générés sur deux parcours différents, et l'ensemble des risques diffère selon le parcours : * **Sessions de workflow** (l'étape POA au sein d'une session de vérification) — l'endpoint de téléversement exécute d'abord une validation bloquante avec une boucle de réessai (voir [Comportement de réessai](#comportement-des-réessais-sessions-de-workflow)), puis les avertissements finaux enregistrés sont calculés par `check_poa_risks` ainsi que par la vérification du nom entre plusieurs documents. * **API autonome** (`POST /v3/poa/`) — les avertissements proviennent uniquement de `check_poa_risks`. Il n'y a pas de boucle de réessai, pas de contexte d'identité vérifiée et un seul document, donc `NAME_MISMATCH_ID_VERIFICATION`, `POA_NAME_MISMATCH_BETWEEN_DOCUMENTS`, `POA_MAX_ATTEMPTS_EXCEEDED` et `FUTURE_ISSUE_DATE` ne sont **jamais** générés par l'API autonome. Les erreurs de validation préalables à l'extraction sont ignorées sur ce parcours. `POOR_DOCUMENT_QUALITY` est défini dans l'enum des risques et réservé dans le mappage des actions, mais **aucun chemin de code dans le pipeline POA ne le produit** — il n'apparaît jamais dans `warnings[]` sur aucun des deux parcours. Ne créez pas de logique conditionnelle basée sur celui-ci. ## Avertissements de refus automatique (forcent toujours `Declined`) Ces risques font partie de `AUTO_DECLINE_RISKS` ; lorsqu'ils sont consignés, le statut POA est `Declined` quelle que soit la configuration, et `log_type` est toujours `error`. | Risque | Cause | Résolution recommandée | | - | - | - | | `MISSING_ADDRESS_INFORMATION` | Aucune adresse n'a pu être extraite du document. | Demandez à l'utilisateur de soumettre à nouveau un document indiquant clairement son adresse. | | `POA_DOCUMENT_EXPIRED` | Le document est expiré selon l'un des deux cas : sa **date d'expiration imprimée** est dépassée, ou il est **plus ancien que l'âge maximal configuré** pour son type. Valeurs par défaut : **3 mois** pour `UTILITY_BILL` et `BANK_STATEMENT`, **12 mois** pour `GOVERNMENT_ISSUED_DOCUMENT` et `OTHER_POA_DOCUMENT` (un mois compte pour 30 jours ; `-1` désactive la vérification). `additional_data` contient toujours `expiration_reason` (`printed_expiration` ou `age_window`), `document_type`, `document_subtype` et `issue_date` ; le cas `printed_expiration` ajoute `expiration_date`, et le cas `age_window` ajoute `max_age_months`. | Demandez à l'utilisateur un document valide ou plus récent, ou augmentez `age_months` pour ce type. | | `INVALID_DOCUMENT_TYPE` | Le document n'a pu être classé dans aucun type de POA pris en charge (`document_type` est défini par défaut sur `UNKNOWN`). | Demandez à l'utilisateur de le soumettre à nouveau ; vérifiez que le fichier n'est pas corrompu. | | `UNABLE_TO_VALIDATE_DOCUMENT_AGE` | La vérification de l'âge du document a elle-même échoué (erreur lors du calcul de l'expiration à partir de la date de délivrance). | Demandez à l'utilisateur un document comportant une date de délivrance clairement lisible. | `FUTURE_ISSUE_DATE` figure également dans `AUTO_DECLINE_RISKS`, mais il ne possède qu'un seul émetteur dans la validation préalable à l'extraction (une date de délivrance située à plus de 7 jours dans le futur) dont les erreurs alimentent uniquement la **boucle de réessai du workflow** — il apparaît sous la forme d'une erreur de téléversement bloquante à cet endroit, n'est jamais produit par l'API autonome et n'est pas écrit dans `warnings[]`. Voir [Comportement de réessai](#comportement-des-réessais-sessions-de-workflow). ## Avertissements configurables Chacun de ces avertissements dépend d'un paramètre d'action du nœud POA du workflow (`DECLINE` / `REVIEW` / `NO_ACTION`). Le `log_type` de l'avertissement reflète l'action configurée : `error` pour Refuser, `warning` pour Examen manuel, `information` pour Aucune action. | Risque | Cause | Paramètre d'action | Valeur par défaut | | - | - | - | - | | `NAME_MISMATCH_WITH_PROVIDED` | Le nom figurant sur le document obtient un score inférieur à `poa_name_match_score_threshold` (par défaut 86) par rapport au nom fourni à la création de la session (`expected_details`). | `poa_name_or_address_mismatch_action` | Examen manuel | | `NAME_MISMATCH_ID_VERIFICATION` | Le nom figurant sur le document obtient un score inférieur au seuil par rapport au document d'identité vérifié. `additional_data` : `{ poa_name, kyc_name, match_score }`. Uniquement pour les sessions de workflow. | `poa_name_or_address_mismatch_action` | Examen manuel | | `ADDRESS_MISMATCH_WITH_PROVIDED` | L'adresse extraite diffère de l'adresse fournie via l'API, ou l'une des deux adresses n'a pas pu être vérifiée comme adresse résidentielle. | `poa_name_or_address_mismatch_action` | Examen manuel | | `POA_COUNTRY_MISMATCH_WITH_PROVIDED` | Le pays du document ne correspond pas au pays fourni via l'API (normalisé au format ISO-3). `additional_data` : `{ expected_country, extracted_country }`. | `poa_name_or_address_mismatch_action` | Examen manuel | | `POA_NAME_MISMATCH_BETWEEN_DOCUMENTS` | Deux documents de justificatif de domicile ou plus dans la même session portent des noms différents. `additional_data` inclut les identifiants des deux nœuds, les deux noms et le score de correspondance. Uniquement pour les sessions de workflow. | `poa_name_or_address_mismatch_action` | Examen manuel | | `DOCUMENT_METADATA_MISMATCH` | Le fichier est vide (`file_size` à 0) ou ses dates EXIF sont mal formées. | `poa_document_issues_action` | Examen manuel | | `SUSPECTED_DOCUMENT_MANIPULATION` | L'analyse forensique a relevé des indices de manipulation : modification après signature électronique (`is_tampered`), manipulation du texte superposé (avec les rectangles `additional_data.manipulated_regions`), un éditeur PDF connu, des dates EXIF incohérentes ou une réexportation suspecte. `additional_data.detection_method` indique la vérification qui a déclenché l'avertissement. | `poa_document_authenticity_action` | **Refuser** | | `POA_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT` | Un champ de texte a été effacé puis retapé dans une autre police, et le fichier ne contient aucune preuve que son contenu a changé : les éditeurs en ligne retapent aussi le texte non modifié. Cet avertissement ne déclenche jamais `SUSPECTED_DOCUMENT_MANIPULATION` à lui seul ; si un autre signal déclenche ce dernier sur le même document, c'est l'action la plus stricte des deux qui s'applique. `additional_data.detection_method` vaut `unproven_text_replacement`, avec `replaced_text` et `manipulated_regions`. Un fichier qui n'a pas pu être analysé dans son intégralité déclenche aussi cet avertissement, car la partie non analysée peut contenir un tel champ : `detection_method` vaut alors `analysis_incomplete`, avec `replaced_text` et `manipulated_regions` vides, sauf si un champ a été trouvé dans la partie analysée. | `poa_document_unproven_text_replacement_action` | Examen manuel | | `UNSUPPORTED_DOCUMENT_LANGUAGE` | La langue du document ne figure pas dans `poa_languages_allowed`. | `poa_unsupported_language_action` | **Refuser** | | `POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION` | Le type de document détecté n'est pas activé dans `poa_documents_allowed` pour le pays du document, ou son sous-type est explicitement désactivé. | `poa_unsupported_document_type_action` | **Refuser** | | `ISSUER_NOT_IDENTIFIED` | L'établissement émetteur n'a pas pu être identifié à partir du document. | `poa_issuer_not_identified_action` | Examen manuel | | `UNABLE_TO_EXTRACT_ISSUE_DATE` | Aucune date d'émission valide n'a pu être trouvée sur le document. | `poa_issue_date_not_detected_action` | Examen manuel | | `POA_NAME_NOT_DETECTED` | Aucun nom n'a été détecté sur le document. | `poa_issue_date_not_detected_action` (paramètre partagé) | Examen manuel | | `UNPARSABLE_OR_INVALID_ADDRESS` | Une adresse a été extraite mais n'a pas pu être analysée ni géocodée en adresse résidentielle valide. | `poa_unparsable_or_invalid_address_action` | Examen manuel | | `POA_MAX_ATTEMPTS_EXCEEDED` | L'utilisateur a épuisé `poa_max_retry_attempts` (par défaut 2) dans la boucle de réessai du workflow. `additional_data` : `{ attempts }`. Uniquement pour les sessions de workflow. | `poa_max_attempts_exceeded_action` | **Refuser** | > [!NOTE] > > Il existe **une seule action partagée** pour tous les écarts de nom et d'adresse : `poa_name_or_address_mismatch_action` couvre les deux risques liés au nom, les deux risques liés à l'adresse et la vérification croisée des noms entre documents. Vous ne pouvez pas configurer séparément le comportement en cas d'écart de nom et le comportement en cas d'écart d'adresse. Sur l'API autonome, le même groupe est régi par l'option de requête `poa_address_mismatch_action` (l'option `poa_name_mismatch_action` est acceptée mais n'est jamais lue). ## Différences avec l'API autonome (`POST /v3/poa/`) L'endpoint autonome établit la même correspondance entre risques et actions, mais avec des options au niveau de la requête qui n'acceptent que `DECLINE` ou `NO_ACTION` (toutes définies sur `DECLINE` par défaut) : * `UNABLE_TO_EXTRACT_ISSUE_DATE` et `POA_NAME_NOT_DETECTED` sont **codés en dur sur Refuser** sur cet endpoint. * `POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION` et `UNPARSABLE_OR_INVALID_ADDRESS` sont **informatifs** ici — leurs actions sont définies par défaut sur Aucune action et ne sont pas configurables par requête. * `FUTURE_ISSUE_DATE`, `POOR_DOCUMENT_QUALITY`, `NAME_MISMATCH_ID_VERIFICATION`, `POA_NAME_MISMATCH_BETWEEN_DOCUMENTS` et `POA_MAX_ATTEMPTS_EXCEEDED` ne sont jamais générés — un document portant une date future n'est **pas** automatiquement refusé sur cet endpoint. Consultez la [référence de l'API POST /v3/poa/](https://docs.didit.me/fr/standalone-apis/proof-of-address.md) pour connaître les options de requête. ## Comportement des réessais (sessions de workflow) Dans une session de vérification, l'étape de téléversement du POA exécute une validation bloquante avant que le document ne soit accepté. Lorsqu'elle détecte une erreur bloquante — `INVALID_DOCUMENT_TYPE`, `UNABLE_TO_EXTRACT_ISSUE_DATE`, `FUTURE_ISSUE_DATE`, `POA_NAME_NOT_DETECTED`, `MISSING_ADDRESS_INFORMATION`, `POA_COUNTRY_MISMATCH_WITH_PROVIDED`, `POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION`, `UNSUPPORTED_DOCUMENT_LANGUAGE` ou `POA_DOCUMENT_EXPIRED` — le téléversement est rejeté avec un code `400` et le code de risque en guise de message, et l'utilisateur peut réessayer avec un meilleur document. Pour `POA_DOCUMENT_EXPIRED`, le corps du `400` inclut également `expiration_reason` (`printed_expiration` ou `age_window`) afin que votre interface utilisateur puisse afficher la raison exacte ; sur le chemin `age_window`, il inclut en plus `max_age_months`. Sur le chemin `printed_expiration`, `max_age_months` est intentionnellement omis, car le document a été rejeté en raison de sa date d'expiration imprimée plutôt que d'une fenêtre d'ancienneté. Une fois que l'utilisateur a épuisé ses tentatives `poa_max_retry_attempts` (par défaut 2, configurable de 2 à 5), la soumission est acceptée malgré tout : les avertissements stockés sont recalculés à partir du document enregistré, `POA_MAX_ATTEMPTS_EXCEEDED` est ajouté, et le statut est déterminé à partir de l'ensemble complet des risques. C'est pourquoi `FUTURE_ISSUE_DATE` peut bloquer un téléversement sans jamais apparaître dans `warnings[]`. ## Paramètres configurables Le nœud POA du workflow expose ces réglages (correspondant aux champs de `VerificationSettings`) : | Paramètre | Contrôle | Valeur par défaut | | - | - | - | | `poa_name_or_address_mismatch_action` | `NAME_MISMATCH_WITH_PROVIDED`, `NAME_MISMATCH_ID_VERIFICATION`, `ADDRESS_MISMATCH_WITH_PROVIDED`, `POA_COUNTRY_MISMATCH_WITH_PROVIDED`, `POA_NAME_MISMATCH_BETWEEN_DOCUMENTS` | Review | | `poa_document_issues_action` | `DOCUMENT_METADATA_MISMATCH` | Review | | `poa_document_authenticity_action` | `SUSPECTED_DOCUMENT_MANIPULATION` | Decline | | `poa_document_unproven_text_replacement_action` | `POA_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT` | Review (un workflow qui ne passe jamais en examen utilise son propre `poa_document_authenticity_action` si celui-ci est Decline, sinon No action ; l'API autonome suit le `poa_document_authenticity_action` de la requête) | | `poa_unsupported_language_action` | `UNSUPPORTED_DOCUMENT_LANGUAGE` | Decline | | `poa_unsupported_document_type_action` | `POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION` | Decline | | `poa_issuer_not_identified_action` | `ISSUER_NOT_IDENTIFIED` | Review | | `poa_issue_date_not_detected_action` | `UNABLE_TO_EXTRACT_ISSUE_DATE`, `POA_NAME_NOT_DETECTED` | Review | | `poa_unparsable_or_invalid_address_action` | `UNPARSABLE_OR_INVALID_ADDRESS` | Review | | `poa_max_attempts_exceeded_action` | `POA_MAX_ATTEMPTS_EXCEEDED` | Decline | | `poa_documents_allowed` | Types de documents acceptés par pays, chacun avec `enabled` et `age_months` (`-1` = illimité) ; dérogations par sous-type via `document_subtypes_config`. | Facture de services publics et relevé bancaire : 3 mois ; documents délivrés par le gouvernement et autres documents : 12 mois | | `poa_languages_allowed` | Langues de documents acceptées. | Toutes les langues prises en charge | | `poa_name_match_score_threshold` | Score minimal de correspondance du nom (0–100) avant que les risques `NAME_MISMATCH*` ne se déclenchent. | 86 | | `poa_max_retry_attempts` | Tentatives de téléversement avant que la boucle de réessai n'abandonne (2–5). | 2 | ## Logique de correspondance des noms La correspondance des noms pour les justificatifs de domicile tolère les variations courantes : * **Deuxièmes prénoms et initiales** font l'objet d'une correspondance souple (la présence/absence est autorisée). * **Noms candidats** — chaque nom détecté sur le document (`name_on_document` ainsi que `additional_names`) reçoit un score, et le candidat obtenant le meilleur score est conservé. * **Seuil de correspondance** — la valeur par défaut de `poa_name_match_score_threshold` est **86** ; un score inférieur déclenche l'avertissement `NAME_MISMATCH*` correspondant. Les scores numériques sont exposés sur le rapport sous la forme `name_match_score_expected_details` et `name_match_score_id_verification` (0–100). Les valeurs de score sont utiles pour un examen approfondi même lorsqu'aucun avertissement n'a été émis. ## Exemples ### Manipulation par superposition (Decline par défaut) ```json theme={null} { "warnings": [ { "feature": "PROOF_OF_ADDRESS", "risk": "SUSPECTED_DOCUMENT_MANIPULATION", "additional_data": { "reason": "Overlay-text manipulation detected: same base font embedded with multiple subset prefixes on 1 page(s).", "detection_method": "overlay_text_manipulation", "signals": ["duplicate_font_subset", "glyph_fragmentation"], "duplicate_font_subsets": [{ "page": 1, "base_font": "Helvetica" }], "fragmented_fonts": [], "manipulated_regions": [ { "page": 1, "x": 102.4, "y": 318.1, "width": 187.0, "height": 18.0, "page_width": 595, "page_height": 842 } ] }, "log_type": "error", "short_description": "Suspected document manipulation", "long_description": "The system detected signs of potential document manipulation or editing.", "node_id": "feature_poa_1" } ] } ``` ### Document expiré + adresse manquante (refus automatique) ```json theme={null} { "warnings": [ { "feature": "PROOF_OF_ADDRESS", "risk": "POA_DOCUMENT_EXPIRED", "additional_data": { "expiration_reason": "age_window", "max_age_months": 3, "document_subtype": "ELECTRICITY_BILL", "document_type": "UTILITY_BILL", "issue_date": "2025-11-02" }, "log_type": "error", "short_description": "Document expired", "long_description": "The submitted document is older than the maximum accepted age of 3 months from its issue date, which exceeds the acceptable time period for validity.", "node_id": "feature_poa_1" }, { "feature": "PROOF_OF_ADDRESS", "risk": "MISSING_ADDRESS_INFORMATION", "additional_data": null, "log_type": "error", "short_description": "Missing address information", "long_description": "The document does not contain complete or clear address information that can be extracted.", "node_id": "feature_poa_1" } ] } ``` ### Non-concordance de nom (Review par défaut) ```json theme={null} { "warnings": [ { "feature": "PROOF_OF_ADDRESS", "risk": "NAME_MISMATCH_ID_VERIFICATION", "additional_data": { "poa_name": "JOHN B SMYTH", "kyc_name": "John A. Smith", "match_score": 60 }, "log_type": "warning", "short_description": "Name mismatch with ID verification", "long_description": "The full name on the document does not match the name from the user's verified identity documents.", "node_id": "feature_poa_1" } ] } ``` ## Ressources associées * [Rapport de justificatif de domicile](https://docs.didit.me/fr/core-technology/proof-of-address/report-proof-of-address.md) — format complet de la réponse, analyse forensique de la manipulation par superposition, sémantique des statuts * [Présentation du justificatif de domicile](https://docs.didit.me/fr/core-technology/proof-of-address/overview.md) — types de documents acceptés * [Modèles de données — Justificatif de domicile](https://docs.didit.me/fr/reference/data-models.md#justificatif-de-domicile) — schéma canonique et objet Warning * [Webhooks](https://docs.didit.me/fr/integration/webhooks.md) — `status.updated` transmet les avertissements de POA ### Types d'avertissements This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.