Advertencias y códigos de error de verificación NFC

Descripción general

Las advertencias del informe NFC señalan cada condición que Didit detectó al leer y validar el chip. Aparecen en el array warnings[] de cada elemento de nfc_verifications[] (consulta Informe NFC), con feature establecido en "NFC". Cada entrada sigue la estructura común del objeto de advertencia: feature, risk, additional_data, log_type, short_description, long_description, node_id. Cada advertencia tiene tres niveles:

El código risk: un identificador estable con el que puedes hacer coincidencias en tu código (los códigos que se indican a continuación).
El log_type: uno de information, warning o error. Se deriva de la acción que tu flujo configura para ese riesgo: No action → information, Review → warning, Decline → error.
El impacto en la decisión: la misma acción configurada también determina el status del informe NFC: una acción de Revisión lo cambia a In Review y una acción de Rechazo, a Declined.

Cuatro riesgos NFC se configuran de esta forma (SKIPPED_NFC_VALIDATION, NFC_CHIP_NOT_VERIFIED, NFC_TRUST_ANCHOR_MISSING, NFC_AND_OCR_DATA_NOT_SAME), además de los cinco riesgos de la My Number Card de Japón, cada uno con su propia configuración. Los dos riesgos de certificado (DSC_CERTIFICATE_REVOKED, DSC_CERTIFICATE_EXPIRED) son solo informativos: siempre llevan log_type: "information" y nunca cambian por sí solos el estado NFC. A continuación se muestra el conjunto completo de códigos de riesgo que produce el módulo NFC. No existe ningún otro código de riesgo NFC.

Advertencias generadas

