Skip to main content
POST
Face Match (Documento + Selfie)

Resumen

Face Match es un servicio de verificación de Gu1 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 Gu1).
  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 Gu1. Toda la verificación se realiza en la infraestructura de Gu1.

Solicitud

Endpoint

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

No definas Content-Type a mano al usar FormData; el cliente lo setea con el boundary correcto. Si tu cuenta usa organización, incluí:

Campos del form

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.
file | string
required
Imagen de la selfie. Igual que documentImage: archivo o base64. Obligatorio.
string
UUID opcional de la entidad persona a asociar con esta verificación. Se usa para auditoría y para listar verificaciones por entidad.
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).
string
Referencia opcional (por ejemplo tu ID de usuario) para trazabilidad. Se guarda en el registro de auditoría.
boolean
Con true, tras aprobar el face match de Gu1 ejecuta RENAPER biométrico (validate-dni con la selfie) y datos (renaper/data: DNI + trámite). Requiere credenciales RENAPER de la org y integraciones Marketplace activas: ar_renaper_data_enrichment y ar_renaper_validate_dni_enrichment. El query prevalece sobre el body.
boolean
Igual que el query param doubleCheckRenaper.
string
DNI para RENAPER cuando doubleCheckRenaper=true. Opcional si entityId resuelve taxId o person.idNumber.
string
Género para RENAPER (M, F, male, female). Obligatorio salvo resolución desde entidad vinculada.
string
required
Número de trámite para el chequeo RENAPER. Obligatorio con doubleCheckRenaper=true.
El umbral mínimo (threshold) puede enviarse en el form; si no se envía, se lee de la configuración KYC de la organización. La respuesta incluye el umbral que se usó en la llamada.

Respuesta

Respuesta exitosa (200 OK)

Si falla RENAPER tras aprobación del proveedor, match pasa a false, status a "declined" y se añaden códigos RENAPER a warnings. Usá timeout HTTP ≥ 60 s con double-check. Ejemplo:

Ejemplo de solicitud

Respuestas de error

Códigos de error habituales:

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). Cada registro guardado también almacena el umbral usado en el momento de la llamada (para mostrarlo en el historial aunque cambie el umbral de la org).

Listar registros de auditoría

Parámetros de query: 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 rutas de imagen opcionales para auditoría.

Obtener verificación por ID

Obtiene un registro de auditoría de Face Match por su verificationId (devuelto en la respuesta del POST o en el listado).
Parámetro de path: id — UUID de la verificación (igual 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 estás autenticado.

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 face match 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 solicitud. No crea un registro en kyc_validations. Usalo cuando necesitás una verificación puntual (p. ej. «¿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 define 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