Verificación biométrica
Biométrico
Verificación biométrica
Validar una imagen de rostro contra sesiones KYC previamente aprobadas — en la API KYC de gu1 para flujos de verificación de identidad.
POST
Verificación biométrica
Resumen
El servicio Biométrico de Gu1 permite comprobar si una imagen de rostro corresponde a una persona que ya completó una validación KYC aprobada en tu organización. Enviás una sola imagen del rostro y la entidad a verificar (porentityId, entityExternalId o entityTaxId). La API compara esa cara con los datos biométricos guardados en sesiones de validación por sesión ya aprobadas para esa entidad. Si la cara coincide con alguna de esas sesiones aprobadas, la respuesta indica match y devuelve los IDs de las validaciones KYC asociadas.
Cómo funcionaEl servicio consulta las sesiones KYC aprobadas (creadas mediante validación por sesión) para la entidad indicada. Compara la cara que enviás con la información biométrica ya almacenada en esas sesiones aprobadas. No se inicia una nueva sesión alojada: es una verificación puntual contra datos existentes.
Prerrequisitos
Para que este endpoint funcione:- Gu1 Biometría activo para tu organización (producto
global_gueno_biometric_kyc). Si no está habilitado, la API responde 403NOT_ENABLED— solicitá la activación a Gu1. - KYC aprobado previo para la entidad (el servicio compara tu imagen contra sesiones KYC ya aprobadas).
- Configuración interna de captura provisionada por Gu1 (mismas credenciales técnicas que el KYC por sesión). Si falta, 403
NOT_CONFIGURED.
El servicio Biométrico es un servicio de Gu1. Toda la verificación se ejecuta en nuestra infraestructura; no se exponen nombres de proveedores externos en las respuestas ni en los errores.
Solicitud
Endpoint
Content-Type
Aceptamultipart/form-data o application/json.
Multipart — enviá la imagen del rostro de cualquiera de estas formas (igual que Face Match / ID Verification):
- Como archivo: campo
userImageouser_image(recomendado). - Como string base64: mismos nombres de campo con la imagen en base64 (con o sin prefijo
data:image/...;base64,).
user_image o userImage como base64, data URL o URL http(s) para que el servidor descargue la imagen. Identificadores de entidad: entityId, entityExternalId y/o entityTaxId.
Tenés que enviar al menos uno de entityId, entityExternalId o entityTaxId para que la API sepa contra qué entidad verificar.
Headers
X-Organization-Id.
Parámetros del body
Imagen del rostro. Multipart: campo
userImage o user_image como archivo o string base64 (con o sin prefijo data:image/...;base64,). JSON: user_image o userImage como base64, data URL o URL http(s). Formatos: JPEG, PNG, WebP, TIFF. Máx. 5MB.UUID de la entidad persona en Gu1. Es obligatorio enviar al menos uno de
entityId, entityExternalId o entityTaxId.Tu propio identificador de la entidad (ID externo). Si no enviás
entityId, la API resuelve la entidad por organización + externalId. Es obligatorio enviar al menos un identificador de entidad.Alias deprecado de
entityExternalId. Sigue aceptándose en POST /api/kyc/biometric por compatibilidad. Preferí entityExternalId en integraciones nuevas.Identificación fiscal de la entidad (CUIT, CPF, RFC, etc.). Si no enviás
entityId ni entityExternalId, la API resuelve la entidad por organización + tax_id normalizado (ignora guiones, puntos y otros caracteres de formato). Es obligatorio enviar al menos un identificador de entidad.Respuesta
Éxito (200 OK)
Ejemplo:
Ejemplo de solicitud
Respuestas de error
Relación con el KYC por sesión
- Validación por sesión (
POST /api/kyc/validations): Crea una sesión KYC, entrega una URL alojada al usuario y guarda el resultado (incluidos los datos biométricos) al completar el flujo. Esas sesiones son las que el endpoint Biométrico usa para comparar. - Biométrico (
POST /api/kyc/biometric): Enviás una imagen de rostro y se verifica si coincide con alguna sesión ya aprobada para esa entidad. Sirve para re-verificar a la misma persona (ej. en login o en una nueva acción) sin iniciar una nueva sesión.
Próximos pasos
Crear validación KYC
Iniciar una verificación por sesión
Face Match (Documento + Selfie)
Comparar dos imágenes en una llamada