Advertències i codis d'error de la verificació NFC

Visió general

Les advertències a l’informe d’NFC assenyalen cada condició que Didit ha observat durant la lectura i validació del xip. Es recullen a la matriu warnings[] de cada element de nfc_verifications[] (consulta l’informe d’NFC), amb feature establert a "NFC". Cada entrada segueix l’estructura compartida d’objecte d’advertència: feature, risk, additional_data, log_type, short_description, long_description, node_id. Cada advertència té tres nivells:

El codi de risk: un identificador estable que pots fer coincidir al teu codi (els codis que es llisten a continuació).
El log_type: un dels valors information, warning o error. Es deriva de l’acció que el teu flux de treball configura per a aquest risc: Sense acció → information, Revisió → warning, Rebutjar → error.
L’impacte en la decisió: la mateixa acció configurada també determina el status de l’informe d’NFC: una acció de Revisió el canvia a In Review, i una acció de Rebutjar el canvia a Declined.

Quatre riscos d’NFC es poden configurar d’aquesta manera (SKIPPED_NFC_VALIDATION, NFC_CHIP_NOT_VERIFIED, NFC_TRUST_ANCHOR_MISSING, NFC_AND_OCR_DATA_NOT_SAME), a més dels cinc riscos de la Japan My Number Card, cadascun amb la seva pròpia configuració. Els dos riscos de certificat (DSC_CERTIFICATE_REVOKED, DSC_CERTIFICATE_EXPIRED) són només informatius: sempre porten log_type: "information" i mai no canvien l’estat d’NFC per si mateixos. A continuació es mostra el conjunt complet de codis de risc que genera el mòdul d’NFC. No existeix cap altre codi de risc d’NFC.

Advertències generades

