Informe de verificación NFC: chip y autenticidad

Descripción general

El informe de verificación NFC recoge lo que Didit leyó y validó del chip NFC de un documento: un pasaporte electrónico, un documento de identidad electrónico u otro documento electrónico ICAO 9303. Incluye los datos biográficos del chip, las comprobaciones criptográficas de integridad (hashes del SOD y de los Data Groups) y un resumen del Document Signer Certificate (DSC) que usa el país emisor. El informe se genera después de que el usuario completa el paso NFC de un flujo de verificación (workflow). Didit lee los Data Groups del chip en el dispositivo del usuario, verifica la firma del Document Security Object (SOD) con el certificado CSCA del país emisor, compara el hash de cada Data Group con los valores firmados en el SOD y contrasta la MRZ del chip con la MRZ extraída por OCR de la cara visible del documento. Una Tarjeta My Number de Japón se lee mediante JPKI (chip_protocol: "jpki"): su informe incluye en jpki las comprobaciones del certificado, la firma, la revocación y los datos del titular, y los campos ICAO quedan en null. Consulta Tarjeta My Number de Japón (JPKI). Cada informe tiene su propio status, independiente del estado general de la sesión, que refleja cómo se resolvió únicamente el paso NFC:

Approved: se leyó el chip y ninguna de las advertencias que se activaron está configurada para enviar el paso a revisión o rechazarlo.
In Review: se activó al menos una advertencia cuya acción configurada es Revisión (por ejemplo, NFC_CHIP_NOT_VERIFIED o NFC_TRUST_ANCHOR_MISSING cuando la acción para chips no verificados está configurada como Revisión, o JPKI_REVOCATION_UNCHECKED con su acción predeterminada).
Declined: se activó al menos una advertencia cuya acción configurada es Rechazar (por ejemplo, NFC_AND_OCR_DATA_NOT_SAME cuando la acción para datos inconsistentes está configurada como Rechazar).
Not Finished: el usuario nunca completó el paso NFC; la lectura del chip se abandonó o el dispositivo no admitía NFC.
Resub Requested: un revisor pidió al usuario que volviera a enviar la información; el informe quedará sustituido por un nuevo intento.

Dónde aparece en las respuestas de la API

El informe NFC se entrega dentro del array nfc_verifications[], que es siempre un array JSON y nunca un objeto nfc singular. Aparecen varias entradas cuando un flujo ejecuta NFC más de una vez (por ejemplo, un flujo de verificación reforzada); cada entrada tiene su propio node_id.

API de decisión de sesión: aparece como nfc_verifications[] en el nivel superior de GET /v3/session/{sessionId}/decision/. Consulta Obtener la decisión de la sesión.
Webhooks: los payloads de status.updated incluyen el mismo array nfc_verifications[] en cuanto el paso NFC ha generado datos. Consulta Webhooks.
NFC independiente: para el envío directo de datos del chip, consulta la descripción general de NFC.

Cuando tu flujo incluye un paso NFC que se omitió o se saltó, el payload de la decisión también incluye un campo de nivel superior nfc_skip_reason que indica exactamente el motivo: el documento no tiene chip, el certificado del país emisor no está disponible, el dispositivo no tiene lector NFC, la verificación se ejecutó sin un SDK nativo (un navegador no tiene acceso a NFC), no se pudo derivar la clave de acceso al chip a partir de la MRZ, no se pudo leer una My Number Card mediante JPKI o el usuario decidió omitir el paso. Queda en null para los resultados que no entran en esa clasificación, sobre todo cuando un usuario abandonó a mitad del intento (estado del informe Not Finished) o en una sesión en la que NFC sigue pendiente. Consulta Motivos de omisión para ver los valores exactos.

La documentación anterior hacía referencia a un campo nfc singular. Esa estructura no existe en el endpoint de decisión v3: solo aparece en destinos de webhook configurados explícitamente para webhooks V2, donde también incluye chip_protocol y jpki. Lee siempre response.nfc_verifications[0] y recorre el array.

Esquema

El esquema canónico campo por campo está en la página de referencia Modelos de datos. Los campos siguientes reflejan ese esquema canónico.

