Saltar al contenido principal
POST
Validación biométrica de Unico IDCloud: compara la selfie del usuario con el rostro asociado a su CPF y devuelve si se trata de la misma persona, de una persona distinta o si el resultado no es concluyente. Didit ofrece este servicio a través de POST /v3/database-validation/ para que puedas verificar los datos enviados contra la fuente oficial y recibir resultados de coincidencia normalizados.

Cobertura

  • Cobertura: 96%
  • País: Brasil
  • ID del servicio: bra_unico_idcloud
  • Dominio de datos: Identidad
  • Categoría: BiometricRiskScore
Alrededor del 96% de los titulares de CPF brasileños se resuelven en un registro biométrico en el registro de Unico, aproximadamente el doble del alcance de la fuente gubernamental de coincidencia facial, Datavalid, que ronda el 50%.

Datos de entrada

  • Datos obligatorios: tax_number, selfie
  • Datos opcionales: first_name, last_name, full_name, date_of_birth, vendor_data
  • Consentimiento: Obligatorio
  • Disponibilidad en flujos de verificación (workflow): Disponible en flujos
  • Cobertura: 96%
  • Precio: $0.20 por consulta exitosa

Parámetros del cuerpo

string
predeterminado:"BRA"
requerido
Código de país ISO 3166-1 alfa-3 para este servicio de base de datos.Ejemplo: BRA
string
predeterminado:"bra_unico_idcloud"
requerido
Array que contiene el ID de este servicio. Fijar el servicio limita la solicitud a esta base de datos concreta.Ejemplo: bra_unico_idcloud
Consentimiento explícito del usuario final para este servicio.Ejemplo: true
string
predeterminado:"11111111111"
requerido
Número de identificación fiscal o tributaria.Ejemplo: 11111111111
file
requerido
Archivo de imagen de la selfie que se sube para la validación biométrica en la base de datos. Formatos aceptados: JPEG, PNG o WebP.Ejemplo: @./selfie.jpg
string
Nombre de pila que se va a validar.Ejemplo: John
string
Apellido que se va a validar.Ejemplo: Doe
string
Nombre legal completo que se va a validar.Ejemplo: John Doe
string
Fecha de nacimiento en formato YYYY-MM-DD.Ejemplo: 1990-01-01
string
predeterminado:"user-1234"
Tu referencia estable de usuario para esta persona, como tu ID de usuario interno. Didit la usa para vincular las comprobaciones independientes con el mismo usuario final y reducir el ruido en la detección de duplicados.Ejemplo: user-1234

Reglas de entrada y notas de validación

  • CPF brasileño (exactamente 11 dígitos)
  • tax_number debe contener solo dígitos; elimina espacios, guiones y signos de puntuación antes de enviar la solicitud.
  • tax_number debe tener exactamente 11 caracteres.

Cómo invocarlo

Datos devueltos

Los campos exactos que aparecen en source_data dependen de lo que devuelva el registro. El ejemplo generado para bra_unico_idcloud documenta actualmente esta estructura normalizada:
  • unico_face_match

Precios y SLA

Las consultas a BRA - Unico IDCloud (CPF + selfie) se facturan solo cuando Didit recibe un resultado concluyente de la fuente de validación.
  • Precio por llamada: $0.20 USD.
  • Facturación: por consulta exitosa. No se te cobra cuando el registro no está disponible, cuando faltan campos obligatorios o cuando la solicitud se rechaza antes de llegar a la fuente.
  • Latencia: p95 típico < 2 s.
  • Disponibilidad: 99.9% por trimestre del lado de Didit; la disponibilidad de la fuente externa varía según el país y el conjunto de datos.

Acerca de esta fuente

Unico es una empresa brasileña de IDtech que opera el mayor registro privado de biometría facial del país. Su plataforma IDCloud almacena más de mil millones de embeddings faciales y suma unos 35 millones de rostros nuevos cada mes, alimentada por los flujos de onboarding y reautenticación de más de 800 empresas brasileñas, entre ellas cuatro de los cinco mayores bancos. Esa escala es la que explica la cifra de cobertura indicada arriba: una consulta por CPF devuelve un registro biométrico para aproximadamente el 96% de los adultos brasileños. Didit tiene una alianza directa con Unico, así que puedes consultar IDCloud a través de la API estándar de Validación de base de datos: pagas por llamada, sin contrato aparte con Unico, sin volumen mínimo y sin proceso de onboarding. En qué se diferencia del registro gubernamental. Didit también ofrece Brasil - CPF + coincidencia facial (Datavalid), que es la fuente oficial de SERPRO y la opción adecuada cuando necesitas específicamente que el registro gubernamental sea tu fuente de verdad. IDCloud es la mejor opción para todo lo demás, en dos aspectos que puedes comprobar: llega a aproximadamente el 96% de los adultos frente a aproximadamente el 50% de Datavalid, y compara contra un registro biométrico que mantiene IDCloud, en lugar de contra un retrato tomado de un documento que te entrega el usuario, por lo que resiste tanto la falsificación de documentos como el fraude con CPF robados. Además, cuesta menos de la mitad por consulta.