`risk`	Causa	Gravedad (`log_type`)	Afecta al estado	Solución
`SKIPPED_NFC_VALIDATION`	Se omitió la lectura del chip: el flujo permite omitirla (`allow_nfc_skip`) y el usuario pulsó omitir, o el cliente la omitió porque no podía leer NFC. El motivo exacto se registra en `additional_data.skip_reason` (consulta Motivos de omisión) y determina el `long_description` de la advertencia.	Sigue la configuración acción al omitir NFC (`skip_nfc_action`): información / advertencia / error.	Configurable: Sin acción, Revisión o Rechazo.	Si tu política exige NFC, establece la acción de omisión en Rechazo (o no permitas omitirla) e indica al usuario que vuelva a intentarlo desde un dispositivo con NFC. De lo contrario, déjala en Sin acción para recurrir a la verificación solo por OCR.
`NFC_CHIP_NOT_VERIFIED`	Se leyó el chip, pero no superó la verificación criptográfica por un motivo distinto de la falta, identificada explícitamente, de un ancla de confianza. No se verificó un hash de un Data Group, la firma del SOD u otra comprobación de autenticación pasiva.	Sigue la configuración acción ante chip no verificado (`unverified_chip_action`).	Configurable: Sin acción, Revisión o Rechazo.	Trátalo como un chip potencialmente inválido o alterado. Revisa `authenticity` y `certificate_summary.validation` para ver qué comprobación falló.
`NFC_TRUST_ANCHOR_MISSING`	El Document Signer Certificate (DSC) del chip pertenece a una generación de Country Signing Certification Authority (CSCA) que no está disponible en el almacén de confianza de Didit (`certificate_summary.validation.csca_missing` es `true`). Por tanto, Didit no puede establecer la cadena de confianza del SOD.	Sigue la configuración acción ante chip no verificado (`unverified_chip_action`).	Configurable: Sin acción, Revisión o Rechazo.	Se trata de una carencia de cobertura del almacén de confianza, no de una prueba de que el chip se haya alterado. Revisa el documento mediante tus comprobaciones alternativas y contacta con el soporte de Didit indicando el país emisor para que se investigue la CSCA que falta.
`NFC_AND_OCR_DATA_NOT_SAME`	La MRZ leída del chip no coincide con la MRZ obtenida por OCR de la cara visible del documento (comparadas tras normalizarlas, ignorando el relleno `<`). Es una señal fuerte de manipulación.	Sigue la configuración acción ante datos incoherentes (`inconsistent_data_action`), la misma que rige las comprobaciones de coherencia de datos de la verificación de identidad.	Configurable: Sin acción, Revisión o Rechazo.	Trátalo como manipulación salvo prueba en contrario; Rechazo es la configuración habitual. El payload `additional_data` incluye las líneas de la MRZ obtenidas por OCR (`ocr_mrz`, array) y la MRZ del chip (`nfc_mrz`, una sola cadena) para compararlas manualmente.
`DSC_CERTIFICATE_REVOKED`	El Document Signer Certificate que firmó este chip figura en la Certificate Revocation List (CRL) del país emisor.	Siempre `information`.	No: nunca cambia por sí sola el estado de NFC.	Es una señal fuerte de que la clave de firma podría estar comprometida; si lo necesitas, envía estas sesiones a revisión manual mediante tu propia lógica. Ten en cuenta que el chip normalmente también generará `NFC_CHIP_NOT_VERIFIED`, que es configurable.
`DSC_CERTIFICATE_EXPIRED`	El periodo de validez del DSC ha vencido (`certificate_summary.validation.dsc_expired` es `true`).	Siempre `information`.	No: nunca cambia por sí sola el estado de NFC.	Es habitual en documentos antiguos. Al igual que con la revocación, un DSC caducado tampoco supera la validación completa del SOD, por lo que también se genera `NFC_CHIP_NOT_VERIFIED` y aplica la acción que hayas configurado.
`JPKI_CERTIFICATE_INVALID`	Tarjeta My Number de Japón: un certificado leído de la tarjeta no forma una cadena de confianza con la autoridad de certificación JPKI de su tipo, está fuera de su periodo de validez o no es un certificado de tarjeta My Number de ese tipo. `additional_data.certificate_types` enumera los certificados que fallaron; `jpki.certificates[].failure` indica el motivo.	Sigue `jpki_certificate_invalid_action` (Rechazo por defecto).	Configurable: Sin acción, Revisión o Rechazo.	Trátalo como una tarjeta inválida o alterada. Un certificado de tarjeta caducado también aparece aquí: el titular lo renueva en su municipio.
`JPKI_SIGNATURE_INVALID`	Tarjeta My Number de Japón: la firma de la tarjeta sobre el desafío de un solo uso no se verifica con su certificado, por lo que no queda demostrada la posesión de la tarjeta ni el conocimiento de su PIN. También se genera cuando el paso de NFC se cerró sin ninguna lectura de tarjeta (en ese caso, `additional_data.certificate_types` está vacío).	Sigue `jpki_signature_invalid_action` (Rechazo por defecto).	Configurable: Sin acción, Revisión o Rechazo.	No aceptes la lectura de la tarjeta como prueba. Pide a la persona que vuelva a intentarlo con la tarjeta física.
`JPKI_CERTIFICATE_REVOKED`	Tarjeta My Number de Japón: la comprobación de revocación indica que un certificado está revocado, por ejemplo porque se denunció la pérdida de la tarjeta o cambió el registro del titular (`jpki.revocation_status` es `revoked`).	Sigue `jpki_certificate_revoked_action` (Rechazo por defecto).	Configurable: Sin acción, Revisión o Rechazo.	No aceptes la tarjeta.
`JPKI_REVOCATION_UNCHECKED`	Tarjeta My Number de Japón: se verificaron los certificados y la firma, pero no había respuesta de revocación disponible (`jpki.revocation_status` es `unchecked`), por lo que no se puede descartar que la tarjeta esté revocada. No se genera cuando la cadena o la firma ya fallaron.	Sigue `jpki_revocation_unchecked_action` (Revisión por defecto).	Configurable: Sin acción, Revisión o Rechazo.	Decide cuánto vale para ti una tarjeta verificada sin respuesta de revocación y configura la acción en consecuencia.
`JPKI_AND_OCR_DATA_NOT_SAME`	Tarjeta My Number de Japón: el nombre, la fecha de nacimiento, el sexo o la dirección del certificado de firma difieren de los datos leídos de la foto de la misma tarjeta. `additional_data.fields` indica los atributos que difieren, nunca sus valores.	Sigue `jpki_inconsistent_data_action` (Revisión por defecto).	Configurable: Sin acción, Revisión o Rechazo.	Compara `jpki.attributes` con los datos de la verificación de identidad antes de decidir. Un nombre con un carácter poco común puede diferir porque el certificado contiene un carácter sustituto (`jpki.attributes.name_substitute_characters`).

