Avvisi e codici di errore della verifica NFC

Panoramica

Gli avvisi nel report NFC segnalano ogni condizione riscontrata da Didit durante la lettura e la validazione del chip. Vengono inseriti nell’array warnings[] di ciascun elemento di nfc_verifications[] (consulta il report NFC), con feature impostato su "NFC". Ciascuna voce segue la struttura condivisa dell’oggetto avviso: feature, risk, additional_data, log_type, short_description, long_description, node_id. Ogni avviso presenta tre livelli:

Il codice risk — un identificatore stabile che puoi utilizzare per i confronti nel tuo codice (i codici elencati di seguito).
Il log_type — uno tra information, warning o error. Deriva dall’azione configurata nel tuo workflow per quel rischio: Nessuna azione → information, Revisione → warning, Rifiuta → error.
L’impatto sulla decisione — la stessa azione configurata determina anche lo status del report NFC: un’azione di Revisione lo sposta su In Review, un’azione di rifiuto su Declined.

Quattro rischi NFC sono configurabili in questo modo (SKIPPED_NFC_VALIDATION, NFC_CHIP_NOT_VERIFIED, NFC_TRUST_ANCHOR_MISSING, NFC_AND_OCR_DATA_NOT_SAME), oltre ai cinque rischi della Japan My Number Card, ciascuno con la propria impostazione. I due rischi legati ai certificati (DSC_CERTIFICATE_REVOKED, DSC_CERTIFICATE_EXPIRED) sono esclusivamente informativi: riportano sempre log_type: "information" e non modificano mai lo stato NFC da soli. Il set completo di codici di rischio generati dal modulo NFC è riportato di seguito. Non esistono altri codici di rischio NFC.

Avvisi generati