Campo	Tipo	Descripción
`status`	`"Not Finished" \| "Approved" \| "Declined" \| "In Review" \| "Resub Requested"`	Estado del paso NFC (consulta los significados más arriba).
`node_id`	string \| null	Nodo del grafo del flujo que generó este informe. Te permite distinguir dos comprobaciones NFC en un flujo de varios pasos.
`is_nfc_skipped`	boolean	`true` cuando este paso NFC se omitió explícitamente en lugar de leerse.
`skip_reason`	string \| null	Motivo por el que se omitió el paso; solo se rellena cuando `is_nfc_skipped` es `true`. Admite los mismos valores que `nfc_skip_reason` a nivel de sesión; consulta Motivos de omisión.
`chip_protocol`	`"icao"` \| `"jpki"`	Cómo se lee el chip. `icao`: un chip de pasaporte electrónico o eID conforme a ICAO 9303. `jpki`: una My Number Card de Japón, cuyo resultado está en `jpki`; en ese caso, los campos ICAO siguientes (`portrait_image`, `signature_image`, `chip_data`, `authenticity`, `certificate_summary`) son `null`. También se rellena en los pasos omitidos.
`jpki`	object \| null	Lo que acredita la lectura de una My Number Card; consulta Campos JPKI. `null` para chips ICAO, para pasos omitidos y cuando el paso se cerró sin ninguna lectura de tarjeta.
`portrait_image`	string (signed URL) \| null	Retrato extraído del chip (DG2). Enlace prefirmado de corta duración: descárgalo cuanto antes; vuelve a obtener la decisión para conseguir una URL nueva.
`signature_image`	string (signed URL) \| null	Imagen de la firma del titular extraída del chip (DG7), cuando existe. Mismo comportamiento prefirmado de corta duración.
`chip_data`	object \| null	Objeto plano con los datos biográficos extraídos del chip. Siempre presente tras una lectura exitosa: `dgs` (lista de Data Groups leídos), `surname`, `name`, `country`, `nationality`, `birth_date` (`YYYY-MM-DD`), `expiry_date` (`YYYY-MM-DD`), `sex` (`M`/`F`), `document_type` (código de documento MRZ, p. ej., `P`), `document_number`, `optional_data`, los dígitos de control de la MRZ (`birth_date_hash`, `expiry_date_hash`, `document_number_hash`, `optional_data_hash`, `final_hash`), `mrz_string` y `mrz_type` (`TD1`/`TD2`/`TD3`). Cuando el chip incluye DG11, se añaden `place_of_birth` y `address` (y `full_name` / `full_name_non_latin` para documentos con un nombre no latino); en caso contrario, estas claves están ausentes, no son null. `null` cuando se omitió el paso NFC.
`authenticity`	object \| null	Resultados de la autenticación pasiva ICAO, que se detallan a continuación. `null` para una lectura JPKI.
`authenticity.sod_integrity`	boolean	`true` cuando la firma del SOD se encadena con una CSCA válida del país emisor y el DSC no está revocado ni expirado.
`authenticity.dg_integrity`	boolean	`true` cuando el hash de cada Data Group coincide con el valor firmado por el SOD. Un valor `false` significa que los datos del chip se manipularon o se leyeron parcialmente.
`certificate_summary`	object \| null	Resumen del DSC que firmó este chip: `issuer`, `subject`, `serial_number`, `not_valid_before`, `not_valid_after` (marcas de tiempo con formato `YYYY-MM-DD HH:MM:SS`), además de un objeto `validation` con los resultados de cada comprobación (`csca_verified`, `csca_missing`, `dsc_revoked`, `dsc_expired`, `csca_expired`). `csca_missing` es `true` cuando el ancla de confianza de la CSCA emisora del DSC no está disponible. `null` cuando no se pudo cargar el SOD o se omitió el paso.
`warnings[]`	array	Advertencias a nivel de módulo, cada una con `feature`, `risk`, `additional_data`, `log_type`, `short_description`, `long_description` y `node_id`; consulta Advertencias NFC.

Valores de estado