`risk`	Causa	Gravetat (`log_type`)	Afecta l’estat?	Resolució
`SKIPPED_NFC_VALIDATION`	S’ha omès la lectura del xip: el flux de treball permet ometre-la (`allow_nfc_skip`) i l’usuari ha premut el botó d’ometre, o bé el client l’ha omès perquè no ha pogut llegir NFC. El motiu exacte es registra a `additional_data.skip_reason` (consulta Motius d’omissió) i determina el `long_description` de l’advertència.	Segueix la configuració de l’acció d’omissió d’NFC (`skip_nfc_action`): informació / advertència / error.	Configurable: Sense acció, Revisió o Rebuig.	Si la teva política requereix NFC, defineix l’acció d’omissió com a Rebutjar (o no permetis l’omissió en absolut) i indica a l’usuari que ho reintenti des d’un dispositiu compatible amb NFC. En cas contrari, deixa-la en Sense acció per recórrer a la verificació només per OCR com a alternativa.
`NFC_CHIP_NOT_VERIFIED`	S’ha llegit el xip però ha fallat la verificació criptogràfica per un motiu diferent d’una àncora de confiança no disponible identificada explícitament. Un hash de grup de dades, la signatura del SOD o una altra comprovació d’autenticació passiva no s’ha verificat.	Segueix la configuració de l’acció de xip no verificat (`unverified_chip_action`).	Configurable: Sense acció, Revisió o Rebuig.	Tracta-ho com un xip potencialment invàlid o alterat. Inspecciona `authenticity` i `certificate_summary.validation` per veure quina comprovació ha fallat.
`NFC_TRUST_ANCHOR_MISSING`	El certificat de signant del document (DSC) del xip pertany a una generació de l’autoritat de certificació de signatura del país (CSCA) que no està disponible al magatzem de confiança de Didit (`certificate_summary.validation.csca_missing` és `true`). Per tant, Didit no pot establir la cadena de confiança del SOD.	Segueix la configuració de l’acció de xip no verificat (`unverified_chip_action`).	Configurable: Sense acció, Revisió o Rebuig.	Es tracta d’una manca de cobertura al magatzem de confiança, no d’una prova que el xip s’hagi alterat. Revisa el document mitjançant les teves comprovacions alternatives i contacta amb el suport de Didit indicant el país emissor perquè es pugui investigar la CSCA que falta.
`NFC_AND_OCR_DATA_NOT_SAME`	La MRZ llegida del xip no coincideix amb la MRZ obtinguda per OCR de la part visible del document (comparada després de la normalització, ignorant el caràcter d’ompliment `<`). És un senyal clar de manipulació.	Segueix la configuració de l’acció de dades incoherents (`inconsistent_data_action`), la mateixa configuració que regeix les comprovacions de coherència de dades de la verificació d’identitat.	Configurable: Sense acció, Revisió o Rebuig.	Tracta-ho com una manipulació tret que es demostri el contrari; Rebutjar és la configuració habitual. El payload de `additional_data` inclou les línies de la MRZ per OCR (`ocr_mrz`, array) i la MRZ del xip (`nfc_mrz`, cadena única) per fer una comparació manual.
`DSC_CERTIFICATE_REVOKED`	El certificat de signant del document que ha signat aquest xip apareix a la llista de revocació de certificats (CRL) del país emissor.	Sempre `information`.	No: mai no canvia l’estat d’NFC per si mateix.	Senyal clar que la clau de signatura podria haver estat compromesa; desvia aquestes sessions cap a la revisió manual mitjançant la teva pròpia lògica si cal. Tingues en compte que el xip normalment també activarà `NFC_CHIP_NOT_VERIFIED`, que és configurable.
`DSC_CERTIFICATE_EXPIRED`	El període de validesa del DSC ha passat (`certificate_summary.validation.dsc_expired` és `true`).	Sempre `information`.	No: mai no canvia l’estat d’NFC per si mateix.	Habitual en documents més antics. Igual que amb la revocació, un DSC caducat també falla la validació completa del SOD, de manera que `NFC_CHIP_NOT_VERIFIED` s’activa al seu costat i aplica l’acció que hagis configurat.
`JPKI_CERTIFICATE_INVALID`	Japan My Number Card: un certificat llegit de la targeta no enllaça amb l’autoritat de certificació JPKI del seu tipus, està fora del seu període de validesa o no és un certificat de My Number Card d’aquest tipus. `additional_data.certificate_types` enumera els certificats que han fallat; `jpki.certificates[].failure` n’indica el motiu.	Segueix `jpki_certificate_invalid_action` (per defecte Rebutjar).	Configurable: Sense acció, Revisió o Rebuig.	Tracta-ho com una targeta invàlida o alterada. Un certificat de targeta caducat també acaba aquí: el titular l’ha de renovar al seu municipi.
`JPKI_SIGNATURE_INVALID`	Japan My Number Card: la signatura de la targeta sobre el repte d’un sol ús no es pot verificar amb el seu certificat, de manera que la possessió de la targeta i el coneixement del seu PIN no queden demostrats. També s’emet quan el pas d’NFC s’ha tancat sense cap lectura de targeta (`additional_data.certificate_types` queda aleshores buit).	Segueix `jpki_signature_invalid_action` (per defecte Rebutjar).	Configurable: Sense acció, Revisió o Rebuig.	No acceptis la lectura de la targeta com a prova. Demana a la persona que ho reintenti amb la targeta física.
`JPKI_CERTIFICATE_REVOKED`	Japan My Number Card: la comprovació de revocació informa que un certificat està revocat, per exemple perquè la targeta s’ha notificat com a perduda o el registre del titular ha canviat (`jpki.revocation_status` és `revoked`).	Segueix `jpki_certificate_revoked_action` (per defecte Rebutjar).	Configurable: Sense acció, Revisió o Rebuig.	No acceptis la targeta.
`JPKI_REVOCATION_UNCHECKED`	Japan My Number Card: els certificats i la signatura s’han verificat, però no s’ha obtingut cap resposta de revocació (`jpki.revocation_status` és `unchecked`), de manera que no es pot descartar una targeta revocada. No s’emet quan la cadena o la signatura ja han fallat.	Segueix `jpki_revocation_unchecked_action` (per defecte Revisió).	Configurable: Sense acció, Revisió o Rebuig.	Decideix quant val per a tu una targeta verificada sense resposta de revocació i configura l’acció en conseqüència.
`JPKI_AND_OCR_DATA_NOT_SAME`	Japan My Number Card: el nom, la data de naixement, el sexe o l’adreça del certificat de signatura difereixen de les dades llegides de la foto de la mateixa targeta. `additional_data.fields` indica els atributs que difereixen, mai els seus valors.	Segueix `jpki_inconsistent_data_action` (per defecte Revisió).	Configurable: Sense acció, Revisió o Rebuig.	Compara `jpki.attributes` amb les dades de verificació d’identitat abans de prendre una decisió. Un nom amb un caràcter poc comú pot diferir perquè el certificat conté un caràcter de substitució (`jpki.attributes.name_substitute_characters`).