Flujo recomendado para Brasil

En la mayoría de los casos de uso en Brasil no necesitas captura de documentos. El usuario te proporciona un CPF y una selfie con prueba de vida confirma que es la persona a la que corresponde.
1

Recopila el CPF

Tu única entrada de texto es el CPF de 11 dígitos: sin foto del documento y sin nombre ni fecha de nacimiento introducidos manualmente.Como en este flujo no se lee ningún documento, Didit no tiene de dónde obtener el CPF a menos que le indiques su origen. Envíalo en el metadata de la sesión al crearla y asígnalo como la entrada tax_number del paso de Validación de base de datos. En la Business Console, esto se hace en la asignación de entradas del paso; a través de la API de flujos, es el database_validation_field_sources del nodo:
Después, crea cada sesión con el valor bajo esa clave:
Sin la asignación, el paso se ejecuta igualmente, pero informa que falta tax_number y nunca consulta el registro: no se factura nada, y la entrada database_validations de la sesión incluye el motivo.
2

Captura la selfie con prueba de vida

Añade un paso de prueba de vida al mismo flujo y elige el método que se ajuste a tu tolerancia al riesgo: Prueba de vida pasiva (sin ninguna acción del usuario), Flash 3D o Acción 3D y Flash (métodos activos que proyectan patrones de luz; el último añade una acción aleatoria). Configúralo con face_liveness_method (PASSIVE, FLASHING o ACTIVE_3D) en la Business Console o a través de la API de flujos. Elijas el que elijas, Didit muestra el paso de captura y confirma que se trata de una persona real y presente: esto es lo que impide que se envíe una foto almacenada o la reproducción de una pantalla.
3

Valida el CPF y la selfie con Unico IDCloud

Dentro de un flujo de sesión, Didit reutiliza automáticamente la selfie de la prueba de vida (nunca manejas la imagen) y lee el CPF a partir de la asignación anterior. Después, IDCloud confirma si ese rostro pertenece a la persona titular del CPF. El paso solo necesita estas dos entradas; si además envías full_name o date_of_birth en metadata y los asignas, se pasan a Unico como verificaciones cruzadas, pero no son obligatorios.
Este flujo basado solo en el CPF se aplica a las integraciones de sesión y flujo, en las que Didit realiza la captura y pasa la selfie de la prueba de vida a este servicio en tu nombre. Si llamas a POST /v3/database-validation/ directamente, selfie es una entrada de archivo obligatoria y debes proporcionar la imagen tú mismo; consulta la descripción general de Validación de base de datos para ver ambos modos.
Coste: unos $0.30 por usuario verificado con Prueba de vida pasiva ($0.20 por la consulta a IDCloud más $0.10 por la prueba de vida), o unos $0.35 con un método activo, en el que la prueba de vida cuesta $0.15. Son precios de lista: el descuento de tu plan se aplica a cada uno de ellos; consulta los precios. Alternativa para el 4% aproximado sin cobertura. Cuando IDCloud devuelve INCONCLUSIVE, el registro no pudo asociar ese CPF a un registro biométrico utilizable, normalmente porque la persona no figura en él. Trátalo como una “respuesta no concluyente” y no como una verificación fallida, y recurre a la Verificación de identidad completa: captura del documento más coincidencia facial con el retrato del documento. Todos siguen pudiendo verificarse, y solo pagas la verificación de documentos para el pequeño resto. Gestión de rechazos. BIOMETRIC_NO_MATCH significa que el registro determinó activamente que no hay coincidencia: el rostro no pertenece a ese CPF. Trátalo como un resultado negativo sólido y no como una invitación a reintentar: enviar al usuario directamente a la captura de documentos es justo el camino que quiere un impostor, ya que el documento es el elemento que controla. Aun así, los falsos negativos genuinos ocurren (un cambio de apariencia, una foto antigua en el registro o una captura deficiente), así que deriva estos casos a revisión manual en lugar de aprobarlos automáticamente o dejar al usuario sin salida. BIOMETRIC_IMAGE_UNUSABLE es distinto: simplemente no se pudo leer la selfie, así que pide una nueva. Decide qué efecto tiene cada resultado en la sesión con las acciones de Partial Match / No Match, y consulta los códigos de resultado para ver la lista completa. Usuarios recurrentes. Solo necesitas pagar una consulta al registro una vez. Cuando un usuario supera este flujo, la selfie de la prueba de vida se almacena asociada a su vendor_data, de modo que más adelante puedes volver a verificarlo con Autenticación biométrica (una prueba de vida más una coincidencia facial con ese rostro almacenado) por $0.10, con la misma elección de métodos de prueba de vida. Ten en cuenta que esto es específicamente para usuarios recurrentes: una sesión de autenticación biométrica necesita un rostro almacenado (o un portrait_image que tú proporciones) y falla al crearse si el usuario no tiene ninguno de los dos, por lo que los usuarios nuevos siguen pasando por el flujo anterior.

Continúa leyendo

Última modificación el 1 de noviembre de 2026