Skip to main content
POST
http://api.gu1.ai
/
api
/
kyc
/
face-match
Face Match (Documento + Selfie)
curl --request POST \
  --url http://api.gu1.ai/api/kyc/face-match \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "documentImage": "<string>",
  "selfieImage": "<string>",
  "entityId": "<string>",
  "vendorData": "<string>"
}
'

​
Resumen

Face Match es un servicio de verificación de Gueno que compara dos imágenes: una selfie (foto actual de la persona) y una imagen de referencia del documento (por ejemplo el retrato del DNI). La API devuelve si las caras coinciden (misma persona) y una puntuación de similitud. No hay sesión alojada ni detección de vida en tiempo real: enviás las imágenes y obtenés el resultado en una sola llamada.
Cuándo usar cada uno
  • KYC por sesión (POST /api/kyc/validations): Flujo completo con URL alojada, selfie en vivo, liveness y captura de documento. Ideal para onboarding y flujos regulados.
  • Face Match (POST /api/kyc/face-match): Enviás dos imágenes en Base64 y recibís coincidencia + puntuación. Ideal cuando ya tenés documento y selfie (por ejemplo desde tu propia app).

​
Prerrequisitos

Antes de usar Face Match:
  1. Integración Face Match activada: Tu organización debe tener la integración KYC Face Match activada (por ejemplo en Marketplace / Integraciones).
  2. Credenciales configuradas: La API key y el webhook secret de la integración Face Match deben estar configurados en la configuración KYC de la organización (lo define el administrador de Gueno).
  3. Umbral (opcional): El puntaje mínimo para aprobar (0–100) se configura en Configuración de la organización → KYC (tarjeta Face Match). Si no se define, el valor por defecto es 30. Solo los administradores de la organización pueden cambiar este valor.
Face Match es un servicio de Gueno. Toda la verificación se realiza en nuestra infraestructura; no se exponen nombres de proveedores externos en las respuestas ni en los mensajes de error.

​
Solicitud

​
Endpoint

POST https://api.gu1.ai/api/kyc/face-match

​
Headers

{
  "Authorization": "Bearer TU_API_KEY",
  "Content-Type": "application/json"
}
Si tu cuenta usa organización, incluí: 
X-Organization-Id: TU_ORGANIZATION_ID

​
Parámetros del Body

​
documentImage
string
required
Imagen de referencia (por ejemplo el retrato del documento) en Base64. Con o sin prefijo data:image/...;base64,. Formatos: JPEG, PNG, WebP, TIFF. Máx. 5MB por imagen.
​
selfieImage
string
required
Imagen de la selfie en Base64. Mismo formato y límite de tamaño que documentImage.
​
entityId
string
UUID opcional de la entidad persona a asociar con esta verificación. Se usa para auditoría y para listar verificaciones por entidad.
​
vendorData
string
Referencia opcional (por ejemplo tu ID de usuario) para trazabilidad. Se guarda en el registro de auditoría.
El puntaje mínimo (umbral) usado para decidir coincidencia o no no se envía en la solicitud. Se toma de la configuración KYC de tu organización (Configuración de la organización → KYC → Face Match). La respuesta incluye el umbral que se usó en la llamada.

​
Respuesta

​
Respuesta exitosa (200 OK)

CampoTipoDescripción
matchbooleanSi las caras se consideraron coincidentes (puntuación ≥ umbral).
scorenumberPuntuación de similitud 0–100.
statusstring"approved" | "declined" | "in_review".
verificationIdstringID del registro de auditoría en face_match_verifications (soporte y listado).
scoreDeclineThresholdnumberEl umbral (0–100) que se usó en esta verificación (configuración de la org).
requestIdstring (opcional)ID interno de la solicitud (soporte).
warningsstring[] (opcional)Advertencias de la verificación.
Ejemplo: 
{
  "match": true,
  "score": 85.5,
  "status": "approved",
  "verificationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "scoreDeclineThreshold": 30,
  "requestId": "req_xyz",
  "warnings": []
}

