Skip to main content
POST
/
api
/
kyc
/
biometric
Verificación biométrica
curl --request POST \
  --url http://api.gu1.ai/api/kyc/biometric \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "user_image": "<string>",
  "entityId": "<string>",
  "externalEntityId": "<string>"
}
'

​
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 o externalEntityId). 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, tu organización debe tener configurada la validación KYC por sesión:
  1. Integración de validación por sesión activada: La integración usada para la validación por sesión (ej. “Gu1 KYC” / validación por sesión) debe estar activada para tu organización (ej. en Marketplace / Integraciones).
  2. Credenciales configuradas: La API key (y el webhook secret) de esa integración de validación por sesión debe estar configurada en la configuración KYC de la organización. El endpoint Biométrico usa las mismas credenciales que la validación por sesión para realizar la verificación.
Si esas credenciales no están configuradas o la integración no está activada, la API devuelve 403 (NOT_ENABLED o 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

POST https://api.gu1.ai/api/kyc/biometric

​
Content-Type

Podés enviar la solicitud en cualquiera de los dos formatos:
  • multipart/form-data: campos del form userImage o user_image (archivo o base64) y opcionales entityId, externalEntityId.
  • application/json: body con user_image (string base64) y opcionales entityId, externalEntityId.
Tenés que enviar al menos uno de entityId o externalEntityId para que la API sepa contra qué entidad verificar.

​
Headers

Authorization: Bearer TU_API_KEY
Content-Type: application/json
o, para multipart: 
Authorization: Bearer TU_API_KEY
Content-Type: multipart/form-data; boundary=----...
La organización se obtiene del contexto de autenticación; no hace falta enviar X-Organization-Id.

​
Parámetros del body

​
user_image
string
required
Imagen del rostro en base64 (con o sin prefijo data:image/...;base64,). En multipart usá el campo userImage o user_image y enviá un archivo o un string base64. Formatos: JPEG, PNG, WebP, TIFF. Máx. 5MB.
​
entityId
string
UUID de la entidad persona en Gu1. Es obligatorio enviar entityId o externalEntityId.
​
externalEntityId
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 entityId o externalEntityId.

​
Respuesta

​
Éxito (200 OK)

CampoTipoDescripción
matchbooleantrue si la cara coincidió con al menos una validación KYC aprobada en tu cuenta para esta entidad (ver nota abajo).
approvedSessionIdsstring[]IDs de sesión del servicio de verificación que se consideraron coincidencias aprobadas.
matchedKycValidationIdsstring[]IDs de las validaciones KYC en tu cuenta que corresponden a esas sesiones y tienen estado approved en nuestra base de datos.
Solo se devuelve match cuando la validación existe en nuestra base con estado approved. Si una sesión fue aprobada por el servicio de verificación pero nosotros la rechazamos después (ej. por desajuste con RENAPER), en nuestra base figurará como rechazada y no se contará como match. | faceSearch | object | Resumen: status, totalMatches, approvedMatchesCount, requestId (para soporte). | Ejemplo: 
{
  "match": true,
  "approvedSessionIds": ["session-abc-123"],
  "matchedKycValidationIds": ["550e8400-e29b-41d4-a716-446655440000"],
  "faceSearch": {
    "status": "Approved",
    "totalMatches": 1,
    "approvedMatchesCount": 1,
    "requestId": "req_xyz"
  }
}

​
Ejemplo de solicitud

const response = await fetch('https://api.gu1.ai/api/kyc/biometric', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer TU_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    user_image: 'data:image/jpeg;base64,/9j/4AAQ...',
    entityId: '550e8400-e29b-41d4-a716-446655440000',
  }),
});
const result = await response.json();
console.log('Match:', result.match, 'Validaciones KYC:', result.matchedKycValidationIds);

​
Respuestas de error

CódigoHTTPSignificado
NOT_CONFIGURED403Las credenciales de validación KYC por sesión no están configuradas en la organización.
NOT_ENABLED403La integración de validación KYC por sesión no está activada para esta organización.
INVALID_REQUEST400Body faltante o inválido (ej. falta user_image, o no se envió entityId ni externalEntityId).
NOT_FOUND404No se encontró entidad para el externalEntityId indicado en esta organización.
UNAUTHORIZED401Autenticación inválida o faltante.
VERIFICATION_FAILED500No se pudo completar la verificación; reintentar o contactar soporte.

​
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