SKIPPED_NFC_VALIDATION és mútuament excloent amb NFC_CHIP_NOT_VERIFIED i NFC_TRUST_ANCHOR_MISSING: les advertències de verificació del xip només s’avaluen quan la lectura del xip no s’ha omès. Les dues advertències de verificació del xip també són mútuament excloents entre si.

Cadenes de descripció exactes

L’API retorna exactament aquestes cadenes de short_description i long_description per a cada risc:

`risk`	`short_description`	`long_description`
`SKIPPED_NFC_VALIDATION`	Validació NFC omesa	Específica segons el motiu — consulta Motius d’omissió. Fa servir per defecte «El procés de validació del xip de comunicació de camp proper (NFC) no s’ha completat, possiblement a causa de problemes tècnics o de la manca de compatibilitat amb NFC.» en sessions antigues registrades abans que existissin els motius d’omissió.
`NFC_CHIP_NOT_VERIFIED`	Xip NFC no verificat	El xip de comunicació de camp proper (NFC) no ha superat l’autenticació passiva per un motiu diferent d’una àncora de confiança absent identificada explícitament. Les dades o la signatura del xip podrien no ser vàlides o haver estat alterades.
`NFC_TRUST_ANCHOR_MISSING`	Àncora de confiança NFC no disponible	El xip de comunicació de camp proper (NFC) no s’ha pogut verificar perquè l’àncora de confiança de l’autoritat de certificació de signatura del país emissor (CSCA) no està disponible. Es tracta d’una manca de cobertura al magatzem de confiança, no d’una prova que el xip hagi estat alterat.
`NFC_AND_OCR_DATA_NOT_SAME`	Dades NFC i d’OCR no coincidents	Les dades del xip de comunicació de camp proper (NFC) i les dades d’OCR no coincideixen, cosa que indica una possible manipulació del document o una incoherència en les dades.
`DSC_CERTIFICATE_REVOKED`	Certificat del signant del document revocat	El certificat del signant del document (DSC) utilitzat per signar les dades del xip de l’ePassport ha estat revocat per la llista de revocació de certificats (CRL) del país emissor, cosa que indica que la clau de signatura podria haver estat compromesa.
`DSC_CERTIFICATE_EXPIRED`	Certificat del signant del document caducat	El certificat del signant del document (DSC) utilitzat per signar les dades del xip de l’ePassport ha caducat, és a dir, el període de validesa del certificat ha vençut.
`JPKI_CERTIFICATE_INVALID`	Certificat de la My Number Card no vàlid	Un certificat llegit del xip de la My Number Card no és vàlid: no forma una cadena de confiança amb l’autoritat de certificació de la infraestructura de clau pública japonesa (JPKI), està fora del seu període de validesa o no és un certificat de la My Number Card del tipus sol·licitat.
`JPKI_SIGNATURE_INVALID`	Signatura de la My Number Card no vàlida	La signatura que la My Number Card ha generat sobre el repte de verificació d’un sol ús no es pot verificar amb el certificat de la targeta, de manera que la possessió de la targeta i el coneixement del seu PIN no queden demostrats.
`JPKI_CERTIFICATE_REVOKED`	Certificat de la My Number Card revocat	La comprovació de revocació indica que un certificat llegit de la My Number Card ha estat revocat, per exemple perquè s’ha notificat la pèrdua de la targeta o ha canviat el registre del titular.
`JPKI_REVOCATION_UNCHECKED`	Estat de revocació de la My Number Card no comprovat	El certificat i la signatura de la My Number Card s’han verificat, però no s’ha pogut comprovar el seu estat de revocació, de manera que no es pot descartar que la targeta estigui revocada.
`JPKI_AND_OCR_DATA_NOT_SAME`	Dades del xip de la My Number Card i d’OCR no coincidents	El nom, la data de naixement, el sexe o l’adreça del certificat de signatura de la My Number Card no coincideixen amb les dades llegides de la imatge de la targeta (OCR), cosa que indica una possible substitució o incoherència en les dades.

Motius d’omissió

Les advertències SKIPPED_NFC_VALIDATION inclouen additional_data.skip_reason, un dels set codis estables que indiquen exactament per què no s’ha executat l’NFC (en sessions enregistrades abans que existissin els motius d’omissió, additional_data pot ser null; tracta el camp com a opcional quan processis decisions històriques). La mateixa taxonomia apareix a escala de sessió com a nfc_skip_reason al payload de decisió, incloent-hi sessions en què l’NFC mai no s’hauria pogut executar (document sense xip, integració web) i per a les quals, per tant, no existeix cap informe ni advertència d’NFC.

