Report di verifica NFC: dati del chip e autenticità

Panoramica

Il report di verifica NFC acquisisce ciò che Didit ha letto e convalidato dal chip NFC di un documento: un passaporto elettronico (ePassport), una carta d’identità elettronica o un altro documento elettronico conforme a ICAO 9303. Include i dati anagrafici del chip, i controlli di integrità crittografica (hash di SOD e Data Group) e un riepilogo del Document Signer Certificate (DSC) utilizzato dal paese di emissione. Il report viene generato dopo che l’utente ha completato il passaggio NFC in un workflow. Didit legge i Data Group del chip sul dispositivo dell’utente, verifica la firma del Document Security Object (SOD) rispetto al certificato CSCA del paese di emissione, confronta l’hash di ciascun Data Group con i valori firmati dal SOD ed esegue un controllo incrociato tra la MRZ del chip e la MRZ rilevata tramite OCR dal lato visibile del documento. La My Number Card giapponese viene invece letta tramite JPKI (chip_protocol: "jpki"): il suo report include i controlli su certificato, firma, revoca e dati del titolare sotto jpki, mentre i campi ICAO rimangono null. Consulta Japan My Number Card (JPKI). Ciascun report presenta un proprio status — indipendente dallo stato generale della sessione — che riflette l’esito del solo passaggio NFC:

Approvato — il chip è stato letto e nessuno degli avvisi attivati è configurato per instradare il passaggio a revisione o rifiuto.
In revisione — si è attivato almeno un avviso la cui azione configurata è Revisione (ad esempio NFC_CHIP_NOT_VERIFIED o NFC_TRUST_ANCHOR_MISSING quando l’azione per chip non verificato è impostata su Revisione, oppure JPKI_REVOCATION_UNCHECKED con la sua azione predefinita).
Rifiutato — si è attivato almeno un avviso la cui azione configurata è Rifiuta (ad esempio NFC_AND_OCR_DATA_NOT_SAME quando l’azione per incongruenza dei dati è impostata su Rifiuta).
Non completato — l’utente non ha mai completato il passaggio NFC; la lettura del chip è stata abbandonata o il dispositivo non supportava l’NFC.
Nuovo invio richiesto — un revisore ha richiesto all’utente di ripetere l’invio; il report verrà sostituito da un nuovo tentativo.

Dove compare nelle risposte API

Il report NFC viene fornito all’interno dell’array nfc_verifications[] — sempre un array JSON, mai un singolo oggetto nfc. Voci multiple compaiono quando un workflow esegue l’NFC più di una volta (ad esempio in un flusso step-up); ciascuna voce include il proprio node_id.

API di decisione della sessione — compare come nfc_verifications[] al livello principale di GET /v3/session/{sessionId}/decision/. Consulta Recupera la decisione della sessione.
Webhook — i payload di status.updated includono lo stesso array nfc_verifications[] non appena il passaggio NFC ha prodotto dati. Consulta Webhook.
NFC autonomo — per l’invio diretto del chip, consulta la Panoramica su NFC.

Quando il tuo workflow include un passaggio NFC che è stato saltato o ignorato, il payload della decisione contiene anche un campo di livello principale nfc_skip_reason che indica esattamente il motivo: il documento non ha un chip, il certificato del paese di emissione non è disponibile, il dispositivo non dispone di un lettore NFC, la verifica è stata eseguita senza un SDK nativo (nessun accesso NFC da browser), non è stato possibile ricavare la chiave di accesso al chip dalla MRZ, non è stato possibile leggere una My Number Card tramite JPKI oppure l’utente ha scelto di saltare il passaggio. Rimane null per gli esiti non inclusi in questa tassonomia, più comunemente nel caso in cui un utente abbia abbandonato a metà del tentativo (stato del report Not Finished) o in una sessione in cui l’NFC è ancora in sospeso. Consulta Motivi di esclusione per i valori esatti.

La documentazione precedente faceva riferimento a un singolo campo nfc. Tale formato non esiste sull’endpoint di decisione v3: compare solo nelle destinazioni esplicitamente configurate sui webhook V2, dove include anche chip_protocol e jpki. Leggi sempre response.nfc_verifications[0] e itera sull’array.