`risk`	Causa	Gravità (`log_type`)	Influisce sullo stato?	Risoluzione
`SKIPPED_NFC_VALIDATION`	La lettura del chip è stata saltata: il workflow consente di saltarla (`allow_nfc_skip`) e l’utente ha premuto su Salta, oppure il client l’ha saltata perché non è riuscito a leggere l’NFC. Il motivo esatto è registrato in `additional_data.skip_reason` (vedi Motivi del salto) e determina la `long_description` dell’avviso.	Segue l’impostazione dell’azione di salto NFC (`skip_nfc_action`): information / warning / error.	Configurabile: Nessuna azione, Revisione o Rifiuto.	Se la tua policy richiede l’NFC, imposta l’azione di salto su Rifiuta (o disabilita del tutto la possibilità di saltare) e chiedi all’utente di riprovare da un dispositivo dotato di NFC. Altrimenti, lasciala su Nessuna azione per passare alla verifica basata solo su OCR.
`NFC_CHIP_NOT_VERIFIED`	Il chip è stato letto ma non ha superato la verifica crittografica per un motivo diverso da un’ancora di attendibilità mancante esplicitamente identificata. L’hash di un Data Group, la firma del SOD o un altro controllo di autenticazione passiva non hanno superato la verifica.	Segue l’impostazione dell’azione per chip non verificato (`unverified_chip_action`).	Configurabile: Nessuna azione, Revisione o Rifiuto.	Trattalo come un chip potenzialmente non valido o manomesso. Ispeziona `authenticity` e `certificate_summary.validation` per vedere quale controllo non è riuscito.
`NFC_TRUST_ANCHOR_MISSING`	Il Document Signer Certificate (DSC) del chip appartiene a una generazione di Country Signing Certification Authority (CSCA) non disponibile nell’archivio delle autorità attendibili di Didit (`certificate_summary.validation.csca_missing` è `true`). Di conseguenza, Didit non può stabilire la catena di attendibilità del SOD.	Segue l’impostazione dell’azione per chip non verificato (`unverified_chip_action`).	Configurabile: Nessuna azione, Revisione o Rifiuto.	Si tratta di un divario di copertura dell’archivio delle autorità attendibili, non della prova che il chip sia stato manomesso. Rivedi il documento tramite i tuoi controlli di fallback e contatta l’assistenza Didit indicando il paese di emissione in modo da poter analizzare la CSCA mancante.
`NFC_AND_OCR_DATA_NOT_SAME`	La MRZ letta dal chip non corrisponde alla MRZ rilevata tramite OCR dal lato visibile del documento (confrontate dopo la normalizzazione, ignorando i caratteri di riempimento `<`). Forte segnale di manomissione.	Segue l’impostazione dell’azione per incoerenza dei dati (`inconsistent_data_action`), la stessa impostazione che regola i controlli di coerenza dei dati della verifica dell’identità.	Configurabile: Nessuna azione, Revisione o Rifiuto.	Trattalo come un tentativo di manomissione salvo prova contraria; Rifiuta è l’impostazione tipica. Il payload `additional_data` include le righe della MRZ da OCR (`ocr_mrz`, array) e la MRZ del chip (`nfc_mrz`, stringa singola) per il confronto manuale.
`DSC_CERTIFICATE_REVOKED`	Il Document Signer Certificate che ha firmato questo chip figura nella Certificate Revocation List (CRL) del paese di emissione.	Sempre `information`.	No — non modifica mai lo stato NFC da solo.	Forte segnale del fatto che la chiave di firma potrebbe essere stata compromessa; se necessario, indirizza queste sessioni alla revisione manuale tramite la tua logica. Tieni presente che di solito il chip attiverà anche `NFC_CHIP_NOT_VERIFIED`, che è configurabile.
`DSC_CERTIFICATE_EXPIRED`	Il periodo di validità del DSC è trascorso (`certificate_summary.validation.dsc_expired` è `true`).	Sempre `information`.	No — non modifica mai lo stato NFC da solo.	Frequente nei documenti più vecchi. Come per la revoca, anche un DSC scaduto non supera la validazione completa del SOD, quindi `NFC_CHIP_NOT_VERIFIED` viene attivato insieme a esso e applica l’azione configurata.
`JPKI_CERTIFICATE_INVALID`	My Number Card giapponese: un certificato letto dalla carta non si collega all’autorità di certificazione JPKI per il suo tipo, è al di fuori del suo periodo di validità o non è un certificato My Number Card di quel tipo. `additional_data.certificate_types` elenca i certificati per i quali la verifica non è riuscita; `jpki.certificates[].failure` ne indica il motivo.	Segue `jpki_certificate_invalid_action` (predefinito Rifiuta).	Configurabile: Nessuna azione, Revisione o Rifiuto.	Trattala come una carta non valida o manomessa. Anche un certificato della carta scaduto rientra qui: il titolare deve rinnovarlo presso il proprio comune.
`JPKI_SIGNATURE_INVALID`	My Number Card giapponese: la firma della carta sulla challenge monouso non viene verificata rispetto al suo certificato, pertanto il possesso della carta e la conoscenza del relativo PIN non sono dimostrati. Viene generato anche quando il passaggio NFC si è chiuso senza alcuna lettura della carta (in questo caso `additional_data.certificate_types` è vuoto).	Segue `jpki_signature_invalid_action` (predefinito Rifiuta).	Configurabile: Nessuna azione, Revisione o Rifiuto.	Non accettare la lettura della carta come prova. Chiedi alla persona di riprovare con la carta fisica.
`JPKI_CERTIFICATE_REVOKED`	My Number Card giapponese: il controllo di revoca segnala un certificato come revocato, ad esempio perché la carta è stata dichiarata smarrita o la registrazione del titolare è cambiata (`jpki.revocation_status` è `revoked`).	Segue `jpki_certificate_revoked_action` (predefinito Rifiuta).	Configurabile: Nessuna azione, Revisione o Rifiuto.	Non accettare la carta.
`JPKI_REVOCATION_UNCHECKED`	My Number Card giapponese: i certificati e la firma sono stati verificati, ma non era disponibile alcuna risposta sulla revoca (`jpki.revocation_status` è `unchecked`), quindi non è possibile escludere che la carta sia revocata. Non viene generato quando la catena o la firma hanno già fallito.	Segue `jpki_revocation_unchecked_action` (predefinito Revisione).	Configurabile: Nessuna azione, Revisione o Rifiuto.	Valuta quanto sia affidabile per te una carta verificata priva di risposta sulla revoca e imposta l’azione di conseguenza.
`JPKI_AND_OCR_DATA_NOT_SAME`	My Number Card giapponese: nome, data di nascita, sesso o indirizzo presenti nel certificato di firma differiscono dai dati letti dalla foto della stessa carta. `additional_data.fields` indica gli attributi che differiscono, mai i relativi valori.	Segue `jpki_inconsistent_data_action` (predefinito Revisione).	Configurabile: Nessuna azione, Revisione o Rifiuto.	Confronta `jpki.attributes` con i dati della verifica dell’identità prima di decidere. Un nome con un carattere raro può differire perché il certificato contiene un carattere sostitutivo (`jpki.attributes.name_substitute_characters`).

SKIPPED_NFC_VALIDATION è mutuamente esclusivo rispetto a NFC_CHIP_NOT_VERIFIED e NFC_TRUST_ANCHOR_MISSING: gli avvisi di verifica del chip vengono valutati solo se la lettura del chip non è stata saltata. Anche i due avvisi di verifica del chip sono mutuamente esclusivi.

