Justificatif de domicile : avertissements, codes d'erreur

​

Vue d’ensemble

​

Deux parcours en production

• 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), 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.

​

Avertissements de refus automatique (forcent toujours Declined)

​

Avertissements configurables

​

Différences avec l’API autonome (POST /v3/poa/)

• 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.

​

Comportement des réessais (sessions de workflow)

​

Paramètres configurables

​

Logique de correspondance des noms

• 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.

​

Exemples

​

Manipulation par superposition (Decline par défaut)

{
  "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)

{
  "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)

{
  "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 — format complet de la réponse, analyse forensique de la manipulation par superposition, sémantique des statuts
• Présentation du justificatif de domicile — types de documents acceptés
• Modèles de données — Justificatif de domicile — schéma canonique et objet Warning
• Webhooks — status.updated transmet les avertissements de POA

​

Types d’avertissements