Schema

Lo schema canonico campo per campo si trova nella pagina di riferimento Modelli di dati. I campi sottostanti rispecchiano tale schema canonico.

Campo	Tipo	Descrizione
`status`	`"Not Finished" \| "Approved" \| "Declined" \| "In Review" \| "Resub Requested"`	Stato del passaggio NFC (vedi i significati sopra).
`node_id`	string \| null	Nodo del grafo del workflow che ha generato questo report. Ti consente di distinguere due controlli NFC in un workflow a più passaggi.
`is_nfc_skipped`	boolean	`true` quando questo passaggio NFC è stato esplicitamente saltato anziché essere letto.
`skip_reason`	string \| null	Motivo per cui il passaggio è stato saltato — impostato solo quando `is_nfc_skipped` è `true`. Stessi valori di `nfc_skip_reason` a livello di sessione; vedi Motivi per il salto.
`chip_protocol`	`"icao"` \| `"jpki"`	Modalità di lettura del chip. `icao`: chip ICAO 9303 di passaporto elettronico o carta d’identità elettronica. `jpki`: Japan My Number Card, il cui risultato si trova sotto `jpki`; i campi ICAO sottostanti (`portrait_image`, `signature_image`, `chip_data`, `authenticity`, `certificate_summary`) sono quindi `null`. Viene impostato anche per i passaggi saltati.
`jpki`	object \| null	Ciò che la lettura della My Number Card ha dimostrato; vedi Campi JPKI. `null` per i chip ICAO, per i passaggi saltati e quando il passaggio si è chiuso senza alcuna lettura della carta.
`portrait_image`	stringa (URL firmato) \| null	Ritratto estratto dal chip (DG2). Link pre-firmato di breve durata — scaricalo tempestivamente; richiedi nuovamente la decisione per ottenere un URL aggiornato.
`signature_image`	stringa (URL firmato) \| null	Immagine della firma del titolare dal chip (DG7), se presente. Lo stesso comportamento vale per il link pre-firmato di breve durata.
`chip_data`	object \| null	Oggetto semplice con i dati anagrafici analizzati dal chip. Sempre presente dopo una lettura riuscita: `dgs` (elenco dei gruppi di dati letti), `surname`, `name`, `country`, `nationality`, `birth_date` (`YYYY-MM-DD`), `expiry_date` (`YYYY-MM-DD`), `sex` (`M`/`F`), `document_type` (codice del documento MRZ, ad es. `P`), `document_number`, `optional_data`, le cifre di controllo MRZ (`birth_date_hash`, `expiry_date_hash`, `document_number_hash`, `optional_data_hash`, `final_hash`), `mrz_string` e `mrz_type` (`TD1`/`TD2`/`TD3`). Quando il chip contiene il DG11, vengono aggiunti `place_of_birth` e `address` (e `full_name` / `full_name_non_latin` per i documenti con un nome non latino); in caso contrario, queste chiavi sono assenti, non null. `null` quando il passaggio NFC è stato saltato.
`authenticity`	object \| null	Risultati dell’autenticazione passiva ICAO, descritti di seguito. `null` per una lettura JPKI.
`authenticity.sod_integrity`	boolean	`true` quando la firma del SOD forma una catena fino a una CSCA valida del paese di emissione e il DSC non è né revocato né scaduto.
`authenticity.dg_integrity`	boolean	`true` quando l’hash di ogni gruppo di dati corrisponde al valore firmato dal SOD. Un valore `false` indica che i dati del chip sono stati manomessi o letti parzialmente.
`certificate_summary`	object \| null	Riepilogo del DSC che ha firmato questo chip: `issuer`, `subject`, `serial_number`, `not_valid_before`, `not_valid_after` (timestamp nel formato `YYYY-MM-DD HH:MM:SS`), oltre a un oggetto `validation` con i risultati dei singoli controlli (`csca_verified`, `csca_missing`, `dsc_revoked`, `dsc_expired`, `csca_expired`). `csca_missing` è `true` quando l’ancora di attendibilità della CSCA di emissione del DSC non è disponibile. `null` quando non è stato possibile caricare il SOD o il passaggio è stato saltato.
`warnings[]`	array	Avvisi a livello di modulo, ciascuno con `feature`, `risk`, `additional_data`, `log_type`, `short_description`, `long_description` e `node_id` — vedi Avvisi NFC.