Stringhe esatte di descrizione

L’API restituisce esattamente queste stringhe short_description e long_description per ogni rischio:

`risk`	`short_description`	`long_description`
`SKIPPED_NFC_VALIDATION`	Skipped NFC Validation	Dipende dal motivo — consulta Motivi del salto. Torna a “The Near Field Communication (NFC) chip validation process was not completed, potentially due to technical issues or lack of NFC support.” per le sessioni legacy registrate prima dell’introduzione dei motivi del salto.
`NFC_CHIP_NOT_VERIFIED`	NFC chip not verified	The Near Field Communication (NFC) chip failed passive authentication for a reason other than an explicitly identified missing trust anchor. The chip data or signature could be invalid or altered.
`NFC_TRUST_ANCHOR_MISSING`	NFC trust anchor unavailable	The Near Field Communication (NFC) chip could not be verified because the issuing country’s Country Signing Certification Authority (CSCA) trust anchor is not available. This is a trust-store coverage gap, not evidence that the chip was altered.
`NFC_AND_OCR_DATA_NOT_SAME`	NFC and OCR data not same	The Near Field Communication (NFC) chip data and the OCR data don’t match, indicating potential document tampering or data inconsistency.
`DSC_CERTIFICATE_REVOKED`	Document Signer Certificate revoked	The Document Signer Certificate (DSC) used to sign the ePassport chip data has been revoked by the issuing country’s Certificate Revocation List (CRL), indicating the signing key may have been compromised.
`DSC_CERTIFICATE_EXPIRED`	Document Signer Certificate expired	The Document Signer Certificate (DSC) used to sign the ePassport chip data has expired, meaning the certificate’s validity period has passed.
`JPKI_CERTIFICATE_INVALID`	My Number Card certificate not valid	A certificate read from the My Number Card chip is not valid: it does not chain to the Japanese public key infrastructure (JPKI) certification authority, it is outside its validity period, or it is not a My Number Card certificate of the requested type.
`JPKI_SIGNATURE_INVALID`	My Number Card signature not valid	The signature the My Number Card made over the one-time verification challenge does not verify against the card’s certificate, so possession of the card and knowledge of its PIN are not proven.
`JPKI_CERTIFICATE_REVOKED`	My Number Card certificate revoked	The revocation check reports that a certificate read from the My Number Card has been revoked, for example because the card was reported lost or the holder’s registration changed.
`JPKI_REVOCATION_UNCHECKED`	My Number Card revocation status not checked	The certificate and signature of the My Number Card were verified, but its revocation status could not be checked, so a revoked card cannot be ruled out.
`JPKI_AND_OCR_DATA_NOT_SAME`	My Number Card chip and OCR data not same	The name, date of birth, sex or address in the My Number Card’s signature certificate does not match the data read from the card’s image (OCR), indicating a possible substitution or data inconsistency.

Motivi di esclusione

Gli avvisi SKIPPED_NFC_VALIDATION contengono additional_data.skip_reason, uno dei sette codici stabili che indicano esattamente perché l’NFC non è stato eseguito (sulle sessioni registrate prima dell’introduzione dei motivi di esclusione, additional_data potrebbe essere null: tratta il campo come facoltativo durante l’elaborazione di decisioni storiche). La stessa tassonomia compare a livello di sessione come nfc_skip_reason nel payload della decisione, incluse le sessioni in cui l’NFC non avrebbe mai potuto essere eseguito (documento senza chip, integrazione web) e per le quali, di conseguenza, non esiste alcun report o avviso NFC.

