> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gu1.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# 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.
## 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 funciona**
El servicio consulta las sesiones KYC aprobadas (creadas mediante [validación por sesión](/es/use-cases/kyc/create-validation)) 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
```
POST https://api.gu1.ai/api/kyc/biometric
```
### 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
```
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
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)
| Campo | Tipo | Descripción |
| ------------------------- | --------- | ------------------------------------------------------------------------------------------------- |
| `match` | boolean | `true` si el rostro coincide con al menos una validación KYC **approved** de esta entidad en Gu1. |
| `matchedSessionIds` | string\[] | Session IDs de las validaciones approved que matchearon. |
| `matchedKycValidationIds` | string\[] | IDs de esas validaciones KYC en Gu1. |
| `faceSearch` | object | Resumen: `totalMatches`, `requestId` (para soporte). |
**Ejemplo:**
```json theme={null}
{
"match": true,
"matchedSessionIds": ["session-abc-123"],
"matchedKycValidationIds": ["550e8400-e29b-41d4-a716-446655440000"],
"faceSearch": {
"totalMatches": 1,
"requestId": "req_xyz"
}
}
```
## Ejemplo de solicitud
```javascript JSON body (entityTaxId) theme={null}
const response = await fetch('https://api.gu1.ai/api/kyc/biometric', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json',
},
body: JSON.stringify({
user_image: 'data:image/jpeg;base64,/9j/4AAQ...',
entityTaxId: '20-41873887-2',
}),
});
const result = await response.json();
console.log('Match:', result.match, 'KYC validations:', result.matchedKycValidationIds);
```
```javascript JSON body theme={null}
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);
```
```javascript Multipart (archivo) theme={null}
const form = new FormData();
form.append('userImage', imageFile);
form.append('entityId', '550e8400-e29b-41d4-a716-446655440000');
const response = await fetch('https://api.gu1.ai/api/kyc/biometric', {
method: 'POST',
headers: { 'Authorization': 'Bearer TU_API_KEY' },
body: form,
});
const result = await response.json();
```
```curl cURL (multipart) theme={null}
curl -X POST https://api.gu1.ai/api/kyc/biometric \
-H "Authorization: Bearer TU_API_KEY" \
-F "userImage=@selfie.jpg" \
-F "entityId=550e8400-e29b-41d4-a716-446655440000"
```
## Respuestas de error
| Código | HTTP | Significado |
| --------------------- | ---- | -------------------------------------------------------------------------------------------------------------------------- |
| `NOT_CONFIGURED` | 403 | Las credenciales de validación KYC por sesión no están configuradas en la organización. |
| `NOT_ENABLED` | 403 | La integración de validación KYC por sesión no está activada para esta organización. |
| `INVALID_REQUEST` | 400 | Body faltante o inválido (ej. falta `user_image`, o no se envió ninguno de `entityId`, `entityExternalId`, `entityTaxId`). |
| `NOT_FOUND` | 404 | No se encontró entidad para el `entityId`, `entityExternalId` o `entityTaxId` indicado en esta organización. |
| `UNAUTHORIZED` | 401 | Autenticación inválida o faltante. |
| `VERIFICATION_FAILED` | 500 | No 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
Iniciar una verificación por sesión
Comparar dos imágenes en una llamada