Valori di status

Status	Significato	Effetto a valle
`Approved`	Chip letto e nessun avviso attivato con un’azione Review o Decline — compreso il caso in cui siano stati generati avvisi la cui azione configurata è “No action”.	Conta come un controllo NFC riuscito; di per sé, non metterà la sessione in revisione.
`In Review`	Si è attivato un avviso la cui azione configurata è Review (`SKIPPED_NFC_VALIDATION`, `NFC_CHIP_NOT_VERIFIED`, `NFC_TRUST_ANCHOR_MISSING`, `NFC_AND_OCR_DATA_NOT_SAME` o uno degli avvisi `JPKI_*`, a seconda delle tue impostazioni).	Anche la sessione passa a `In Review` finché un revisore non interviene.
`Declined`	Si è attivato un avviso la cui azione configurata è Decline.	La sessione viene rifiutata a meno che un altro ramo approvato non soddisfi il workflow.
`Not Finished`	L’utente ha abbandonato il passaggio NFC, il dispositivo non supportava l’NFC oppure la lettura del chip non è mai stata completata.	Il ramo NFC non ha prodotto un risultato; verifica i fallback del workflow.
`Resub Requested`	Un revisore ha richiesto il reinvio di questo passaggio.	Un nuovo tentativo sostituisce questo report non appena l’utente riprova.

I due avvisi relativi al certificato (DSC_CERTIFICATE_REVOKED, DSC_CERTIFICATE_EXPIRED) sono informativi: compaiono in warnings[] ma di per sé non modificano mai lo status NFC. Vedi Avvisi NFC per la matrice di comportamento completa.

Esempi

Approved — chip letto e crittograficamente valido

{
  "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 — mancata corrispondenza tra OCR e 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)

Una Japan My Number Card viene letta tramite JPKI negli SDK nativi: la persona inserisce il PIN della carta e la carta firma una sfida monouso (vedi come funziona). Il relativo report presenta chip_protocol: "jpki" e riporta le prove sotto jpki. portrait_image, signature_image, chip_data, authenticity e certificate_summary sono null, poiché la carta non contiene dati ICAO.

La lettura delle My Number Card tramite JPKI non è ancora abilitata in produzione. Fino a quel momento, una My Number Card salta il passaggio NFC con motivo di esclusione JPKI_UNAVAILABLE.

Campi JPKI

Campo	Tipo	Descrizione
`jpki.certificate_types`	array di `"user_authentication"` \| `"signature"`	I certificati della carta letti. `user_authentication` (PIN a 4 cifre) viene sempre letto; `signature` (PIN di firma) viene letto quando l’impostazione `jpki_request_attributes` del nodo NFC è attiva, che è l’impostazione predefinita.
`jpki.chain_valid`	boolean	`true` quando ogni certificato forma una catena fino all’autorità di certificazione JPKI del rispettivo tipo, rientra nel proprio periodo di validità ed è un certificato My Number Card di quel tipo.
`jpki.signature_valid`	boolean	`true` quando ogni firma generata dalla carta sulla sfida monouso risulta verificata. La carta firma solo dopo l’inserimento del relativo PIN, dimostrando quindi che la persona è in possesso della carta e ne conosce il PIN.
`jpki.revocation_status`	`"good"` \| `"revoked"` \| `"unchecked"`	`good`: è confermato che nessun certificato è revocato. `revoked`: un certificato è revocato, ad esempio perché la carta è stata segnalata come smarrita. `unchecked`: non è stata disponibile alcuna risposta sulla revoca, pertanto non è possibile escludere una carta revocata; non viene mai trattato come `good`. La revoca viene verificata solo dopo che la catena e la firma risultano valide.
`jpki.ca_generation`	string \| null	Generazione dell’autorità di certificazione JPKI che ha emesso i certificati, ad esempio `"2023"`. `null` quando nessun certificato forma una catena fino a un’autorità di certificazione JPKI.
`jpki.certificate_expires_at`	string (ISO 8601) \| null	La scadenza più ravvicinata tra i certificati letti.
`jpki.certificates[]`	array	Una voce per ciascun certificato letto: `type`, `chain_valid`, `signature_valid`, `ca_generation`, `not_valid_before`, `not_valid_after` e `failure`. `failure` è `null` quando la catena è valida, altrimenti uno tra `unreadable_certificate`, `untrusted_issuer`, `expired`, `not_yet_valid`, `wrong_policy` (non è un certificato My Number Card di quel tipo) o `key_usage`.
`jpki.attributes`	object \| null	I dati del titolare provenienti dal certificato di firma, una volta che la relativa catena è valida: `full_name` (come registrato, solitamente nel sistema di scrittura giapponese), `date_of_birth` (`YYYY-MM-DD`), `gender` (`M`, `F` o `null`), `address` e `name_substitute_characters` / `address_substitute_characters`, che indicano i caratteri sostituiti poiché esterni al set di caratteri standard (`null` se nessuno è stato sostituito). `null` quando il certificato di firma non è stato richiesto o la sua catena non è valida.
`jpki.attributes_match_ocr`	boolean \| null	`true` quando gli attributi corrispondono ai dati letti dalla foto della stessa carta, `false` quando uno qualsiasi differisce (`JPKI_AND_OCR_DATA_NOT_SAME`), `null` quando non è stato possibile confrontare nulla, anche quando `attributes` è `null`.
`jpki.mismatched_attributes`	array di string	Gli attributi che differiscono dai dati della foto (`full_name`, `date_of_birth`, `gender`, `address`), mai i rispettivi valori.

Il report non include mai i certificati stessi, i relativi numeri di serie, le firme o il Numero Individuale (My Number) a 12 cifre della carta, che il passaggio NFC non legge mai.

Esempio: lettura di 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": []
    }
  ]
}