`skip_reason`	Significato	`long_description`
`USER_SKIPPED`	L’NFC è stato proposto su un dispositivo compatibile e l’utente ha scelto di saltarlo.	Il passaggio di lettura del chip NFC è stato proposto su un dispositivo compatibile, ma l’utente ha scelto di saltarlo (il salto è consentito dalla configurazione del workflow).
`DOCUMENT_WITHOUT_CHIP`	Il modello di documento non presenta un chip NFC leggibile (non è un documento elettronico ICAO 9303).	Non è stato possibile eseguire la verifica NFC perché questo documento non dispone di un chip NFC leggibile: non è un documento elettronico ICAO 9303.
`CHIP_CERTIFICATE_UNAVAILABLE`	Il chip è presente, ma nessun certificato di firma del paese di emissione (CSCA) copre il periodo di emissione del documento, pertanto la firma non può essere verificata.	Non è stato possibile eseguire la verifica NFC perché il certificato di firma (CSCA) del paese di emissione relativo al periodo di emissione del documento non è disponibile; pertanto, non è possibile verificare la firma del chip.
`DEVICE_WITHOUT_NFC`	Un SDK nativo ha segnalato che il telefono non ha un lettore NFC disponibile.	Non è stato possibile eseguire la verifica NFC perché il dispositivo dell’utente ha segnalato di non disporre di un lettore NFC.
`INTEGRATION_WITHOUT_NFC_ACCESS`	La verifica è stata eseguita senza un SDK nativo (ad esempio in un browser web), che non ha accesso al lettore NFC del telefono.	Non è stato possibile eseguire la verifica NFC perché la verifica non è stata eseguita tramite un SDK mobile nativo, quindi non è stato possibile accedere al lettore NFC del telefono (i browser web non possono leggere i chip NFC).
`MRZ_KEY_UNAVAILABLE`	Non è stato possibile ricavare la chiave di accesso al chip (seed BAC/PACE) dalla MRZ del documento.	Non è stato possibile eseguire la verifica NFC perché non è stato possibile ricavare la chiave di accesso al chip dalla zona a lettura ottica del documento (MRZ).
`JPKI_UNAVAILABLE`	Il documento è una Japan My Number Card, il cui chip viene letto tramite JPKI, e JPKI non era disponibile per questa verifica: non è abilitato, oppure la release dell’SDK nativo dell’app non può leggere le My Number Card. Una My Number Card verificata in un browser riceve `INTEGRATION_WITHOUT_NFC_ACCESS`, mentre una su un telefono senza NFC riceve `DEVICE_WITHOUT_NFC`, come per qualsiasi chip.	Non è stato possibile eseguire la verifica NFC perché questa My Number Card viene letta tramite JPKI, che non era disponibile per questa verifica: non è abilitato oppure l’SDK dell’app non è in grado di leggere le My Number Card.

Un report NFC e il relativo avviso SKIPPED_NFC_VALIDATION esistono solo quando il client ha raggiunto il passaggio NFC e lo ha esplicitamente saltato (in genere USER_SKIPPED, oppure DEVICE_WITHOUT_NFC quando il lettore è risultato non disponibile al momento della scansione). Quando il passaggio NFC è stato ignorato prima ancora di poter essere proposto (documento senza chip, certificato mancante, nessuna funzionalità NFC rilevata, chiave MRZ illeggibile, JPKI non disponibile), non viene creato alcun report o avviso e il motivo compare solo nel campo nfc_skip_reason a livello di sessione, senza influire sullo stato della sessione.

Configurazione

Tre impostazioni del workflow controllano il modo in cui vengono instradati gli avvisi NFC. Ognuna può essere impostata su Nessuna azione, Revisione o Rifiuta:

Azione di esclusione NFC (skip_nfc_action) — si applica a SKIPPED_NFC_VALIDATION. La possibilità di saltare il passaggio viene proposta agli utenti solo quando allow_nfc_skip è abilitato.
Azione chip non verificato (unverified_chip_action) — si applica sia a NFC_CHIP_NOT_VERIFIED che a NFC_TRUST_ANCHOR_MISSING, in modo che il comportamento dello stato della sessione rimanga lo stesso mentre il codice di rischio spiega il motivo del fallimento della verifica.
Azione incoerenza dati (inconsistent_data_action) — si applica a NFC_AND_OCR_DATA_NOT_SAME. Si tratta della stessa impostazione per l’incoerenza dei dati utilizzata dalla Verifica dell’identità.

I due rischi DSC_CERTIFICATE_* non dispongono di un’impostazione di azione: sono sempre informativi. I rischi per la Japan My Number Card hanno altre cinque impostazioni, elencate nella sezione seguente.

Japan My Number Card (JPKI)

Una Japan My Number Card viene letta tramite JPKI anziché ICAO 9303 (chip_protocol: "jpki"), pertanto i rischi ICAO sopra indicati non si attivano mai per questo documento. La sua lettura genera invece questi cinque rischi, ciascuno con la propria impostazione sul nodo NFC:

Impostazione	Rischio	Predefinito
`jpki_certificate_invalid_action`	`JPKI_CERTIFICATE_INVALID`	Rifiuta
`jpki_signature_invalid_action`	`JPKI_SIGNATURE_INVALID`	Rifiuta
`jpki_certificate_revoked_action`	`JPKI_CERTIFICATE_REVOKED`	Rifiuta
`jpki_revocation_unchecked_action`	`JPKI_REVOCATION_UNCHECKED`	Revisione
`jpki_inconsistent_data_action`	`JPKI_AND_OCR_DATA_NOT_SAME`	Revisione

