NFC-Verifizierungsbericht: Chip-Daten & Authentizität

Übersicht

Der NFC-Verifizierungsbericht erfasst, was Didit aus dem NFC-Chip eines Dokuments ausgelesen und validiert hat – einem ePass, einem elektronischen Personalausweis oder einem anderen elektronischen Dokument nach ICAO 9303. Er enthält die biografischen Daten des Chips, kryptografische Integritätsprüfungen (SOD- und Data-Group-Hashes) sowie eine Zusammenfassung des vom Ausstellungsland verwendeten Document Signer Certificate (DSC). Der Bericht wird erstellt, nachdem der Benutzer den NFC-Schritt in einem Workflow abgeschlossen hat. Didit liest die Data Groups des Chips auf dem Gerät des Benutzers aus, verifiziert die Signatur des Document Security Object (SOD) anhand des CSCA-Zertifikats des Ausstellungslands, vergleicht jeden Data-Group-Hash mit den durch das SOD signierten Werten und gleicht die MRZ des Chips mit der MRZ ab, die per OCR von der sichtbaren Seite des Dokuments erfasst wurde. Eine Japan My Number Card wird stattdessen über JPKI ausgelesen (chip_protocol: "jpki"): Ihr Bericht enthält die Zertifikats-, Signatur-, Sperr- und Inhaberdatenprüfungen unter jpki, und die ICAO-Felder bleiben null. Siehe Japan My Number Card (JPKI). Jeder Bericht enthält einen eigenen status – unabhängig vom Gesamtstatus der Sitzung –, der widerspiegelt, wie der NFC-Schritt allein entschieden wurde:

Genehmigt – der Chip wurde ausgelesen und keine der ausgelösten Warnungen ist so konfiguriert, dass der Schritt zur Prüfung weitergeleitet oder abgelehnt wird.
In Prüfung – mindestens eine Warnung wurde ausgelöst, deren konfigurierte Aktion Prüfung ist (beispielsweise NFC_CHIP_NOT_VERIFIED oder NFC_TRUST_ANCHOR_MISSING, wenn die Aktion für nicht verifizierte Chips auf Überprüfung gesetzt ist, oder JPKI_REVOCATION_UNCHECKED mit der Standardaktion).
Abgelehnt – mindestens eine Warnung wurde ausgelöst, deren konfigurierte Aktion Ablehnung ist (beispielsweise NFC_AND_OCR_DATA_NOT_SAME, wenn die Aktion bei Dateninkonsistenz auf Ablehnen gesetzt ist).
Nicht abgeschlossen – der Benutzer hat den NFC-Schritt nie abgeschlossen; das Auslesen des Chips wurde abgebrochen oder das Gerät unterstützte kein NFC.
Erneute Einreichung angefordert – ein Prüfer hat den Benutzer um eine erneute Einreichung gebeten; der Bericht wird durch einen neuen Versuch ersetzt.

Wo er in API-Antworten erscheint

Der NFC-Bericht wird innerhalb des Arrays nfc_verifications[] bereitgestellt – immer ein JSON-Array, niemals ein einzelnes nfc-Objekt. Mehrere Einträge erscheinen, wenn ein Workflow NFC mehr als einmal ausführt (beispielsweise in einem Step-up-Flow); jeder Eintrag enthält seine eigene node_id.

Sitzungsentscheidungs-API – erscheint als nfc_verifications[] auf oberster Ebene von GET /v3/session/{sessionId}/decision/. Siehe Sitzungsentscheidung abrufen.
Webhooks – status.updated-Payloads enthalten dasselbe Array nfc_verifications[], sobald der NFC-Schritt Daten erzeugt hat. Siehe Webhooks.
Eigenständiges NFC – zur direkten Chipeinreichung siehe die NFC-Übersicht.

Wenn Ihr Workflow einen NFC-Schritt enthält, der übersprungen oder umgangen wurde, enthält die Entscheidungs-Payload auf oberster Ebene auch ein Feld nfc_skip_reason, das genau angibt, warum – das Dokument hat keinen Chip, das Zertifikat des Ausstellungslands ist nicht verfügbar, das Gerät hat keinen NFC-Leser, die Verifizierung wurde ohne natives SDK ausgeführt (kein NFC-Zugriff über einen Browser), der Chip-Zugangsschlüssel konnte nicht aus der MRZ abgeleitet werden, eine My Number Card konnte nicht über JPKI ausgelesen werden oder der Benutzer hat sich entschieden zu überspringen. Es bleibt null für Ergebnisse außerhalb dieser Taxonomie – am häufigsten ein Benutzer, der mitten im Versuch abgebrochen hat (Berichtsstatus Not Finished), oder eine Sitzung, in der NFC noch aussteht. Siehe Überspringen-Gründe für die genauen Werte.