Se il controllo di revoca non è disponibile per una lettura, lo stesso report presenta revocation_status: "unchecked", un avviso JPKI_REVOCATION_UNCHECKED e status: "In Review" con le impostazioni predefinite. Vedi Avvisi NFC.

Nota sulla sicurezza

I dati del chip NFC sono firmati dall’autorità di emissione, pertanto un report approvato con sod_integrity: true e dg_integrity: true costituisce la prova d’identità più solida che Didit possa produrre. Tratta gli URL firmati delle immagini (portrait_image, signature_image) come temporanei: scaricali tempestivamente e non memorizzarli pubblicamente nella cache; richiedi nuovamente la decisione quando hai bisogno di link aggiornati.

Contenuti correlati

Avvisi NFC — enum completa degli avvisi, cause e risoluzione.
Webhook — ascolta l’evento status.updated per ricevere il report NFC.
Modelli di dati — Verifica NFC — schema canonico con tutti i campi.
Documenti supportati — quali documenti elettronici Didit può leggere tramite NFC.

Autenticazione

Verifica

Monitoraggio

Piattaforma

Report di verifica NFC: dati del chip e autenticità

Panoramica

Dove compare nelle risposte API

Schema

Valori di status

Esempi

Approved — chip letto e crittograficamente valido

Declined — mancata corrispondenza tra OCR e chip

Japan My Number Card (JPKI)

Campi JPKI

Esempio: lettura di My Number Card

Nota sulla sicurezza

Contenuti correlati

​Panoramica

​Dove compare nelle risposte API

​Schema

​Valori di status

​Esempi

​Approved — chip letto e crittograficamente valido

​Declined — mancata corrispondenza tra OCR e chip

​Japan My Number Card (JPKI)

​Campi JPKI

​Esempio: lettura di My Number Card

​Nota sulla sicurezza

​Contenuti correlati

Panoramica

Dove compare nelle risposte API

Schema

Valori di status

Esempi

Approved — chip letto e crittograficamente valido

Declined — mancata corrispondenza tra OCR e chip

Japan My Number Card (JPKI)

Campi JPKI

Esempio: lettura di My Number Card

Nota sulla sicurezza

Contenuti correlati