Prova di residenza: avvisi e codici di errore

​

Panoramica

​

Due percorsi di produzione

• Sessioni di workflow (il passaggio POA all’interno di una sessione di verifica): l’endpoint di caricamento esegue innanzitutto una validazione bloccante con un ciclo di nuovi tentativi (vedi Comportamento dei nuovi tentativi), quindi gli avvisi finali memorizzati vengono calcolati da check_poa_risks insieme al controllo del nome su più documenti.
• API autonoma (POST /v3/poa/): gli avvisi provengono esclusivamente da check_poa_risks. Non è presente alcun ciclo di nuovi tentativi, né contesto dell’ID verificato e vi è un solo documento; pertanto NAME_MISMATCH_ID_VERIFICATION, POA_NAME_MISMATCH_BETWEEN_DOCUMENTS, POA_MAX_ATTEMPTS_EXCEEDED e FUTURE_ISSUE_DATE non vengono mai generati dall’API autonoma. Gli errori di validazione pre-estrazione vengono scartati in questo percorso.

​

Avvisi con rifiuto automatico (impongono sempre Declined)

​

Avvisi configurabili

​

Differenze dell’API standalone (POST /v3/poa/)

• UNABLE_TO_EXTRACT_ISSUE_DATE e POA_NAME_NOT_DETECTED sono impostati rigidamente su Rifiuta su questo endpoint.
• POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION e UNPARSABLE_OR_INVALID_ADDRESS sono informativi in questo caso; le loro azioni sono predefinite su Nessuna azione e non sono configurabili per richiesta.
• FUTURE_ISSUE_DATE, POOR_DOCUMENT_QUALITY, NAME_MISMATCH_ID_VERIFICATION, POA_NAME_MISMATCH_BETWEEN_DOCUMENTS e POA_MAX_ATTEMPTS_EXCEEDED non vengono mai generati; un documento con data futura non viene rifiutato automaticamente su questo endpoint.

​

Comportamento dei tentativi (sessioni di workflow)

​

Impostazioni configurabili

​

Logica di corrispondenza del nome

• Secondi nomi e iniziali vengono confrontati con tolleranza (la presenza/assenza è consentita).
• Nomi candidati — ogni nome rilevato sul documento (name_on_document più additional_names) riceve un punteggio e viene mantenuto il candidato con il punteggio migliore.
• Soglia di corrispondenza — la soglia predefinita poa_name_match_score_threshold è 86; un punteggio inferiore attiva il relativo avviso NAME_MISMATCH*.

​

Esempi

​

Manipolazione tramite overlay (Rifiuto per impostazione predefinita)

{
  "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"
    }
  ]
}

​

Documento scaduto + indirizzo mancante (rifiuto automatico)

{
  "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"
    }
  ]
}

​

Mancata corrispondenza del nome (Revisione per impostazione predefinita)

{
  "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"
    }
  ]
}

​

Correlati

• Report della prova di residenza — formato completo della risposta, analisi forense delle manipolazioni tramite overlay, semantica dello stato
• Panoramica sulla prova di residenza — tipi di documenti accettati
• Modelli di dati — Prova di residenza — schema canonico e oggetto Warning
• Webhook — status.updated include gli avvisi della POA

​

Tipi di avviso