Una lettura saltata di una My Number Card genera SKIPPED_NFC_VALIDATION e segue skip_nfc_action, come qualsiasi chip. Consulta Japan My Number Card (JPKI) per scoprire come funziona la lettura.

La lettura della My Number Card tramite JPKI non è ancora abilitata in produzione. Fino ad allora, una My Number Card salta il passaggio NFC con motivo di esclusione JPKI_UNAVAILABLE e nessuno di questi rischi viene generato.

Esempi

In revisione — impossibile verificare il chip

{
  "warnings": [
  {
    "feature": "NFC",
    "risk": "NFC_CHIP_NOT_VERIFIED",
    "additional_data": null,
    "log_type": "warning",
    "short_description": "NFC chip not verified",
    "long_description": "The Near Field Communication (NFC) chip failed passive authentication for a reason other than an explicitly identified missing trust anchor. The chip data or signature could be invalid or altered.",
    "node_id": "nfc_primary"
  },
  {
    "feature": "NFC",
    "risk": "DSC_CERTIFICATE_EXPIRED",
    "additional_data": null,
    "log_type": "information",
    "short_description": "Document Signer Certificate expired",
    "long_description": "The Document Signer Certificate (DSC) used to sign the ePassport chip data has expired, meaning the certificate's validity period has passed.",
    "node_id": "nfc_primary"
  }
]
}

In questo caso, l’azione per il chip non verificato è impostata su Review, quindi NFC_CHIP_NOT_VERIFIED presenta log_type: "warning" e lo stato del report NFC è In Review. La voce relativa al DSC scaduto è puramente informativa.

Rifiutata — mancata corrispondenza tra chip e OCR

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

In questo caso, l’azione per l’incoerenza dei dati è impostata su Decline, quindi l’avviso presenta log_type: "error" e lo stato del report NFC è Declined. Nota che ocr_mrz è un array di righe MRZ, mentre nfc_mrz è la singola stringa MRZ concatenata del chip.

In revisione: My Number Card senza risposta di revoca

{
  "warnings": [
  {
    "feature": "NFC",
    "risk": "JPKI_REVOCATION_UNCHECKED",
    "additional_data": null,
    "log_type": "warning",
    "short_description": "My Number Card revocation status not checked",
    "long_description": "The certificate and signature of the My Number Card were verified, but its revocation status could not be checked, so a revoked card cannot be ruled out.",
    "node_id": "nfc_primary"
  }
]
}

In questo caso, jpki_revocation_unchecked_action mantiene il suo valore predefinito, Review, quindi l’avviso presenta log_type: "warning" e lo stato del report NFC è In Review. La carta stessa è stata verificata: sia jpki.chain_valid sia jpki.signature_valid sono true.

Tipi di avviso

A ciascun rischio viene assegnata una gravità in base alla configurazione della tua applicazione. I tre livelli di gravità sono:

Correlati

Report NFC — schema completo del report e stati.
Webhook — status.updated si attiva alle modifiche di stato della sessione; il payload della decisione (compresi gli avvisi NFC) viene allegato quando la sessione raggiunge lo stato Approved, Declined, In Review o Abandoned.
Modelli di dati — Verifica NFC — schema canonico campo per campo.
Modelli di dati — Oggetto dell’avviso — la struttura di ogni voce in warnings[].

Autenticazione

Verifica

Monitoraggio

Piattaforma

Avvisi e codici di errore della verifica NFC

Panoramica

Avvisi generati

Stringhe esatte di descrizione

Motivi di esclusione

Configurazione

Japan My Number Card (JPKI)

Esempi

In revisione — impossibile verificare il chip

Rifiutata — mancata corrispondenza tra chip e OCR

In revisione: My Number Card senza risposta di revoca

Tipi di avviso

Correlati

​Panoramica

​Avvisi generati

​Stringhe esatte di descrizione

​Motivi di esclusione

​Configurazione

​Japan My Number Card (JPKI)

​Esempi

​In revisione — impossibile verificare il chip

​Rifiutata — mancata corrispondenza tra chip e OCR

​In revisione: My Number Card senza risposta di revoca

​Tipi di avviso

​Correlati

Panoramica

Avvisi generati

Stringhe esatte di descrizione

Motivi di esclusione

Configurazione

Japan My Number Card (JPKI)

Esempi

In revisione — impossibile verificare il chip

Rifiutata — mancata corrispondenza tra chip e OCR

In revisione: My Number Card senza risposta di revoca

Tipi di avviso

Correlati