In älterer Dokumentation wurde ein einzelnes Feld nfc referenziert. Diese Struktur existiert auf dem v3-Entscheidungs-Endpoint nicht – sie erscheint nur bei Zielen, die explizit auf V2-Webhooks festgelegt sind, wo sie auch chip_protocol und jpki enthält. Lesen Sie immer response.nfc_verifications[0] aus und iterieren Sie über das Array.

Schema

Das kanonische Feld-für-Feld-Schema befindet sich auf der Referenzseite Datenmodelle. Die folgenden Felder spiegeln dieses kanonische Schema wider.

Feld	Typ	Beschreibung
`status`	`"Not Finished" \| "Approved" \| "Declined" \| "In Review" \| "Resub Requested"`	Status des NFC-Schritts (Bedeutungen siehe oben).
`node_id`	string \| null	Workflow-Graph-Knoten, der diesen Bericht erzeugt hat. Ermöglicht die Unterscheidung zweier NFC-Prüfungen in einem mehrstufigen Workflow.
`is_nfc_skipped`	boolean	`true`, wenn dieser NFC-Schritt explizit übersprungen statt ausgelesen wurde.
`skip_reason`	string \| null	Grund, warum der Schritt übersprungen wurde – nur gesetzt, wenn `is_nfc_skipped` gleich `true` ist. Dieselben Werte wie beim sitzungsbezogenen `nfc_skip_reason`; siehe Gründe für das Überspringen.
`chip_protocol`	`"icao"` \| `"jpki"`	Wie der Chip ausgelesen wird. `icao`: ein ICAO-9303-ePassport- oder eID-Chip. `jpki`: eine Japan My Number Card, deren Ergebnis unter `jpki` liegt; die nachstehenden ICAO-Felder (`portrait_image`, `signature_image`, `chip_data`, `authenticity`, `certificate_summary`) sind dann `null`. Wird auch bei übersprungenen Schritten gesetzt.
`jpki`	object \| null	Was das Auslesen einer My Number Card nachgewiesen hat; siehe JPKI-Felder. `null` für ICAO-Chips, für übersprungene Schritte und wenn der Schritt geschlossen wurde, ohne dass eine Karte ausgelesen wurde.
`portrait_image`	string (signierte URL) \| null	Aus dem Chip extrahiertes Porträt (DG2). Kurzlebiger vorsignierter Link – laden Sie ihn zeitnah herunter; rufen Sie die Entscheidung erneut ab, um eine neue URL zu erhalten.
`signature_image`	string (signierte URL) \| null	Unterschriftsbild des Inhabers vom Chip (DG7), sofern vorhanden. Für vorsignierte URLs gilt ebenfalls eine kurze Gültigkeitsdauer.
`chip_data`	object \| null	Flaches Objekt mit den aus dem Chip geparsten biografischen Daten. Nach erfolgreichem Auslesen immer vorhanden: `dgs` (Liste der ausgelesenen Datengruppen), `surname`, `name`, `country`, `nationality`, `birth_date` (`YYYY-MM-DD`), `expiry_date` (`YYYY-MM-DD`), `sex` (`M`/`F`), `document_type` (MRZ-Dokumentencode, z. B. `P`), `document_number`, `optional_data`, die MRZ-Prüfziffern (`birth_date_hash`, `expiry_date_hash`, `document_number_hash`, `optional_data_hash`, `final_hash`), `mrz_string` und `mrz_type` (`TD1`/`TD2`/`TD3`). Wenn der Chip DG11 enthält, werden `place_of_birth` und `address` hinzugefügt (sowie `full_name` / `full_name_non_latin` bei Dokumenten mit nicht-lateinischem Namen); andernfalls sind diese Schlüssel nicht vorhanden, nicht null. `null`, wenn der NFC-Schritt übersprungen wurde.
`authenticity`	object \| null	Ergebnisse der passiven ICAO-Authentifizierung, siehe unten. `null` bei einem JPKI-Lesevorgang.
`authenticity.sod_integrity`	boolean	`true`, wenn die SOD-Signatur zu einer gültigen CSCA des Ausstellungslandes führt und das DSC weder widerrufen noch abgelaufen ist.
`authenticity.dg_integrity`	boolean	`true`, wenn der Hash jeder Datengruppe mit dem vom SOD signierten Wert übereinstimmt. Ein `false`-Wert bedeutet, dass die Chipdaten manipuliert oder unvollständig ausgelesen wurden.
`certificate_summary`	object \| null	Zusammenfassung des DSC, das diesen Chip signiert hat: `issuer`, `subject`, `serial_number`, `not_valid_before`, `not_valid_after` (Zeitstempel als `YYYY-MM-DD HH:MM:SS`), plus ein `validation`-Objekt mit den einzelnen Prüfergebnissen (`csca_verified`, `csca_missing`, `dsc_revoked`, `dsc_expired`, `csca_expired`). `csca_missing` ist `true`, wenn der Trust-Anchor der ausstellenden CSCA nicht verfügbar ist. `null`, wenn das SOD nicht geladen werden konnte oder der Schritt übersprungen wurde.
`warnings[]`	array	Warnungen auf Modulebene, jeweils mit `feature`, `risk`, `additional_data`, `log_type`, `short_description`, `long_description` und `node_id` – siehe NFC-Warnungen.

