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": {},
"entityId": "<string>",
"entityExternalId": "<string>",
"externalEntityId": "<string>",
"entityTaxId": "<string>"
}
'import requests
url = "http://api.gu1.ai/api/kyc/biometric"
payload = {
"user_image": {},
"entityId": "<string>",
"entityExternalId": "<string>",
"externalEntityId": "<string>",
"entityTaxId": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
user_image: {},
entityId: '<string>',
entityExternalId: '<string>',
externalEntityId: '<string>',
entityTaxId: '<string>'
})
};
fetch('http://api.gu1.ai/api/kyc/biometric', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "http://api.gu1.ai/api/kyc/biometric",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'user_image' => [
],
'entityId' => '<string>',
'entityExternalId' => '<string>',
'externalEntityId' => '<string>',
'entityTaxId' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "http://api.gu1.ai/api/kyc/biometric"
payload := strings.NewReader("{\n \"user_image\": {},\n \"entityId\": \"<string>\",\n \"entityExternalId\": \"<string>\",\n \"externalEntityId\": \"<string>\",\n \"entityTaxId\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("http://api.gu1.ai/api/kyc/biometric")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"user_image\": {},\n \"entityId\": \"<string>\",\n \"entityExternalId\": \"<string>\",\n \"externalEntityId\": \"<string>\",\n \"entityTaxId\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("http://api.gu1.ai/api/kyc/biometric")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"user_image\": {},\n \"entityId\": \"<string>\",\n \"entityExternalId\": \"<string>\",\n \"externalEntityId\": \"<string>\",\n \"entityTaxId\": \"<string>\"\n}"
response = http.request(request)
puts response.read_bodyBiomé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
/
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": {},
"entityId": "<string>",
"entityExternalId": "<string>",
"externalEntityId": "<string>",
"entityTaxId": "<string>"
}
'import requests
url = "http://api.gu1.ai/api/kyc/biometric"
payload = {
"user_image": {},
"entityId": "<string>",
"entityExternalId": "<string>",
"externalEntityId": "<string>",
"entityTaxId": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
user_image: {},
entityId: '<string>',
entityExternalId: '<string>',
externalEntityId: '<string>',
entityTaxId: '<string>'
})
};
fetch('http://api.gu1.ai/api/kyc/biometric', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "http://api.gu1.ai/api/kyc/biometric",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'user_image' => [
],
'entityId' => '<string>',
'entityExternalId' => '<string>',
'externalEntityId' => '<string>',
'entityTaxId' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "http://api.gu1.ai/api/kyc/biometric"
payload := strings.NewReader("{\n \"user_image\": {},\n \"entityId\": \"<string>\",\n \"entityExternalId\": \"<string>\",\n \"externalEntityId\": \"<string>\",\n \"entityTaxId\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("http://api.gu1.ai/api/kyc/biometric")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"user_image\": {},\n \"entityId\": \"<string>\",\n \"entityExternalId\": \"<string>\",\n \"externalEntityId\": \"<string>\",\n \"entityTaxId\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("http://api.gu1.ai/api/kyc/biometric")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"user_image\": {},\n \"entityId\": \"<string>\",\n \"entityExternalId\": \"<string>\",\n \"externalEntityId\": \"<string>\",\n \"entityTaxId\": \"<string>\"\n}"
response = http.request(request)
puts response.read_bodyResumen
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
POST https://api.gu1.ai/api/kyc/biometric
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
Authorization: Bearer TU_API_KEY
Content-Type: application/json
Authorization: Bearer TU_API_KEY
Content-Type: multipart/form-data; boundary=----...
X-Organization-Id.
Parámetros del body
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.string
UUID de la entidad persona en Gu1. Es obligatorio enviar al menos uno de
entityId, entityExternalId o entityTaxId.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.string
Alias deprecado de
entityExternalId. Sigue aceptándose en POST /api/kyc/biometric por compatibilidad. Preferí entityExternalId en integraciones nuevas.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)
| 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). |
{
"match": true,
"matchedSessionIds": ["session-abc-123"],
"matchedKycValidationIds": ["550e8400-e29b-41d4-a716-446655440000"],
"faceSearch": {
"totalMatches": 1,
"requestId": "req_xyz"
}
}
Ejemplo de solicitud
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);
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);
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 -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.
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
Was this page helpful?