​
Ejemplo de solicitud

const response = await fetch('https://api.gu1.ai/api/kyc/face-match', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer TU_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    documentImage: 'data:image/jpeg;base64,/9j/4AAQ...',
    selfieImage: 'data:image/jpeg;base64,/9j/4AAQ...',
    entityId: '123e4567-e89b-12d3-a456-426614174000',
  }),
});

const result = await response.json();
console.log('Match:', result.match, 'Score:', result.score);

​
Respuestas de error

Las respuestas usan mensajes genéricos (sin nombres de proveedores). Códigos habituales:
CódigoHTTPSignificado
NOT_CONFIGURED403Credenciales de Face Match no configuradas en la organización.
NOT_ENABLED403La integración Face Match no está activada para esta organización.
INVALID_REQUEST400Imágenes inválidas o faltantes (formato/tamaño).
UNAUTHORIZED401Credenciales de API/verificación inválidas o faltantes.
QUOTA_EXCEEDED403No se pudo completar la verificación (cuota/créditos).
SERVICE_UNAVAILABLE503Servicio de verificación no disponible temporalmente.
VERIFICATION_FAILED500Fallo genérico; reintentar o usar otras imágenes.

​
Auditoría y listado de verificaciones

Cada solicitud de Face Match (éxito o fallo) se guarda en face_match_verifications para auditoría y cumplimiento. La respuesta incluye verificationId (ID del registro de auditoría). En cada registro se guarda también el umbral usado en ese momento (para poder mostrarlo en el historial aunque luego se cambie el umbral de la organización).

​
Listar registros de auditoría

GET https://api.gu1.ai/api/kyc/face-match/verifications?entityId={entityId}&limit=50&offset=0
Parámetros de query:
ParámetroTipoDescripción
entityIdstring (UUID)Opcional. Filtrar por entidad persona.
statusstringOpcional. Filtrar por estado (approved, declined, in_review, failed).
limitnumberCantidad máxima (por defecto 50, máx. 100).
offsetnumberDesplazamiento para paginación.
Respuesta: { "verifications": [ ... ], "scoreDeclineThreshold": 30, "pagination": { "limit", "offset", "total" } }. Cada verificación incluye id, entityId, status, match, score, threshold (valor usado en esa ejecución), createdAt y opcionalmente rutas de imágenes para auditoría.

​
Obtener verificación por ID

Obtener un único registro de auditoría de Face Match por su verificationId (devuelto en la respuesta del POST o en el listado). 
GET https://api.gu1.ai/api/kyc/face-match/verifications/:id
Parámetro de path: id — UUID de la verificación (el mismo que verificationId del POST o del listado). Respuesta (200): Un objeto de verificación con los mismos campos que cada ítem del listado: id, organizationId, entityId, status, match, score, requestId, vendorData, errorMessage, triggeredByUserId, createdAt, documentStoragePath, selfieStoragePath, storageProvider, threshold. Errores: 404 NOT_FOUND si el ID no existe o pertenece a otra organización; 401 UNAUTHORIZED si no hay autenticación.

​
Convivencia con KYC por sesión

  • Flujo por sesión crea un registro en kyc_validations, envía al usuario a una URL alojada y actualiza el estado vía webhooks. La decisión almacenada incluye documento, liveness y coincidencia facial de la sesión en vivo.
  • Face Match crea un registro de auditoría en face_match_verifications y devuelve el resultado en la misma respuesta. No crea un registro en kyc_validations. Úsalo cuando necesites una verificación puntual (por ejemplo “¿estas dos imágenes son la misma persona?”) sin sesión alojada.
  • Ambos usan la misma configuración KYC de la organización. El umbral de Face Match se configura en Configuración de la organización → KYC (tarjeta Face Match).

​
Próximos pasos

Crear Validación KYC

Verificación por sesión con URL alojada

Listar Validaciones

Listar validaciones KYC por entidad