Statuswerte

Status	Bedeutung	Nachgelagerte Auswirkung
`Approved`	Chip ausgelesen und keine Warnung mit der Aktion Prüfung oder Ablehnung ausgelöst – einschließlich des Falls, dass Warnungen ausgelöst wurden, deren konfigurierte Aktion jedoch “Keine Aktion” lautet.	Gilt als erfolgreiche NFC-Prüfung; führt für sich allein genommen nicht dazu, dass die Sitzung in Prüfung geht.
`In Review`	Es wurde eine Warnung ausgelöst, deren konfigurierte Aktion Prüfung ist (`SKIPPED_NFC_VALIDATION`, `NFC_CHIP_NOT_VERIFIED`, `NFC_TRUST_ANCHOR_MISSING`, `NFC_AND_OCR_DATA_NOT_SAME` oder eine der `JPKI_*`-Warnungen, abhängig von Ihren Einstellungen).	Die Sitzung wechselt ebenfalls zu `In Review`, bis ein Prüfer reagiert.
`Declined`	Es wurde eine Warnung ausgelöst, deren konfigurierte Aktion Ablehnung ist.	Die Sitzung wird abgelehnt, es sei denn, eine andere genehmigte Verzweigung erfüllt den Workflow.
`Not Finished`	Der Benutzer hat den NFC-Schritt abgebrochen, das Gerät verfügte über keine NFC-Unterstützung oder das Auslesen des Chips wurde nie abgeschlossen.	Die NFC-Verzweigung hat kein Ergebnis geliefert; prüfen Sie die Workflow-Fallbacks.
`Resub Requested`	Ein Prüfer hat die erneute Einreichung dieses Schritts angefordert.	Ein neuer Versuch ersetzt diesen Bericht, sobald der Benutzer es erneut versucht.

Die beiden Zertifikatswarnungen (DSC_CERTIFICATE_REVOKED, DSC_CERTIFICATE_EXPIRED) sind rein informativ: Sie erscheinen in warnings[], ändern jedoch den NFC-status niemals von selbst. Siehe NFC-Warnungen für die vollständige Verhaltensmatrix.

Beispiele

Approved – Chip ausgelesen und kryptografisch gültig

