> ## Documentation Index > Fetch the complete documentation index at: https://docs.didit.me/llms.txt > Use this file to discover all available pages before exploring further. # Report di verifica NFC: dati del chip e autenticità > Didit include nel report di verifica NFC: dati del chip, autenticità dei certificati, stato e payload di esempio nelle risposte API. ## 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)](#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](https://docs.didit.me/it/sessions-api/retrieve-session.md). * **Webhook** — i payload di `status.updated` includono lo stesso array `nfc_verifications[]` non appena il passaggio NFC ha prodotto dati. Consulta [Webhook](https://docs.didit.me/it/integration/webhooks.md). * **NFC autonomo** — per l'invio diretto del chip, consulta la [Panoramica su NFC](https://docs.didit.me/it/core-technology/nfc-verification/overview.md). 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](https://docs.didit.me/it/core-technology/nfc-verification/warnings-nfc-verification.md#motivi-di-esclusione) per i valori esatti. > [!NOTE] > > 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](https://docs.didit.me/it/reference/data-models.md#verifica-nfc). 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](https://docs.didit.me/it/core-technology/nfc-verification/warnings-nfc-verification.md#motivi-di-esclusione). | | `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](#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](https://docs.didit.me/it/core-technology/nfc-verification/warnings-nfc-verification.md). | ## 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. | > [!NOTE] > > 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](https://docs.didit.me/it/core-technology/nfc-verification/warnings-nfc-verification.md) per la matrice di comportamento completa. ## Esempi ### Approved — chip letto e crittograficamente valido ```json theme={null} { "nfc_verifications": [ { "status": "Approved", "node_id": "nfc_primary", "portrait_image": "https:///.../epassport/_face.jpg?signature=...", "signature_image": "https:///.../epassport/_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/.../epassport/_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 [!WARNING] > > 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 ```json theme={null} { "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](https://docs.didit.me/it/core-technology/nfc-verification/warnings-nfc-verification.md#japan-my-number-card-jpki). ## 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](https://docs.didit.me/it/core-technology/nfc-verification/warnings-nfc-verification.md) — enum completa degli avvisi, cause e risoluzione. * [Webhook](https://docs.didit.me/it/integration/webhooks.md) — ascolta l'evento `status.updated` per ricevere il report NFC. * [Modelli di dati — Verifica NFC](https://docs.didit.me/it/reference/data-models.md#verifica-nfc) — schema canonico con tutti i campi. * [Documenti supportati](https://docs.didit.me/it/core-technology/nfc-verification/supported-documents-nfc-verification.md) — quali documenti elettronici Didit può leggere tramite NFC. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.