Skip to main content
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 (por entityId, 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:
  1. Gu1 Biometría activo para tu organización (producto global_gueno_biometric_kyc). Si no está habilitado, la API responde 403 NOT_ENABLED — solicitá la activación a Gu1.
  2. KYC aprobado previo para la entidad (el servicio compara tu imagen contra sesiones KYC ya aprobadas).
  3. 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

Acepta multipart/form-data o application/json. Multipart — enviá la imagen del rostro de cualquiera de estas formas (igual que Face Match / ID Verification):
  1. Como archivo: campo userImage o user_image (recomendado).
  2. Como string base64: mismos nombres de campo con la imagen en base64 (con o sin prefijo data:image/...;base64,).
Si falta la imagen (sin archivo ni base64), la API responde 400. JSON — enviá 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

o, para multipart:
La organización se obtiene del contexto de autenticación; no hace falta enviar X-Organization-Id.

Parámetros del body

user_image
file | string
required
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.
entityId
string
UUID de la entidad persona en Gu1. Es obligatorio enviar al menos uno de entityId, entityExternalId o entityTaxId.
entityExternalId
string
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.
externalEntityId
string
Alias deprecado de entityExternalId. Sigue aceptándose en POST /api/kyc/biometric por compatibilidad. Preferí entityExternalId en integraciones nuevas.
entityTaxId
string
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.
Ambos usan las mismas credenciales de la organización para la validación KYC por sesión. Si esas credenciales no están configuradas, el endpoint Biométrico no puede ejecutarse.

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