{
  "nfc_verifications": [
    {
      "status": "Approved",
      "node_id": "nfc_primary",
      "portrait_image": "https://<media-host>/.../epassport/<session-id>_face.jpg?signature=...",
      "signature_image": "https://<media-host>/.../epassport/<session-id>_signature.jpg?signature=...",
      "chip_data": {
        "dgs": ["DG1", "DG2", "DG7", "DG11"],
        "surname": "DOE",
        "name": "JOHN",
        "country": "ESP",
        "nationality": "ESP",
        "birth_date": "1990-05-15",
        "expiry_date": "2030-01-01",
        "sex": "M",
        "document_type": "P",
        "document_number": "AAB000123",
        "optional_data": "",
        "birth_date_hash": "4",
        "expiry_date_hash": "7",
        "document_number_hash": "3",
        "optional_data_hash": "",
        "final_hash": "4",
        "mrz_string": "P<ESPDOE<<JOHN<<<<<<<<<<<<<<<<<<<<<<<<<<<<<AAB000123ESP9005154M3001017<<<<<<<<<<<<<<04",
        "mrz_type": "TD3",
        "place_of_birth": "MADRID, MADRID",
        "address": "CALLE MAYOR 1, MADRID"
      },
      "is_nfc_skipped": false,
      "skip_reason": null,
      "authenticity": {
        "sod_integrity": true,
        "dg_integrity": true
      },
      "certificate_summary": {
        "issuer": "Common Name: CSCA SPAIN, Serial Number: 3, Organization: DIRECCION GENERAL DE LA POLICIA, Country: ES",
        "subject": "Common Name: DS n-eID SPAIN 2, Organizational Unit: PASSPORT, Organization: DIRECCION GENERAL DE LA POLICIA, Country: ES",
        "not_valid_before": "2020-11-18 10:21:11",
        "not_valid_after": "2031-02-18 10:21:11",
        "serial_number": 118120836164494130086420187336801405660,
        "validation": {
          "csca_verified": true,
          "dsc_revoked": false,
          "dsc_expired": false,
          "csca_expired": false
        }
      },
      "warnings": []
    }
  ]
}

Declined – Nichtübereinstimmung zwischen OCR und Chip

{
  "nfc_verifications": [
    {
      "status": "Declined",
      "node_id": "nfc_primary",
      "portrait_image": "https://<media-host>/.../epassport/<session-id>_face.jpg?signature=...",
      "signature_image": null,
      "chip_data": {
        "dgs": ["DG1", "DG2"],
        "surname": "DOE",
        "name": "JOHN",
        "country": "ESP",
        "nationality": "ESP",
        "birth_date": "1990-05-15",
        "expiry_date": "2030-01-01",
        "sex": "M",
        "document_type": "P",
        "document_number": "AAB000254",
        "optional_data": "",
        "birth_date_hash": "4",
        "expiry_date_hash": "7",
        "document_number_hash": "6",
        "optional_data_hash": "",
        "final_hash": "6",
        "mrz_string": "P<ESPDOE<<JOHN<<<<<<<<<<<<<<<<<<<<<<<<<<<<<AAB000254ESP9005154M3001017<<<<<<<<<<<<<<06",
        "mrz_type": "TD3"
      },
      "is_nfc_skipped": false,
      "skip_reason": null,
      "authenticity": {
        "sod_integrity": true,
        "dg_integrity": true
      },
      "certificate_summary": {
        "issuer": "Common Name: CSCA SPAIN, Serial Number: 3, Organization: DIRECCION GENERAL DE LA POLICIA, Country: ES",
        "subject": "Common Name: DS n-eID SPAIN 2, Organizational Unit: PASSPORT, Organization: DIRECCION GENERAL DE LA POLICIA, Country: ES",
        "not_valid_before": "2020-11-18 10:21:11",
        "not_valid_after": "2031-02-18 10:21:11",
        "serial_number": 118120836164494130086420187336801405660,
        "validation": {
          "csca_verified": true,
          "dsc_revoked": false,
          "dsc_expired": false,
          "csca_expired": false
        }
      },
      "warnings": [
        {
          "feature": "NFC",
          "risk": "NFC_AND_OCR_DATA_NOT_SAME",
          "additional_data": {
            "ocr_mrz": ["P<ESPDOE<<JOHN<<<<<<<<<<<<<<<<<<<<<<<<<<<<<", "AAB000123ESP9005154M3001017<<<<<<<<<<<<<<04"],
            "nfc_mrz": "P<ESPDOE<<JOHN<<<<<<<<<<<<<<<<<<<<<<<<<<<<<AAB000254ESP9005154M3001017<<<<<<<<<<<<<<06"
          },
          "log_type": "error",
          "short_description": "NFC and OCR data not same",
          "long_description": "The Near Field Communication (NFC) chip data and the OCR data don't match, indicating potential document tampering or data inconsistency.",
          "node_id": "nfc_primary"
        }
      ]
    }
  ]
}

