Validación NFC

Validación NFC

La lectura NFC está disponible para reforzar la verificación de documentos directamente desde el chip del pasaporte o DNI. Solo aparece en el flujo móvil con el Soyio React Native SDK; si el usuario corre el flujo web o un SDK distinto, el paso no se mostrará aunque la plantilla lo tenga habilitado.

Activa NFC en tu plantilla

• Usa el campo mobile_nfc_enabled del template de disclosure_template y ponlo en true cuando crees o actualices la plantilla (ej. PATCH /api/v1/disclosure_templates/{id}).
• No es necesario cambiar los data_requirements; la lectura NFC se agrega como paso adicional cuando el SDK es compatible.

Ejemplo de actualización

{
  "mobile_nfc_enabled": true,
  "mobile_nfc_strictness": "strict"
}

SDK compatible

La lectura NFC solo está soportada en el Soyio React Native SDK usando la integración de componente (WebView). Si el usuario ejecuta el flujo en web, en InAppBrowser o en otro SDK, el paso no aparece aunque la plantilla tenga mobile_nfc_enabled en true. Usa strict solo en plantillas que se ejecuten exclusivamente en el SDK móvil React Native; si compartes una plantilla con flujos sin soporte NFC, la validación puede fallar aunque el paso no se muestre. Usa plantillas separadas para los flujos móviles y no móviles.

Controla el nivel de exigencia

Usa mobile_nfc_strictness para definir qué ocurre cuando el escaneo NFC falla (skip, error de chip, error MRZ). Solo aplica cuando mobile_nfc_enabled es true.

Valor	Comportamiento
always_passthrough	El resultado NFC es solo metadata; la validación no falla por NFC. Úsalo si quieres recopilar el resultado sin hacerlo requisito
flexible_on_unsupported	NFC es obligatorio excepto si el dispositivo no lo soporta. Si el dispositivo soporta NFC y falla, la validación falla
strict	NFC es siempre obligatorio. Si falla por cualquier razón o el dispositivo no soporta NFC, la validación falla. Es la opción recomendada si usas NFC para reforzar la validación

El backend usa always_passthrough por defecto. Si usas NFC para reforzar el proceso, cambia ese valor a strict. Usa flexible_on_unsupported solo si necesitas admitir dispositivos sin NFC.

Cómo leer los resultados

• Consulta performed_nfc_scan en el disclosure_request para saber si el paso se ejecutó. Puedes verlo en el listado de GET /api/v1/disclosure_requests o en el detalle de cada request.
• En los validation_attempts encuentras nfc_detail con el resultado específico (disponible en GET /api/v1/validation_attempts):
  • not_requested: la plantilla no tenía NFC activo o el flujo se ejecutó en un contexto sin soporte.
  • success: el chip se leyó correctamente.
  • failed: hubo un intento de lectura que no pudo completarse (chip dañado o error de lectura). El resultado depende de mobile_nfc_strictness: con always_passthrough puede terminar en successful; con flexible_on_unsupported o strict, el fallo puede hacer que falle la validación.

Errores NFC en la validación

Cuando mobile_nfc_strictness es flexible_on_unsupported o strict, una falla técnica de lectura puede hacer que la validación falle. Además, si el chip se lee pero su identidad no coincide con la biometría, la discrepancia bloquea el intento. Estos casos aparecen en el errors_array del manejo de errores:

code	type	message	detail
auth-074	document	nfc_validation_failed	La lectura NFC no fue exitosa
auth-075	document	nfc_not_supported_by_device	El dispositivo no soporta lectura NFC
auth-077	document	nfc_identity_mismatch	El chip se leyó, pero la identidad no coincide con la biometría

auth-074 representa una falla técnica de lectura y puede permitir un reintento. auth-077 representa una discrepancia de identidad después de leer el chip correctamente; bloquea el intento y no debe ofrecer un reintento al usuario.

El mismo errors_array puede incluir errores de la validación con bases de datos gubernamentales. En ese origen, auth-074 usa el message invalid_document_number y auth-075 usa government_api_error. Identifica un error NFC con la combinación de code, type, message y detail, no solo con code.

Revisa la tabla de códigos seleccionados para conocer el resto de los mapeos documentados.