Estado	Significado	Efecto posterior
`Approved`	Se leyó el chip y no se activó ninguna advertencia con una acción de revisión o rechazo, incluido el caso en que se activaron advertencias cuya acción configurada es “Sin acción”.	Cuenta como una comprobación NFC correcta; por sí sola, no enviará la sesión a revisión.
`In Review`	Se activó una advertencia cuya acción configurada es revisión (`SKIPPED_NFC_VALIDATION`, `NFC_CHIP_NOT_VERIFIED`, `NFC_TRUST_ANCHOR_MISSING`, `NFC_AND_OCR_DATA_NOT_SAME` o una de las advertencias `JPKI_*`, según tu configuración).	La sesión también pasa a `In Review` hasta que un revisor actúe.
`Declined`	Se activó una advertencia cuya acción configurada es rechazo.	La sesión se rechaza, salvo que otra rama aprobada satisfaga el flujo.
`Not Finished`	El usuario abandonó el paso NFC, el dispositivo no era compatible con NFC o la lectura del chip nunca se completó.	La rama NFC no generó ningún resultado; revisa las alternativas del flujo.
`Resub Requested`	Un revisor solicitó que se volviera a enviar este paso.	Un nuevo intento sustituye a este informe cuando el usuario vuelve a intentarlo.

Las dos advertencias de certificado (DSC_CERTIFICATE_REVOKED, DSC_CERTIFICATE_EXPIRED) son informativas: aparecen en warnings[], pero por sí solas nunca cambian el status de NFC. Consulta Advertencias NFC para ver la matriz completa de comportamiento.

Ejemplos

Aprobado: chip leído y criptográficamente válido

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

Rechazado: discrepancia entre OCR y 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"
        }
      ]
    }
  ]
}

Tarjeta My Number de Japón (JPKI)

En los SDK nativos, la tarjeta My Number de Japón se lee mediante JPKI: la persona introduce el PIN de la tarjeta y la tarjeta firma un desafío de un solo uso (consulta cómo funciona). Su informe tiene chip_protocol: "jpki" y contiene la evidencia en jpki. portrait_image, signature_image, chip_data, authenticity y certificate_summary son null, porque la tarjeta no contiene datos ICAO.

La lectura de la tarjeta My Number mediante JPKI todavía no está habilitada en producción. Mientras no lo esté, una tarjeta My Number omite el paso NFC con el motivo de omisión JPKI_UNAVAILABLE.

Campos JPKI

Campo	Tipo	Descripción
`jpki.certificate_types`	array de `"user_authentication"` \| `"signature"`	Los certificados de la tarjeta que se leyeron. `user_authentication` (PIN de 4 dígitos) se lee siempre; `signature` (PIN de firma) se lee cuando la configuración `jpki_request_attributes` del nodo NFC está activada, que es el valor predeterminado.
`jpki.chain_valid`	boolean	`true` cuando cada certificado forma una cadena de confianza hasta la autoridad de certificación JPKI de su tipo, está dentro de su periodo de validez y es un certificado de tarjeta My Number de ese tipo.
`jpki.signature_valid`	boolean	`true` cuando se verifica cada firma que la tarjeta hizo sobre el desafío de un solo uso. La tarjeta solo firma después de que se introduce su PIN, así que esto demuestra que la persona tiene la tarjeta y conoce el PIN.
`jpki.revocation_status`	`"good"` \| `"revoked"` \| `"unchecked"`	`good`: se confirma que ningún certificado está revocado. `revoked`: un certificado está revocado, por ejemplo porque se denunció la pérdida de la tarjeta. `unchecked`: no hubo respuesta de revocación disponible, así que no se puede descartar que la tarjeta esté revocada; nunca se trata como `good`. La revocación solo se comprueba una vez que la cadena y la firma son válidas.
`jpki.ca_generation`	string \| null	Generación de la autoridad de certificación JPKI que emitió los certificados, por ejemplo `"2023"`. `null` cuando ningún certificado forma una cadena de confianza hasta una autoridad de certificación JPKI.
`jpki.certificate_expires_at`	string (ISO 8601) \| null	La fecha de caducidad más temprana entre los certificados leídos.
`jpki.certificates[]`	array	Una entrada por cada certificado leído: `type`, `chain_valid`, `signature_valid`, `ca_generation`, `not_valid_before`, `not_valid_after` y `failure`. `failure` es `null` cuando la cadena es válida; en caso contrario, es uno de `unreadable_certificate`, `untrusted_issuer`, `expired`, `not_yet_valid`, `wrong_policy` (no es un certificado de tarjeta My Number de ese tipo) o `key_usage`.
`jpki.attributes`	object \| null	Los datos del titular procedentes del certificado de firma, una vez que su cadena es válida: `full_name` (tal como está registrado, normalmente en escritura japonesa), `date_of_birth` (`YYYY-MM-DD`), `gender` (`M`, `F` o `null`), `address`, y `name_substitute_characters` / `address_substitute_characters`, que señalan los caracteres reemplazados por un sustituto porque están fuera del conjunto de caracteres estándar (`null` cuando no se reemplazó ninguno). `null` cuando no se solicitó el certificado de firma o su cadena no es válida.
`jpki.attributes_match_ocr`	boolean \| null	`true` cuando los atributos coinciden con los datos leídos de la foto de la misma tarjeta, `false` cuando alguno de ellos difiere (`JPKI_AND_OCR_DATA_NOT_SAME`), `null` cuando no se pudo comparar nada, incluido cuando `attributes` es `null`.
`jpki.mismatched_attributes`	array de string	Los atributos que difieren de los datos de la foto (`full_name`, `date_of_birth`, `gender`, `address`), nunca sus valores.