Japan My Number Card (JPKI)

Eine japanische My Number Card wird in nativen SDKs über JPKI ausgelesen: Die Person gibt die Karten-PIN ein und die Karte signiert eine Einmal-Challenge (siehe Funktionsweise). Der Bericht enthält chip_protocol: "jpki" und führt die Nachweise unter jpki auf. portrait_image, signature_image, chip_data, authenticity und certificate_summary sind null, da die Karte keine ICAO-Daten enthält.

Das Auslesen von My Number Cards über JPKI ist in der Produktion noch nicht aktiviert. Bis dies der Fall ist, überspringt eine My Number Card den NFC-Schritt mit dem Grund für das Überspringen JPKI_UNAVAILABLE.

JPKI-Felder

Feld	Typ	Beschreibung
`jpki.certificate_types`	Array aus `"user_authentication"` \| `"signature"`	Die ausgelesenen Kartenzertifikate. `user_authentication` (4-stellige PIN) wird immer ausgelesen; `signature` (Signatur-PIN) wird ausgelesen, wenn die Einstellung `jpki_request_attributes` des NFC-Knotens aktiviert ist, was dem Standard entspricht.
`jpki.chain_valid`	boolean	`true`, wenn jedes Zertifikat bis zur JPKI-Zertifizierungsstelle seines Typs zurückreicht, innerhalb seiner Gültigkeitsdauer liegt und ein Zertifikat einer My Number Card dieses Typs ist.
`jpki.signature_valid`	boolean	`true`, wenn jede Signatur, die die Karte über die Einmal-Challenge erstellt hat, erfolgreich verifiziert wird. Die Karte signiert erst nach Eingabe ihrer PIN, was beweist, dass die Person im Besitz der Karte ist und die PIN kennt.
`jpki.revocation_status`	`"good"` \| `"revoked"` \| `"unchecked"`	`good`: Jedes Zertifikat ist nachweislich nicht widerrufen. `revoked`: Ein Zertifikat ist widerrufen, beispielsweise weil die Karte als verloren gemeldet wurde. `unchecked`: Es war keine Antwort zum Widerrufsstatus verfügbar, daher kann eine widerrufene Karte nicht ausgeschlossen werden; wird niemals als `good` behandelt. Der Widerruf wird erst geprüft, sobald die Kette und die Signatur gültig sind.
`jpki.ca_generation`	string \| null	Generation der JPKI-Zertifizierungsstelle, die die Zertifikate ausgestellt hat, beispielsweise `"2023"`. `null`, wenn kein Zertifikat auf eine solche zurückgeführt werden kann.
`jpki.certificate_expires_at`	string (ISO 8601) \| null	Das früheste Ablaufdatum unter den ausgelesenen Zertifikaten.
`jpki.certificates[]`	Array	Ein Eintrag pro ausgelesenem Zertifikat: `type`, `chain_valid`, `signature_valid`, `ca_generation`, `not_valid_before`, `not_valid_after` und `failure`. `failure` ist `null`, wenn die Kette gültig ist, andernfalls einer der Werte `unreadable_certificate`, `untrusted_issuer`, `expired`, `not_yet_valid`, `wrong_policy` (kein Zertifikat einer My Number Card dieses Typs) oder `key_usage`.
`jpki.attributes`	object \| null	Die Daten des Inhabers aus dem Signaturzertifikat, sobald dessen Kette gültig ist: `full_name` (wie registriert, üblicherweise im japanischen Schriftsystem), `date_of_birth` (`YYYY-MM-DD`), `gender` (`M`, `F` oder `null`), `address` sowie `name_substitute_characters` / `address_substitute_characters`, die Zeichen markieren, die durch ein Ersatzzeichen ersetzt wurden, da sie außerhalb des Standardzeichensatzes liegen (`null`, wenn keine ersetzt wurden). `null`, wenn das Signaturzertifikat nicht angefordert wurde oder dessen Kette nicht gültig ist.
`jpki.attributes_match_ocr`	boolean \| null	`true`, wenn die Attribute mit den aus dem Foto derselben Karte ausgelesenen Daten übereinstimmen, `false`, wenn eines davon abweicht (`JPKI_AND_OCR_DATA_NOT_SAME`), `null`, wenn nichts verglichen werden konnte, auch dann, wenn `attributes` `null` ist.
`jpki.mismatched_attributes`	Array aus Zeichenketten	Die Attribute, die von den Fotodaten abweichen (`full_name`, `date_of_birth`, `gender`, `address`), niemals deren Werte.