SKIPPED_NFC_VALIDATION es mutuamente excluyente con NFC_CHIP_NOT_VERIFIED y NFC_TRUST_ANCHOR_MISSING: las advertencias de verificación del chip solo se evalúan cuando no se omitió la lectura del chip. Las dos advertencias de verificación del chip también son mutuamente excluyentes entre sí.

Cadenas de descripción exactas

La API devuelve exactamente estas cadenas short_description y long_description para cada riesgo:

`risk`	`short_description`	`long_description`
`SKIPPED_NFC_VALIDATION`	Skipped NFC Validation	Depende del motivo: consulta Motivos de omisión. En las sesiones antiguas, registradas antes de que existieran los motivos de omisión, se usa en su lugar “No se completó el proceso de validación del chip de comunicación de campo cercano (NFC), posiblemente por problemas técnicos o por falta de compatibilidad con NFC.”
`NFC_CHIP_NOT_VERIFIED`	NFC chip not verified	El chip de comunicación de campo cercano (NFC) no superó la autenticación pasiva por un motivo distinto de la ausencia explícitamente identificada de un ancla de confianza. Los datos o la firma del chip podrían ser inválidos o haber sido alterados.
`NFC_TRUST_ANCHOR_MISSING`	NFC trust anchor unavailable	No se pudo verificar el chip de comunicación de campo cercano (NFC) porque no está disponible el ancla de confianza de la autoridad de certificación firmante de país (CSCA) del país emisor. Se trata de una carencia de cobertura del almacén de confianza, no de una prueba de que el chip haya sido alterado.
`NFC_AND_OCR_DATA_NOT_SAME`	NFC and OCR data not same	Los datos del chip de comunicación de campo cercano (NFC) y los datos de OCR no coinciden, lo que indica una posible manipulación del documento o una inconsistencia en los datos.
`DSC_CERTIFICATE_REVOKED`	Document Signer Certificate revoked	El certificado de firmante de documentos (DSC) usado para firmar los datos del chip del pasaporte electrónico ha sido revocado por la lista de revocación de certificados (CRL) del país emisor, lo que indica que la clave de firma puede haber quedado comprometida.
`DSC_CERTIFICATE_EXPIRED`	Document Signer Certificate expired	El certificado de firmante de documentos (DSC) usado para firmar los datos del chip del pasaporte electrónico ha expirado, es decir, su periodo de validez ya ha terminado.
`JPKI_CERTIFICATE_INVALID`	My Number Card certificate not valid	Un certificado leído del chip de la My Number Card no es válido: no establece una cadena de confianza con la autoridad de certificación de la infraestructura de clave pública japonesa (JPKI), está fuera de su periodo de validez o no es un certificado de My Number Card del tipo solicitado.
`JPKI_SIGNATURE_INVALID`	My Number Card signature not valid	La firma que la My Number Card generó sobre el desafío de verificación de un solo uso no se verifica con el certificado de la tarjeta, por lo que no queda demostrada la posesión de la tarjeta ni el conocimiento de su PIN.
`JPKI_CERTIFICATE_REVOKED`	My Number Card certificate revoked	La comprobación de revocación indica que un certificado leído de la My Number Card ha sido revocado, por ejemplo, porque se denunció la pérdida de la tarjeta o cambió el registro del titular.
`JPKI_REVOCATION_UNCHECKED`	My Number Card revocation status not checked	Se verificaron el certificado y la firma de la My Number Card, pero no se pudo comprobar su estado de revocación, por lo que no se puede descartar que la tarjeta esté revocada.
`JPKI_AND_OCR_DATA_NOT_SAME`	My Number Card chip and OCR data not same	El nombre, la fecha de nacimiento, el sexo o la dirección del certificado de firma de la My Number Card no coinciden con los datos leídos de la imagen de la tarjeta (OCR), lo que indica una posible sustitución o una inconsistencia en los datos.

Motivos de omisión

Las advertencias SKIPPED_NFC_VALIDATION incluyen additional_data.skip_reason, uno de siete códigos estables que indica exactamente por qué no se ejecutó NFC (en las sesiones registradas antes de que existieran los motivos de omisión, additional_data puede ser null; trata el campo como opcional al procesar decisiones históricas). La misma clasificación aparece a nivel de sesión como nfc_skip_reason en el payload de la decisión, incluso en las sesiones en las que NFC nunca pudo ejecutarse (documento sin chip, integración web) y en las que, por tanto, no existe ningún informe ni advertencia de NFC.