`skip_reason`	Significat	`long_description`
`USER_SKIPPED`	L’NFC es va oferir en un dispositiu compatible i l’usuari va triar ometre’l.	El pas de lectura del xip NFC es va oferir en un dispositiu compatible, però l’usuari va triar ometre’l (l’omissió està permesa per la configuració del flux de treball).
`DOCUMENT_WITHOUT_CHIP`	El disseny del document no té cap xip NFC llegible (no és un document electrònic ICAO 9303).	La verificació NFC no s’ha pogut dur a terme perquè aquest document no té cap xip NFC llegible: no és un document electrònic ICAO 9303.
`CHIP_CERTIFICATE_UNAVAILABLE`	El xip existeix, però cap certificat de signatura del país emissor (CSCA) cobreix el període d’emissió del document, de manera que la signatura no es pot verificar.	La verificació NFC no s’ha pogut dur a terme perquè el certificat de signatura del país emissor (CSCA) que cobreix el període d’emissió d’aquest document no està disponible, de manera que no es pot verificar la signatura del xip.
`DEVICE_WITHOUT_NFC`	Un SDK natiu ha notificat que el telèfon no té cap lector NFC disponible.	La verificació NFC no s’ha pogut dur a terme perquè el dispositiu de l’usuari ha informat que no disposa de cap lector NFC.
`INTEGRATION_WITHOUT_NFC_ACCESS`	La verificació s’ha executat sense un SDK natiu (per exemple, en un navegador web), que no té accés al lector NFC del telèfon.	La verificació NFC no s’ha pogut dur a terme perquè la verificació no s’ha executat mitjançant un SDK mòbil natiu, de manera que no hi havia accés al lector NFC del telèfon (els navegadors web no poden llegir xips NFC).
`MRZ_KEY_UNAVAILABLE`	La clau d’accés al xip (llavor BAC/PACE) no s’ha pogut derivar de l’MRZ del document.	La verificació NFC no s’ha pogut dur a terme perquè la clau d’accés al xip no s’ha pogut derivar de la zona de lectura mecànica del document (MRZ).
`JPKI_UNAVAILABLE`	El document és una targeta Japan My Number Card, el xip de la qual es llegeix mitjançant JPKI, i JPKI no estava disponible per a aquesta verificació: no està habilitat o la versió de l’SDK natiu de l’aplicació no pot llegir targetes My Number Card. Una targeta My Number Card verificada en un navegador rep `INTEGRATION_WITHOUT_NFC_ACCESS`, i en un telèfon sense NFC rep `DEVICE_WITHOUT_NFC`, com passa amb qualsevol xip.	La verificació NFC no s’ha pogut dur a terme perquè aquesta My Number Card es llegeix mitjançant JPKI, que no estava disponible per a aquesta verificació: no està habilitat o l’SDK de l’aplicació no pot llegir My Number Cards.

Un informe d’NFC i la seva advertència SKIPPED_NFC_VALIDATION només existeixen quan el client ha arribat al pas d’NFC i l’ha omès explícitament (normalment USER_SKIPPED, o DEVICE_WITHOUT_NFC quan s’ha constatat que el lector no estava disponible en el moment de l’escaneig). Quan el pas d’NFC s’ha ignorat abans que es pogués arribar a oferir (document sense xip, certificat absent, cap capacitat NFC notificada, clau MRZ il·legible, JPKI no disponible), no es crea cap informe ni advertència i el motiu només apareix al camp nfc_skip_reason a escala de sessió, sense afectar l’estat de la sessió.

Configuració

Tres configuracions del flux de treball controlen com s’encaminen les advertències d’NFC. Cadascuna es pot establir a Sense acció, Revisió o Rebutjar:

Acció d’omissió d’NFC (skip_nfc_action): s’aplica a SKIPPED_NFC_VALIDATION. L’omissió només s’ofereix als usuaris quan allow_nfc_skip està habilitat.
Acció de xip no verificat (unverified_chip_action): s’aplica tant a NFC_CHIP_NOT_VERIFIED com a NFC_TRUST_ANCHOR_MISSING, de manera que el comportament de l’estat de la sessió es manté igual mentre el codi de risc explica per què ha fallat la verificació.
Acció d’incoherència de dades (inconsistent_data_action): s’aplica a NFC_AND_OCR_DATA_NOT_SAME. És la mateixa configuració d’incoherència de dades utilitzada per la verificació d’identitat.

