Adressnachweis: Warnungen und Fehlercodes

​

Übersicht

​

Zwei Produktionspfade

• Workflow-Sitzungen (der POA-Schritt innerhalb einer Verifizierungssitzung) – der Upload-Endpoint führt zunächst eine blockierende Validierung mit einer Wiederholungsschleife aus (siehe Wiederholungsverhalten), danach werden die endgültig gespeicherten Warnungen durch check_poa_risks plus den dokumentenübergreifenden Namensabgleich berechnet.
• Eigenständige API (POST /v3/poa/) – Warnungen stammen ausschließlich aus check_poa_risks. Es gibt weder eine Wiederholungsschleife noch einen Kontext zu einem verifizierten Ausweis und nur ein einziges Dokument, sodass NAME_MISMATCH_ID_VERIFICATION, POA_NAME_MISMATCH_BETWEEN_DOCUMENTS, POA_MAX_ATTEMPTS_EXCEEDED und FUTURE_ISSUE_DATE von der eigenständigen API nie erzeugt werden. Die Validierungsfehler vor der Extraktion werden auf diesem Pfad verworfen.

​

Warnungen mit automatischer Ablehnung (erzwingen immer Declined)

​

Konfigurierbare Warnungen

​

Unterschiede der Standalone-API (POST /v3/poa/)

• UNABLE_TO_EXTRACT_ISSUE_DATE und POA_NAME_NOT_DETECTED sind an diesem Endpoint fest auf Ablehnen gesetzt.
• POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION und UNPARSABLE_OR_INVALID_ADDRESS sind hier informativ – ihre Aktionen sind standardmäßig auf Keine Aktion gesetzt und können nicht pro Anfrage konfiguriert werden.
• FUTURE_ISSUE_DATE, POOR_DOCUMENT_QUALITY, NAME_MISMATCH_ID_VERIFICATION, POA_NAME_MISMATCH_BETWEEN_DOCUMENTS und POA_MAX_ATTEMPTS_EXCEEDED werden nie erzeugt – ein Dokument mit einem Datum in der Zukunft wird an diesem Endpoint nicht automatisch abgelehnt.

​

Verhalten bei Wiederholungsversuchen (Workflow-Sitzungen)

​

Konfigurierbare Einstellungen

​

Logik für den Namensabgleich

• Zweitnamen und Initialen werden tolerant abgeglichen (Vorhandensein/Fehlen ist zulässig).
• Kandidatennamen – Jeder auf dem Dokument erkannte Name (name_on_document zuzüglich additional_names) wird bewertet, und der Kandidat mit dem höchsten Übereinstimmungswert wird beibehalten.
• Übereinstimmungs-Schwellenwert – Der Standardwert für poa_name_match_score_threshold ist 86; ein Wert darunter löst die entsprechende NAME_MISMATCH*-Warnung aus.

​

Beispiele

​

Overlay-Manipulation (standardmäßig: Ablehnung)

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

​

Abgelaufenes Dokument + fehlende Adresse (automatische Ablehnung)

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

​

Namensabweichung (standardmäßig Prüfung)

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

​

Verwandte Themen

• Adressnachweis-Bericht – Vollständige Antwortstruktur, Forensik bei Overlay-Manipulation, Statussemantik
• Adressnachweis – Übersicht – Akzeptierte Dokumenttypen
• Datenmodelle – Adressnachweis – Kanonisches Schema und Warnungsobjekt
• Webhooks – status.updated übermittelt POA-Warnungen

​

Warnungstypen