`skip_reason`	Significado	`long_description`
`USER_SKIPPED`	Se ofreció NFC en un dispositivo compatible y el usuario decidió omitirlo.	El paso de lectura del chip NFC se ofreció en un dispositivo compatible, pero el usuario decidió omitirlo (la configuración del flujo permite omitirlo).
`DOCUMENT_WITHOUT_CHIP`	El diseño del documento no tiene un chip NFC legible (no es un documento electrónico ICAO 9303).	No se pudo realizar la verificación NFC porque este documento no tiene un chip NFC legible: no es un documento electrónico ICAO 9303.
`CHIP_CERTIFICATE_UNAVAILABLE`	El chip existe, pero ningún certificado de firma del país emisor (CSCA) cubre el periodo de emisión del documento, por lo que no se puede verificar la firma.	No se pudo realizar la verificación NFC porque no está disponible el certificado de firma del país emisor (CSCA) que cubre el periodo de emisión de este documento, por lo que no se puede verificar la firma del chip.
`DEVICE_WITHOUT_NFC`	Un SDK nativo informó de que el teléfono no tiene un lector NFC disponible.	No se pudo realizar la verificación NFC porque el dispositivo del usuario informó de que no tiene un lector NFC disponible.
`INTEGRATION_WITHOUT_NFC_ACCESS`	La verificación se ejecutó sin un SDK nativo (por ejemplo, en un navegador web), que no tiene acceso al lector NFC del teléfono.	No se pudo realizar la verificación NFC porque la verificación no se ejecutó mediante un SDK móvil nativo, por lo que no hubo acceso al lector NFC del teléfono (los navegadores web no pueden leer chips NFC).
`MRZ_KEY_UNAVAILABLE`	No se pudo derivar la clave de acceso al chip (semilla BAC/PACE) a partir de la MRZ del documento.	No se pudo realizar la verificación NFC porque no se pudo derivar la clave de acceso al chip a partir de la zona de lectura mecánica (MRZ) del documento.
`JPKI_UNAVAILABLE`	El documento es una tarjeta My Number de Japón, cuyo chip se lee mediante JPKI, y JPKI no estaba disponible para esta verificación: no está habilitado o la versión del SDK nativo de la aplicación no puede leer tarjetas My Number. Una tarjeta My Number verificada en un navegador recibe `INTEGRATION_WITHOUT_NFC_ACCESS`, y una en un teléfono sin NFC recibe `DEVICE_WITHOUT_NFC`, como con cualquier chip.	No se pudo realizar la verificación NFC porque esta tarjeta My Number se lee mediante JPKI, que no estaba disponible para esta verificación: no está habilitado o el SDK de la aplicación no puede leer tarjetas My Number.

Un informe de NFC y su advertencia SKIPPED_NFC_VALIDATION solo existen cuando el cliente llegó al paso de NFC y lo omitió de forma explícita (normalmente USER_SKIPPED, o DEVICE_WITHOUT_NFC cuando el lector resultó no estar disponible en el momento del escaneo). Cuando el paso de NFC se omitió antes de que pudiera ofrecerse (documento sin chip, certificado ausente, ninguna capacidad NFC informada, clave MRZ ilegible, JPKI no disponible), no se crea ningún informe ni advertencia y el motivo aparece solo en el campo nfc_skip_reason a nivel de sesión, sin afectar al estado de la sesión.

Configuración

Tres ajustes del flujo controlan cómo se gestionan las advertencias de NFC. Cada uno puede configurarse como Sin acción, Revisión o Rechazar:

Skip NFC action (skip_nfc_action): se aplica a SKIPPED_NFC_VALIDATION. La opción de omitir solo se ofrece a los usuarios cuando allow_nfc_skip está habilitado.
Unverified chip action (unverified_chip_action): se aplica tanto a NFC_CHIP_NOT_VERIFIED como a NFC_TRUST_ANCHOR_MISSING, de modo que el comportamiento del estado de la sesión sigue siendo el mismo mientras el código de riesgo explica por qué falló la verificación.
Data inconsistency action (inconsistent_data_action): se aplica a NFC_AND_OCR_DATA_NOT_SAME. Es el mismo ajuste de inconsistencia de datos que usa la verificación de identidad.

Los dos riesgos DSC_CERTIFICATE_* no tienen ajuste de acción: siempre son informativos. Los riesgos de la tarjeta My Number de Japón tienen cinco ajustes más, que se enumeran en la siguiente sección.