Els dos riscos DSC_CERTIFICATE_* no tenen cap configuració d’acció; sempre són informatius. Els riscos de la targeta Japan My Number Card tenen cinc configuracions addicionals, que s’enumeren a la secció següent.

Japan My Number Card (JPKI)

Una targeta Japan My Number Card es llegeix mitjançant JPKI en lloc d’ICAO 9303 (chip_protocol: "jpki"), de manera que els riscos d’ICAO anteriors mai no s’activen per a ella. La seva lectura genera aquests cinc riscos en el seu lloc, cadascun amb la seva pròpia configuració al node d’NFC:

Configuració	Risc	Per defecte
`jpki_certificate_invalid_action`	`JPKI_CERTIFICATE_INVALID`	Rebutjar
`jpki_signature_invalid_action`	`JPKI_SIGNATURE_INVALID`	Rebutjar
`jpki_certificate_revoked_action`	`JPKI_CERTIFICATE_REVOKED`	Rebutjar
`jpki_revocation_unchecked_action`	`JPKI_REVOCATION_UNCHECKED`	Revisió
`jpki_inconsistent_data_action`	`JPKI_AND_OCR_DATA_NOT_SAME`	Revisió

Una lectura omesa d’una My Number Card genera SKIPPED_NFC_VALIDATION i segueix skip_nfc_action, com qualsevol xip. Consulta Japan My Number Card (JPKI) per saber com funciona la lectura.

La lectura de la My Number Card mitjançant JPKI encara no està habilitada a producció. Fins que ho estigui, una My Number Card omet el pas d’NFC amb el motiu d’omissió JPKI_UNAVAILABLE i cap d’aquests riscos no es genera.

Examples

En revisió — no s’ha pogut verificar el xip

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

Aquí l’acció per al xip no verificat està configurada amb el valor Review, de manera que NFC_CHIP_NOT_VERIFIED inclou log_type: "warning" i l’estat de l’informe NFC és In Review. L’entrada de DSC caducat és merament informativa.

Rebutjada — discrepància entre xip i 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"
  }
]
}

Aquí l’acció per a inconsistència de dades està configurada a Decline, de manera que l’advertència inclou log_type: "error" i l’estat de l’informe NFC és Declined. Tingues en compte que ocr_mrz és una matriu de línies MRZ mentre que nfc_mrz és l’única cadena MRZ concatenada del xip.

En revisió: targeta My Number sense resposta de revocació

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

Aquí jpki_revocation_unchecked_action manté el seu valor per defecte, Review, de manera que l’advertència inclou log_type: "warning" i l’estat de l’informe NFC és In Review. La targeta en si mateixa s’ha validat: tant jpki.chain_valid com jpki.signature_valid són true.

Tipus d’advertències

A cada risc se li assigna una gravetat basada en la configuració de la teva aplicació. Les tres gravetats són:

Relacionat

Informe NFC — esquema complet de l’informe i estats.
Webhooks — status.updated es dispara amb els canvis d’estat de la sessió; el payload de decisió (incloent-hi les advertències NFC) s’adjunta quan la sessió arriba a Approved, Declined, In Review o Abandoned.
Models de dades — Verificació NFC — esquema canònic camp per camp.
Models de dades — Objecte d’advertència — l’estructura de cada entrada a warnings[].

Autenticació

Verificació

Monitoratge

Plataforma

Advertències i codis d'error de la verificació NFC

Visió general

Advertències generades

Cadenes de descripció exactes

Motius d’omissió

Configuració

Japan My Number Card (JPKI)

Examples

En revisió — no s’ha pogut verificar el xip

Rebutjada — discrepància entre xip i OCR

En revisió: targeta My Number sense resposta de revocació

Tipus d’advertències

Relacionat

​Visió general

​Advertències generades

​Cadenes de descripció exactes

​Motius d’omissió

​Configuració

​Japan My Number Card (JPKI)

​Examples

​En revisió — no s’ha pogut verificar el xip

​Rebutjada — discrepància entre xip i OCR

​En revisió: targeta My Number sense resposta de revocació

​Tipus d’advertències

​Relacionat

Visió general

Advertències generades

Cadenes de descripció exactes

Motius d’omissió

Configuració

Japan My Number Card (JPKI)

Examples

En revisió — no s’ha pogut verificar el xip

Rebutjada — discrepància entre xip i OCR

En revisió: targeta My Number sense resposta de revocació

Tipus d’advertències

Relacionat