El informe nunca contiene los propios certificados, sus números de serie, las firmas ni el Número Individual (My Number) de 12 dígitos de la tarjeta, que el paso NFC nunca lee.

Ejemplo: lectura de una tarjeta My Number

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

Cuando la comprobación de revocación no está disponible para una lectura, el mismo informe tiene revocation_status: "unchecked", una advertencia JPKI_REVOCATION_UNCHECKED y status: "In Review" con la configuración predeterminada. Consulta Advertencias de NFC.

Nota de seguridad

Los datos del chip NFC están firmados por la autoridad emisora, por lo que un informe aprobado con sod_integrity: true y dg_integrity: true es la evidencia de identidad más sólida que Didit puede generar. Trata las URL firmadas de las imágenes (portrait_image, signature_image) como enlaces de corta duración: descárgalas sin demora y no las almacenes en caché de forma pública; vuelve a solicitar la decisión cuando necesites enlaces nuevos.

Relacionado

Advertencias de NFC: enum completo de advertencias, causas y soluciones.
Webhooks: escucha el evento de status.updated para recibir el informe NFC.
Modelos de datos: verificación NFC: esquema canónico con todos los campos.
Documentos compatibles: qué documentos electrónicos puede leer Didit mediante NFC.

Autenticación

Verificación

Monitorización

Plataforma

Informe de verificación NFC: chip y autenticidad

Descripción general

Dónde aparece en las respuestas de la API

Esquema

Valores de estado

Ejemplos

Aprobado: chip leído y criptográficamente válido

Rechazado: discrepancia entre OCR y chip

Tarjeta My Number de Japón (JPKI)

Campos JPKI

Ejemplo: lectura de una tarjeta My Number

Nota de seguridad

Relacionado

​Descripción general

​Dónde aparece en las respuestas de la API

​Esquema

​Valores de estado

​Ejemplos

​Aprobado: chip leído y criptográficamente válido

​Rechazado: discrepancia entre OCR y chip

​Tarjeta My Number de Japón (JPKI)

​Campos JPKI

​Ejemplo: lectura de una tarjeta My Number

​Nota de seguridad

​Relacionado

Descripción general

Dónde aparece en las respuestas de la API

Esquema

Valores de estado

Ejemplos

Aprobado: chip leído y criptográficamente válido

Rechazado: discrepancia entre OCR y chip

Tarjeta My Number de Japón (JPKI)

Campos JPKI

Ejemplo: lectura de una tarjeta My Number

Nota de seguridad

Relacionado