Tarjeta My Number de Japón (JPKI)

Una tarjeta My Number de Japón se lee mediante JPKI en lugar de ICAO 9303 (chip_protocol: "jpki"), por lo que los riesgos ICAO anteriores nunca se activan para ella. En su lugar, su lectura genera estos cinco riesgos, cada uno con su propio ajuste en el nodo de NFC:

Ajuste	Riesgo	Valor predeterminado
`jpki_certificate_invalid_action`	`JPKI_CERTIFICATE_INVALID`	Rechazar
`jpki_signature_invalid_action`	`JPKI_SIGNATURE_INVALID`	Rechazar
`jpki_certificate_revoked_action`	`JPKI_CERTIFICATE_REVOKED`	Rechazar
`jpki_revocation_unchecked_action`	`JPKI_REVOCATION_UNCHECKED`	Revisar
`jpki_inconsistent_data_action`	`JPKI_AND_OCR_DATA_NOT_SAME`	Revisar

Una lectura omitida de una tarjeta My Number genera SKIPPED_NFC_VALIDATION y sigue skip_nfc_action, como cualquier chip. Consulta Tarjeta My Number de Japón (JPKI) para saber cómo funciona la lectura.

La lectura de tarjetas My Number mediante JPKI aún no está habilitada en producción. Hasta que lo esté, una tarjeta My Number omite el paso de NFC con el motivo de omisión JPKI_UNAVAILABLE y no se genera ninguno de estos riesgos.

Ejemplos

En revisión: no se pudo verificar el 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"
  }
]
}

Aquí la acción para un chip no verificado está configurada en Revisar, por lo que NFC_CHIP_NOT_VERIFIED lleva log_type: "warning" y el estado del informe NFC es In Review. La entrada del DSC expirado es solo informativa.

Rechazado: discrepancia entre el chip y el 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í la acción para datos incoherentes está configurada en Rechazar, por lo que la advertencia lleva log_type: "error" y el estado del informe NFC es Declined. Ten en cuenta que ocr_mrz es un array de líneas de la MRZ, mientras que nfc_mrz es la cadena única de la MRZ del chip, con todas las líneas concatenadas.

En revisión: tarjeta My Number sin respuesta de revocación

{
  "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 mantiene su valor predeterminado, Revisar, por lo que la advertencia lleva log_type: "warning" y el estado del informe NFC es In Review. Se demostró la validez de la tarjeta: jpki.chain_valid y jpki.signature_valid son ambos true.

Tipos de advertencia

A cada riesgo se le asigna una gravedad según la configuración de tu aplicación. Las tres gravedades son:

Relacionado

Informe NFC: esquema completo del informe y sus estados.
Webhooks: status.updated se dispara cuando cambia el estado de la sesión; el payload de la decisión (incluidas las advertencias NFC) se adjunta cuando la sesión pasa a aprobada, rechazada, en revisión o abandonada.
Modelos de datos: Verificación NFC: esquema de referencia, campo por campo.
Modelos de datos: Objeto de advertencia: la estructura de cada entrada de warnings[].

Autenticación

Verificación

Monitorización

Plataforma

Advertencias y códigos de error de verificación NFC

Descripción general

Advertencias generadas

Cadenas de descripción exactas

Motivos de omisión

Configuración

Tarjeta My Number de Japón (JPKI)

Ejemplos

En revisión: no se pudo verificar el chip

Rechazado: discrepancia entre el chip y el OCR

En revisión: tarjeta My Number sin respuesta de revocación

Tipos de advertencia

Relacionado

​Descripción general

​Advertencias generadas

​Cadenas de descripción exactas

​Motivos de omisión

​Configuración

​Tarjeta My Number de Japón (JPKI)

​Ejemplos

​En revisión: no se pudo verificar el chip

​Rechazado: discrepancia entre el chip y el OCR

​En revisión: tarjeta My Number sin respuesta de revocación

​Tipos de advertencia

​Relacionado

Descripción general

Advertencias generadas

Cadenas de descripción exactas

Motivos de omisión

Configuración

Tarjeta My Number de Japón (JPKI)

Ejemplos

En revisión: no se pudo verificar el chip

Rechazado: discrepancia entre el chip y el OCR

En revisión: tarjeta My Number sin respuesta de revocación

Tipos de advertencia

Relacionado