Crear Validación KYC
Validación por sesión
Crear Validación KYC
Iniciar una sesión de verificación KYC para una entidad persona — en la API KYC de gu1 para flujos de verificación de identidad, con ejemplos para create.
POST
Crear Validación KYC
Resumen
Este endpoint crea una nueva sesión de validación KYC para una entidad persona usando un proveedor de integración configurado. Después de crear la validación, recibirás una URL de verificación que puedes compartir con tu cliente para completar la verificación de identidad.Diagrama de Flujo Completo
Secuencia desde la creación de la entidad hasta la validación KYC (flujo de producción; en sandbox con números de documento de prueba se omite el paso del proveedor y la API devuelve el resultado mock y los webhooks de inmediato—ver Datos mock en sandbox):Puntos Clave en el Flujo
Puntos Clave en el Flujo
1. Entidad y taxId duplicado
- Crea primero la entidad persona con
POST /api/entities(incluyecountryCode). Si eltaxIdya existe en la organización, la API devuelve 409 y no crea duplicado; usa el ID de la entidad existente. - Necesitas un
entityIdexistente para crear una validación KYC.
global_gueno_validation_kyces el código estándar para KYC completo y funciona en sandbox sin configuración adicional.
- En producción, la respuesta incluye
providerSessionUrl. Envía esa URL a tu usuario; completan el flujo en la página del proveedor (documento + selfie). La URL es válida hastaexpiresAt. - En sandbox, si el documento de la entidad está en la lista de prueba, no se usa sesión del proveedor: la API devuelve 201 con estado
pendingy momentos después actualiza la validación y envía los webhooks (p. ej.kyc.validation_approvedokyc.validation_rejected), sin paso del usuario. Importante: Debes tener configurado un webhook endpoint para recibir las respuestas - ver Datos mock en sandbox.
- Cuando termina la validación, la API envía un webhook a tu URL. El evento es uno de:
kyc.validation_approved,kyc.validation_rejected,kyc.validation_abandoned,kyc.validation_expired,kyc.validation_cancelled(no un único evento “completed”). El payload es el objeto de validación completo. - También puedes hacer polling a
GET /api/kyc/validations/:idpara actualizaciones de estado.
Prerrequisitos
Antes de crear una validación KYC:- La entidad persona debe existir: Crea una entidad persona usando la API de Entidades
- Integración KYC configurada: Tu organización debe tener un proveedor de integración KYC activado (ej:
global_gueno_validation_kyc) - API key válida: Autentica con tu clave API
Sandbox vs Producción: Los entornos sandbox NO requieren configuración de perfil ni preconfiguración. Puedes probar validaciones KYC inmediatamente en sandbox con datos de prueba. Los entornos de producción requieren:
- Proceso de onboarding de la organización completado
- Proveedor de integración KYC activado por el equipo de gu1
- Saldo de crédito suficiente para operaciones KYC
Datos mock (sandbox)
En sandbox, cuando el documento de la entidad persona (taxId) coincide con uno de nuestros valores de prueba, la API devuelve un resultado mock inmediato (p. ej. aprobado, rechazado, cancelado) y envía los webhooks correspondientes, sin ejecutar una verificación real. El formato del documento no importa (p. ej. 99.990.001 y 99990001 funcionan igual).
Para ver la lista completa de números de documento de prueba por formato (Argentina DNI/CUIT, Brasil CPF/CNPJ), resultados esperados y ejemplos de respuesta, consulta Datos mock en sandbox.
Comportamientos Importantes
taxId duplicado (POST /entities)
Múltiples Validaciones KYC por Entidad
Puedes crear múltiples validaciones KYC para la misma entidad:- Cada validación obtiene un ID y sesión únicos
- Solo la validación aprobada más reciente se marca como
isCurrent: true - Casos de uso: Re-verificación, validaciones expiradas, intentos fallidos
Solicitud
Endpoint
Headers
Parámetros de Query (opcionales)
En
true, activa el doble chequeo RENAPER para entidades Argentina. En estados terminales la API consulta el registro oficial (datos y, cuando aplica, biometría) y guarda el resultado en metadata. Solo si la verificación OCR KYC devuelve el estado approved un fallo de cruce puede rechazar automáticamente la validación; en in_review o rejected el chequeo es informativo (enforcementApplied: false). Requiere entidad de Argentina y credenciales RENAPER configuradas en la organización.Parámetros del Body
El UUID de la entidad persona a verificarTipo:
string (uuid)El código del proveedor de integración para validación KYCValor Estándar:
global_gueno_validation_kyc (recomendado para la mayoría de casos de uso)Tipo: string (longitud mínima: 1)¿Qué es integrationCode?El
integrationCode identifica qué integración de proveedor KYC usar para la verificación. Piénsalo como seleccionar el servicio de verificación.Códigos de Integración Disponibles:global_gueno_validation_kyc- Recomendado - KYC completo con documento + selfie + coincidencia facial + detección de vida- Es posible que se configuren códigos personalizados para tu organización (contacta a soporte)
- Inicia sesión en gu1 Dashboard
- Navega a Configuración → Integraciones → Proveedores KYC
- Tu código de integración activo estará listado allí
global_gueno_validation_kyc funciona inmediatamente sin configuración.Igual que el query param. En
true activa el doble chequeo RENAPER para Argentina. Puede enviarse en el body o como ?doubleCheckRenaper=true. Si van ambos, prevalece el query.Lista opcional de códigos de advertencia KYC (strings exactos). Se guarda en la validación como
metadata.omitWarnings. Cuando termina la sesión, si la validación quedaría en in_review, warnings no está vacío y todos los códigos de warnings están en esta lista, la API pasa el estado a approved y conserva las advertencias para UI y auditoría. Si alguna advertencia no está en omitWarnings, el estado sigue in_review. Si warnings está vacío pero el estado es in_review, no se auto-aprueba. Códigos inválidos o no permitidos en el body devuelven 400. Si aplica la regla, metadata.kycOmitWarningsApplied guarda la marca de tiempo y las advertencias coincidentes.Los códigos no omitibles (p. ej. GUENO_CROSS_ENTITY_DUPLICATED) se rechazan en este campo con 400 y siempre bloquean la auto-aprobación por omit aunque figuren en warnings.Tipo: string[] (cada elemento debe ser un código permitido; se ignoran duplicados)Respuesta
Respuesta Exitosa (201 Created)
metadata.doubleChecks.renaper: true. Tras aprobación y ejecución del chequeo, se rellena metadata.responseDoubleChecks.renaper (ver Doble chequeo RENAPER).
Campos de Respuesta
La URL de verificación para compartir con tu cliente
Estado actual de la validación. Valores posibles:
pending- Validación creada, esperando que el cliente iniciein_progress- Cliente completando la verificación (llenando formulario)in_review- Verificación completada, requiere revisión manual del equipo de complianceapproved- Verificación exitosarejected- Verificación fallidaexpired- Sesión de verificación expirada (ej. tras 7 días)abandoned- Cliente inició pero no completócancelled- Validación cancelada manualmente
Tras la aprobación, las claves de medios aparecen dentro de
decision. Para descargar archivos (imágenes, video), usá GET /api/kyc/validations/:id/media?key=... con Authorization: Bearer. Detalle completo: Obtener medios de la validación KYC.Ejemplo de Solicitud
Respuestas de Error
Entidad No Encontrada (404)
Tipo de Entidad Inválido (400)
KYC No Configurado (400)
Doble chequeo RENAPER (Argentina)
CondoubleCheckRenaper: true y entidad de Argentina, en cada estado terminal (approved, rejected, in_review) la API ejecuta una verificación cruzada contra el registro oficial (RENAPER) cuando hay datos OCR suficientes. El rechazo automático por RENAPER solo aplica si la verificación OCR KYC devolvió el estado approved.
Cómo enviarlo
- Body:
{ "entityId": "...", "integrationCode": "...", "doubleCheckRenaper": true } - Query:
POST /api/kyc/validations?doubleCheckRenaper=truecon el mismo body. Si van ambos, prevalece el query.
Dónde se guarda el resultado
Enmetadata.responseDoubleChecks.renaper. Los códigos de mismatch (p. ej. trámite y vencimiento) se añaden a metadata.warnings sin reemplazar advertencias previas de la verificación OCR KYC. errorCode en el objeto renaper conserva el primer fallo para compatibilidad; la UI puede listar todos los códigos desde comparisonResults y warnings.
Campos de metadata.responseDoubleChecks.renaper:
| Campo | Tipo | Descripción |
|---|---|---|
verified | boolean | true si el chequeo pasó. |
matchResult | string | "match" | "mismatch" | "error". |
verifiedAt | string | ISO timestamp del chequeo. |
personalNumber | string | Número de trámite desde KYC. |
idTramitePrincipal | string | Número de trámite desde RENAPER. |
renaperData | object | Respuesta cruda de RENAPER (ver forma de renaperData). |
comparisonResults | object | Comparación campo a campo entre OCR y registro (cuando aplica). |
renaperBiometric | object | Resultado biométrico ABIS (validate-dni): matchResult, score, renaperData (respuesta cruda). |
errorCode | string | Presente si falla; ver códigos abajo. |
Forma de renaperData
Es el body sin transformar que devuelve el registro vía ms-providers (POST …/provider-records/renaper/data). Gu1 lo reenvía tal cual en metadata.responseDoubleChecks.renaper.renaperData. Los nombres de campo están en snake_case; todos son opcionales según lo que devuelva RENAPER en cada consulta.
Ejemplo (doble chequeo exitoso, matchResult: "match"):
| Situación | renaperData típico |
|---|---|
Error antes de obtener datos (ej. RENAPER_DNI_MISSING) | {} |
Servicio no disponible (RENAPER_VERIFICATION_UNAVAILABLE) | { "error": "…", "code": "SERVICE_UNAVAILABLE" } |
| Cruce fallido con datos parciales del registro | Subconjunto de campos (ej. id_tramite_principal, apellido, nombres, fecha_nacimiento) |
Forma de comparisonResults
Mapa por campo (dni, tramite, name, ejemplar, dateOfBirth, expirationDate). Cada entrada puede incluir:
| Campo | Tipo | Descripción |
|---|---|---|
compared | boolean | true si se intentó comparar; false si se omitió por datos faltantes. |
passed | boolean | Resultado cuando compared es true. |
skipReason | string | ocr_missing, renaper_missing o both_missing cuando no se comparó. |
ocrValue | string | Valor extraído del OCR (si aplica). |
renaperValue | string | Valor del registro RENAPER (si aplica). |
similarityPercent | number | Solo en name: similitud Levenshtein (0–100). |
threshold | number | Solo en name: umbral aplicado (p. ej. 80). |
errorCode | string | Código de fallo del campo (p. ej. RENAPER_DNI_NOT_MATCH). |
ejemplar, el valor OCR es extractedData.ejemplar (ver campos de extractedData). La comparación corre cuando existen ambos valores OCR y RENAPER.
Ejemplo — extractedData en una validación KYC aprobada (Argentina):
Forma de renaperBiometric
Objeto anidado en metadata.responseDoubleChecks.renaper.renaperBiometric cuando la org tiene credenciales biométricas y la sesión KYC aporta selfie. Gu1 envía una selfie a validate-dni; RENAPER la compara con la foto del DNI en el registro.
| Campo | Tipo | Descripción |
|---|---|---|
verified | boolean | true si resultado.match del chequeo biométrico ABIS es positivo. |
matchResult | string | "match" | "mismatch" | "error". |
score | number | Puntuación devuelta por el chequeo biométrico (si aplica). |
verifiedAt | string | ISO timestamp del chequeo biométrico. |
renaperData | object | Respuesta cruda de validate-dni (incluye resultado.match, resultado.score, etc.). |
submittedSelfieRef | string | Referencia de la selfie enviada: ruta de almacenamiento (kyc/...) o URL (https://...). |
submittedSelfieRefKind | string | Formato de submittedSelfieRef: s3_key (ruta interna) | url (URL pública). |
submittedSelfiePickedFrom | string | Origen en decision: liveness_reference_image o face_match_target_image. |
errorCode | string | Si falla (p. ej. RENAPER_BIOMETRIC_NOT_MATCH). |
skipReason | string | Si no se ejecutó (p. ej. selfie no disponible). |
Ejemplo completo de responseDoubleChecks.renaper
renaperBiometric y entradas en comparisonResults pueden omitirse según credenciales, datos OCR o disponibilidad de selfie.
Códigos de error (cuando falla RENAPER)
El motivo del rechazo es un código enmetadata.warnings y en metadata.responseDoubleChecks.renaper.errorCode. La UI debe traducir estos códigos.
| Código | Significado |
|---|---|
RENAPER_DNI_MISSING | No se obtuvo número de documento (DNI) en la verificación. |
RENAPER_GENDER_MISSING | Falta género (M/F) para llamar a RENAPER. |
RENAPER_VERIFICATION_UNAVAILABLE | No se pudo completar la verificación cruzada (ej. error de red). Reintentar. |
RENAPER_DNI_NOT_MATCH | El número de documento no coincide con el registro oficial. |
RENAPER_TRAMITE_DATA_MISSING | Faltan datos para comparar el número de trámite. |
RENAPER_TRAMITE_ID_NOT_MATCH | El número de trámite del documento no coincide con el registro (ejemplar anterior, vencido o reemitido; la persona debe verificar de nuevo con DNI vigente). |
RENAPER_NAME_NOT_MATCH | El nombre del OCR no alcanza el 80% de similitud con el registro RENAPER. |
RENAPER_EJEMPLAR_NOT_MATCH | El ejemplar del DNI no coincide con el registro RENAPER. |
RENAPER_DOB_NOT_MATCH | La fecha de nacimiento del OCR no coincide con RENAPER. |
RENAPER_EXPIRY_NOT_MATCH | La fecha de vencimiento del OCR no coincide con RENAPER. |
RENAPER_BIOMETRIC_NOT_MATCH | La selfie no coincide con la foto del DNI en el registro biométrico. |
RENAPER_BIOMETRIC_UNAVAILABLE | No se pudo completar el chequeo biométrico (red, credenciales o servicio). |
Cuándo RENAPER aplica enforce (rechazo automático)
| Estado de la verificación OCR KYC | ¿RENAPER se ejecuta? | ¿Puede rechazar por RENAPER? |
|---|---|---|
approved (aprobación directa) | Sí | Sí — fallo de cruce → rejected |
in_review | Sí | No — informativo; el equipo decide en revisión manual |
rejected (rechazo de la verificación OCR o reglas Gu1) | Sí (si hay OCR) | No — informativo; deja datos en metadata |
Aprobación manual desde in_review (POST …/approve) | No (reutiliza el chequeo ya guardado) | No — decisión humana; no se re-ejecuta el cruce |
metadata.responseDoubleChecks.renaper (comparisonResults, renaperBiometric). En in_review y rejected los códigos RENAPER con mismatch se agregan a warnings junto con las advertencias de la verificación OCR.
Próximos Pasos
Después de crear una validación:- Extrae la URL de verificación de
providerSessionUrl - Comparte la URL con tu cliente vía email, SMS o en tu app
- Configura endpoint webhook para recibir notificaciones de finalización
- Monitorea el estado de validación usando el ID de validación
- Tras la aprobación, leé las claves en
decisiony descargá archivos — ver Obtener medios de la validación KYC
Obtener URL de KYC
Aprende cómo recuperar la URL
Integración Webhook
Configura notificaciones webhook