Der Bericht enthält niemals die Zertifikate selbst, deren Seriennummern, die Signaturen oder die 12-stellige Individual Number (My Number) der Karte, die der NFC-Schritt niemals ausliest.

Beispiel: Auslesen einer My Number Card

{
  "nfc_verifications": [
    {
      "status": "Approved",
      "node_id": "nfc_primary",
      "portrait_image": null,
      "signature_image": null,
      "chip_data": null,
      "is_nfc_skipped": false,
      "skip_reason": null,
      "chip_protocol": "jpki",
      "jpki": {
        "certificate_types": ["user_authentication", "signature"],
        "chain_valid": true,
        "signature_valid": true,
        "revocation_status": "good",
        "ca_generation": "2023",
        "certificate_expires_at": "2029-05-15T14:59:59Z",
        "certificates": [
          {
            "type": "user_authentication",
            "chain_valid": true,
            "signature_valid": true,
            "ca_generation": "2023",
            "not_valid_before": "2024-06-03T01:12:40+00:00",
            "not_valid_after": "2029-05-15T14:59:59+00:00",
            "failure": null
          },
          {
            "type": "signature",
            "chain_valid": true,
            "signature_valid": true,
            "ca_generation": "2023",
            "not_valid_before": "2024-06-03T01:12:40+00:00",
            "not_valid_after": "2029-05-15T14:59:59+00:00",
            "failure": null
          }
        ],
        "attributes": {
          "full_name": "山田 太郎",
          "date_of_birth": "1990-05-15",
          "gender": "M",
          "address": "東京都千代田区千代田1番1号",
          "name_substitute_characters": null,
          "address_substitute_characters": null
        },
        "attributes_match_ocr": true,
        "mismatched_attributes": []
      },
      "authenticity": null,
      "certificate_summary": null,
      "warnings": []
    }
  ]
}

Ist die Widerrufsprüfung für einen Lesevorgang nicht verfügbar, weist derselbe Bericht unter den Standardeinstellungen revocation_status: "unchecked", eine JPKI_REVOCATION_UNCHECKED-Warnung und status: "In Review" auf. Siehe NFC-Warnungen.

Sicherheitshinweis

NFC-Chipdaten werden von der ausstellenden Behörde signiert, weshalb ein genehmigter Bericht mit sod_integrity: true und dg_integrity: true den stärkstmöglichen Identitätsnachweis darstellt, den Didit erbringen kann. Behandeln Sie die signierten Bild-URLs (portrait_image, signature_image) als kurzlebig: Laden Sie sie zeitnah herunter und cachen Sie sie nicht öffentlich — fordern Sie die Entscheidung erneut an, wenn Sie frische Links benötigen.

Authentifizierung

Verifizierung

Überwachung

Plattform

NFC-Verifizierungsbericht: Chip-Daten & Authentizität

Übersicht

Wo er in API-Antworten erscheint

Schema

Statuswerte

Beispiele

Approved – Chip ausgelesen und kryptografisch gültig

Declined – Nichtübereinstimmung zwischen OCR und Chip

Japan My Number Card (JPKI)

JPKI-Felder

Beispiel: Auslesen einer My Number Card

Sicherheitshinweis

Verwandte Themen

​Übersicht

​Wo er in API-Antworten erscheint

​Schema

​Statuswerte

​Beispiele

​Approved – Chip ausgelesen und kryptografisch gültig

​Declined – Nichtübereinstimmung zwischen OCR und Chip

​Japan My Number Card (JPKI)

​JPKI-Felder

​Beispiel: Auslesen einer My Number Card

​Sicherheitshinweis

​Verwandte Themen

Übersicht

Wo er in API-Antworten erscheint

Schema

Statuswerte

Beispiele

Approved – Chip ausgelesen und kryptografisch gültig

Declined – Nichtübereinstimmung zwischen OCR und Chip

Japan My Number Card (JPKI)

JPKI-Felder

Beispiel: Auslesen einer My Number Card

Sicherheitshinweis

Verwandte Themen