Zum Hauptinhalt springen

Overview

Warnungen im NFC-Bericht kennzeichnen jeden Zustand, den Didit beim Auslesen und Validieren des Chips festgestellt hat. Sie werden im Array warnings[] jedes Elements in nfc_verifications[] aufgeführt (siehe NFC-Bericht), wobei feature auf "NFC" gesetzt ist. Jeder Eintrag folgt dem gemeinsamen Aufbau des Warnungsobjekts: feature, risk, additional_data, log_type, short_description, long_description, node_id. Jede Warnung hat drei Ebenen:
  1. Der risk-Code – eine stabile Kennung, die Sie in Ihrem Code abgleichen können (die unten aufgeführten Codes).
  2. Der log_type – entweder information, warning oder error. Er wird aus der Aktion abgeleitet, die Ihr Workflow für dieses Risiko konfiguriert: Keine Aktion → information, Überprüfung → warning, Ablehnen → error.
  3. Die Auswirkung auf die Entscheidung – dieselbe konfigurierte Aktion steuert auch den status des NFC-Berichts: Eine Aktion vom Typ „Überprüfung“ setzt ihn auf In Review, eine Aktion vom Typ „Ablehnen“ auf Declined.
Vier NFC-Risiken sind auf diese Weise konfigurierbar (SKIPPED_NFC_VALIDATION, NFC_CHIP_NOT_VERIFIED, NFC_TRUST_ANCHOR_MISSING, NFC_AND_OCR_DATA_NOT_SAME), zuzüglich der fünf Japan My Number Card-Risiken mit jeweils eigener Einstellung. Die beiden Zertifikatsrisiken (DSC_CERTIFICATE_REVOKED, DSC_CERTIFICATE_EXPIRED) sind ausschließlich informativ: Sie weisen stets log_type: "information" auf und ändern den NFC-Status niemals von sich aus. Die vollständige Liste der Risikocodes, die das NFC-Modul erzeugt, finden Sie unten. Es existieren keine weiteren NFC-Risikocodes.

Erzeugte Warnungen

SKIPPED_NFC_VALIDATION schließt NFC_CHIP_NOT_VERIFIED und NFC_TRUST_ANCHOR_MISSING gegenseitig aus: Warnungen zur Chip-Verifizierung werden nur ausgewertet, wenn das Auslesen des Chips nicht übersprungen wurde. Die beiden Warnungen zur Chip-Verifizierung schließen sich ebenfalls gegenseitig aus.

Exakte Beschreibungs-Strings

Die API gibt für jedes Risiko genau diese Strings für short_description und long_description zurück:

Gründe für das Überspringen

SKIPPED_NFC_VALIDATION-Warnungen enthalten additional_data.skip_reason, einen von sieben stabilen Codes, der genau angibt, warum NFC nicht ausgeführt wurde (bei Sitzungen, die vor der Einführung von Gründen für das Überspringen aufgezeichnet wurden, kann additional_data den Wert null haben – behandeln Sie das Feld bei der Verarbeitung historischer Entscheidungen als optional). Dieselbe Taxonomie erscheint auf Sitzungsebene als nfc_skip_reason im Entscheidungs-Payload – einschließlich bei Sitzungen, bei denen NFC überhaupt nicht ausgeführt werden konnte (chiploses Dokument, Web-Integration) und daher kein NFC-Bericht oder keine Warnung existiert.
Ein NFC-Bericht und seine Warnung SKIPPED_NFC_VALIDATION existieren nur dann, wenn der Client den NFC-Schritt erreicht und diesen explizit übersprungen hat (typischerweise USER_SKIPPED oder DEVICE_WITHOUT_NFC, wenn sich der Leser zum Zeitpunkt des Scannens als nicht verfügbar herausstellte). Wurde der NFC-Schritt umgangen, bevor er überhaupt angeboten werden konnte – chiploses Dokument, fehlendes Zertifikat, keine gemeldete NFC-Funktionalität, unlesbarer MRZ-Schlüssel, JPKI nicht verfügbar –, wird kein Bericht und keine Warnung erstellt und der Grund erscheint ausschließlich im Feld nfc_skip_reason auf Sitzungsebene, ohne den Sitzungsstatus zu beeinflussen.

