Face Match (Documento + Selfie)

Verificar que una selfie y la foto del documento corresponden a la misma persona en una sola llamada a la API

POST /api/kyc/face-match

Face Match (Documento + Selfie)

cURL

curl --request POST \
  --url http://api.gu1.ai/api/kyc/face-match \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "documentImage": {},
  "selfieImage": {},
  "entityId": "<string>",
  "scoreThreshold": 123,
  "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 (como archivos o 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

Content-Type

Solo se acepta multipart/form-data. Podés enviar las imágenes de dos formas (o combinar):

1. Como archivos: adjuntar archivos de imagen en los campos del form documentImage y selfieImage.
2. Como cadenas base64: enviar los mismos nombres de campo con la imagen en base64 (con o sin prefijo data:image/...;base64,).

Si falta una imagen obligatoria (ni archivo ni base64 para ese campo), la API devuelve 400. Para cada imagen, si enviás archivo y base64, se usa el archivo.

Headers

Authorization: Bearer TU_API_KEY
Content-Type: multipart/form-data; boundary=----...

No definas Content-Type a mano al usar FormData; el cliente lo setea con el boundary correcto.

Si tu cuenta usa organización, incluí:

X-Organization-Id: TU_ORGANIZATION_ID

Campos del form

documentImage · file | string · required

Imagen de referencia (por ejemplo el retrato del documento). Enviar como archivo (recomendado) o como string (base64, con o sin prefijo data:image/...;base64,). Formatos: JPEG, PNG, WebP, TIFF. Máx. 5MB.

selfieImage · file | string · required

Imagen de la selfie. Igual que documentImage: archivo o base64. Obligatorio.

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.

scoreThreshold · number

Opcional. Umbral 0–100; resultados por debajo se rechazan. Si se omite, se usa el umbral configurado en la organización (o 30 por defecto).

vendorData · string

Referencia opcional (por ejemplo tu ID de usuario) para trazabilidad. Se guarda en el registro de auditoría.

Respuesta

Respuesta exitosa (200 OK)

Campo	Tipo	Descripción
match	boolean	Si las caras se consideraron coincidentes (puntuación ≥ umbral).
score	number	Puntuación de similitud 0–100.
status	string	"approved" | "declined" | "in_review".
verificationId	string	ID del registro de auditoría en face_match_verifications.
scoreDeclineThreshold	number	Umbral (0–100) usado en esta verificación (configuración de la org).
requestId	string (opcional)	ID interno de la solicitud (soporte).
warnings	string[] (opcional)	Array de códigos de riesgo (p. ej. LOW_FACE_MATCH_SIMILARITY, NO_REFERENCE_IMAGE). Ver Códigos de riesgo en advertencias.

Ejemplo de solicitud

Node.js (archivos)

const form = new FormData();
form.append('documentImage', documentFile);
form.append('selfieImage', selfieFile);
form.append('entityId', '123e4567-e89b-12d3-a456-426614174000');

const response = await fetch('https://api.gu1.ai/api/kyc/face-match', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer TU_API_KEY' },
  body: form,
});
const result = await response.json();

Errores

Código	HTTP	Significado
NOT_CONFIGURED	403	Credenciales Face Match no configuradas en la organización.
NOT_ENABLED	403	Integración Face Match no activada.
INVALID_REQUEST	400	Content-Type no es multipart/form-data o faltan/imagen inválida (sin archivo ni base64 para un campo obligatorio).
UNAUTHORIZED	401	Credenciales inválidas o faltantes.
VERIFICATION_FAILED	500	Fallo genérico; reintentar u otras imágenes.

Auditoría y listado

Cada solicitud se guarda en face_match_verifications. Para listar:

GET https://api.gu1.ai/api/kyc/face-match/verifications?entityId={entityId}&limit=50&offset=0

Para obtener una verificación por ID:

GET https://api.gu1.ai/api/kyc/face-match/verifications/:id

Próximos pasos

Crear validación KYC

Verificación por sesión con URL alojada

Face Match (Documento + Selfie)

Comparar documento y selfie