Konfiguration

Drei Workflow-Einstellungen steuern, wie NFC-Warnungen weitergeleitet werden. Jede kann auf Keine Aktion, Überprüfung oder Ablehnen gesetzt werden:
  1. NFC-Überspringen-Aktion (skip_nfc_action) – gilt für SKIPPED_NFC_VALIDATION. Das Überspringen wird Benutzern nur angeboten, wenn allow_nfc_skip aktiviert ist.
  2. Aktion für nicht verifizierten Chip (unverified_chip_action) – gilt sowohl für NFC_CHIP_NOT_VERIFIED als auch für NFC_TRUST_ANCHOR_MISSING, sodass das Verhalten des Sitzungsstatus unverändert bleibt, während der Risiko-Code erklärt, warum die Verifizierung fehlgeschlagen ist.
  3. Aktion bei Dateninkonsistenz (inconsistent_data_action) – gilt für NFC_AND_OCR_DATA_NOT_SAME. Dies ist dieselbe Einstellung für Dateninkonsistenzen, die auch bei der Ausweisverifizierung verwendet wird.
Die beiden DSC_CERTIFICATE_*-Risiken verfügen über keine Aktionseinstellung – sie sind immer rein informativ. Für die Risiken der Japan My Number Card gibt es fünf weitere Einstellungen, die im nächsten Abschnitt aufgeführt sind.

Japan My Number Card (JPKI)

Eine Japan My Number Card wird über JPKI anstelle von ICAO 9303 ausgelesen (chip_protocol: "jpki"), sodass die oben genannten ICAO-Risiken dafür niemals ausgelöst werden. Das Auslesen löst stattdessen diese fünf Risiken aus, jeweils mit einer eigenen Einstellung am NFC-Knoten: Das Überspringen des Auslesens der My Number Card löst SKIPPED_NFC_VALIDATION aus und folgt wie bei jedem Chip skip_nfc_action. Unter Japan My Number Card (JPKI) erfahren Sie, wie das Auslesen funktioniert.
Das Auslesen von My Number Cards über JPKI ist in der Produktion noch nicht aktiviert. Bis dahin überspringt eine My Number Card den NFC-Schritt mit dem Grund für das Überspringen JPKI_UNAVAILABLE und keines dieser Risiken wird ausgelöst.

Beispiele

In Prüfung – Chip konnte nicht verifiziert werden

Hier ist die Aktion für nicht verifizierte Chips auf Review gesetzt, sodass NFC_CHIP_NOT_VERIFIED log_type: "warning" aufweist und der Status des NFC-Berichts In Review lautet. Der Eintrag für das abgelaufene DSC dient rein der Information.

Abgelehnt – Diskrepanz zwischen Chip und OCR

Hier ist die Aktion für Dateninkonsistenzen auf Decline gesetzt, sodass die Warnung log_type: "error" aufweist und der Status des NFC-Berichts Declined lautet. Beachten Sie, dass ocr_mrz ein Array von MRZ-Zeilen ist, während nfc_mrz der einzelne verkettete MRZ-String des Chips ist.

In Prüfung: My Number Card ohne Antwort zur Widerrufsprüfung

Hier behält jpki_revocation_unchecked_action seinen Standardwert Review bei, sodass die Warnung log_type: "warning" aufweist und der Status des NFC-Berichts In Review lautet. Die Karte selbst wurde nachgewiesen: jpki.chain_valid und jpki.signature_valid sind beide true.

Warnungstypen

Jedem Risiko wird basierend auf der Konfiguration Ihrer Anwendung ein Schweregrad zugewiesen. Die drei Schweregrade sind:

Verwandte Themen

  • NFC-Bericht – vollständiges Berichtsschema und Statusangaben.
  • Webhooks – status.updated wird bei Statusänderungen der Sitzung ausgelöst; die Entscheidungs-Payload (einschließlich NFC-Warnungen) wird angehängt, wenn die Sitzung den Status Approved, Declined, In Review oder Abandoned erreicht.
  • Datenmodelle – NFC-Verifizierung – kanonisches Schema mit den einzelnen Feldern.
  • Datenmodelle – Warnungsobjekt – die Struktur jedes Eintrags in warnings[].
Zuletzt geändert am 7. November 2026