Skip to main content
POST
/
api
/
kyc
/
validations
Crear Validación KYC
curl --request POST \
  --url http://api.gu1.ai/api/kyc/validations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "entityId": "<string>",
  "integrationCode": "<string>",
  "doubleCheckRenaper": true
}
'
{
  "providerSessionUrl": "<string>",
  "status": "<string>"
}

​
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):
1. Entidad y taxId duplicado
  • Crea primero la entidad persona con POST /api/entities (incluye countryCode). Si el taxId ya existe en la organización, la API devuelve 409 y no crea duplicado; usa el ID de la entidad existente.
  • Necesitas un entityId existente para crear una validación KYC.
2. Código de integración
  • global_gueno_validation_kyc es el código estándar para KYC completo y funciona en sandbox sin configuración adicional.
3. URL de verificación
  • 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 hasta expiresAt.
  • 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 pending y momentos después actualiza la validación y envía los webhooks (p. ej. kyc.validation_approved o kyc.validation_rejected), sin paso del usuario. Importante: Debes tener configurado un webhook endpoint para recibir las respuestas - ver Datos mock en sandbox.
4. Eventos de webhook
  • 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/:id para actualizaciones de estado.

​
Prerrequisitos

Antes de crear una validación KYC:
  1. La entidad persona debe existir: Crea una entidad persona usando la API de Entidades
  2. Integración KYC configurada: Tu organización debe tener un proveedor de integración KYC activado (ej: global_gueno_validation_kyc)
  3. 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
Para comenzar en sandbox, simplemente usa tu clave API de sandbox - no se necesita configuración adicional.

​
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)

¿Qué sucede si llamas a POST /entities con un taxId que ya existe?La API no crea una segunda entidad. Devuelve 409 Conflict con código de error DUPLICATE_TAX_ID e incluye en los detalles el id, name y type de la entidad existente.Qué hacer:
  1. Opción A – Consultar antes: Usa GET /api/entities?taxId=12345678 (o el endpoint by-tax-id) antes de crear. Si existe la entidad, usa su entityId para KYC.
  2. Opción B – Manejar el 409: Si recibes 409, lee error.details.existingEntityId en la respuesta y usa ese entityId para tu validación KYC.
  3. Reutilizar la misma entidad: Usa una entidad por persona/empresa y crea varias validaciones KYC sobre ese mismo entityId si necesitas re-verificación o nuevos intentos.
Ejemplo – Verificar antes de crear:
// Verificar si la entidad existe
const existing = await fetch('https://api.gu1.ai/api/entities?taxId=12345678', {
  headers: { 'Authorization': 'Bearer TU_API_KEY' }
});
const data = await existing.json();

let entityId;
if (data.data && data.data.length > 0) {
  entityId = data.data[0].id; // Usar entidad existente
} else {
  const createRes = await fetch('https://api.gu1.ai/api/entities', {
    method: 'POST',
    headers: { 'Authorization': 'Bearer TU_API_KEY', 'Content-Type': 'application/json' },
    body: JSON.stringify({ type: 'person', taxId: '12345678', name: 'Juan Pérez', countryCode: 'AR' })
  });
  const created = await createRes.json();
  entityId = created.entity?.id ?? created.data?.id;
}

// Crear validación KYC con el entityId

​
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

POST https://api.gu1.ai/api/kyc/validations

​
Headers

{
  "Authorization": "Bearer TU_API_KEY",
  "Content-Type": "application/json"
}

​
Parámetros de Query (opcionales)

​
doubleCheckRenaper
boolean
En true, activa el doble chequeo RENAPER para entidades Argentina. Tras la aprobación del proveedor KYC, la API valida el documento contra el registro oficial (RENAPER). Si falla, la validación pasa a rejected y el motivo se guarda como código en metadata.warnings y en metadata.responseDoubleChecks.renaper.errorCode. Requiere entidad de Argentina y credenciales RENAPER configuradas en la organización.

​
Parámetros del Body

​
entityId
string
required
El UUID de la entidad persona a verificarTipo: string (uuid)
​
integrationCode
string
required
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)
Cómo encontrar tu código de integración:
  1. Inicia sesión en gu1 Dashboard
  2. Navega a Configuración → Integraciones → Proveedores KYC
  3. Tu código de integración activo estará listado allí
En entornos sandbox, global_gueno_validation_kyc funciona inmediatamente sin configuración.
​
doubleCheckRenaper
boolean
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.

​
Respuesta

​
Respuesta Exitosa (201 Created)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "entityId": "123e4567-e89b-12d3-a456-426614174000",
  "organizationId": "org_abc123",
  "sessionId": "session_xyz789",
  "status": "pending",
  "provider": "kyc_provider",
  "providerSessionUrl": "https://verify.example.com/session_xyz789",
  "isCurrent": true,
  "metadata": {
    "customField": "customValue",
    "doubleChecks": { "renaper": true }
  },
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-01-15T10:30:00Z"
}
Cuando el doble chequeo RENAPER está activo, en creación se guarda metadata.doubleChecks.renaper: true. Tras aprobación y ejecución del chequeo, se rellena metadata.responseDoubleChecks.renaper (ver Doble chequeo RENAPER).

​
Campos de Respuesta

​
providerSessionUrl
string
La URL de verificación para compartir con tu cliente
​
status
string
Estado actual de la validación. Valores posibles:
  • pending - Validación creada, esperando que el cliente inicie
  • in_progress - Cliente completando la verificación (llenando formulario)
  • in_review - Verificación completada, requiere revisión manual del equipo de compliance
  • approved - Verificación exitosa
  • rejected - Verificación fallida
  • expired - Sesión de verificación expirada (ej. tras 7 días)
  • abandoned - Cliente inició pero no completó
  • cancelled - Validación cancelada manualmente

​
Ejemplo de Solicitud

const response = await fetch('https://api.gu1.ai/api/kyc/validations', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer TU_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    entityId: '123e4567-e89b-12d3-a456-426614174000',
    integrationCode: 'global_gueno_validation_kyc'
  })
});

const validation = await response.json();
console.log('URL de verificación:', validation.providerSessionUrl);

​
Respuestas de Error

​
Entidad No Encontrada (404)

{
  "error": "ENTITY_NOT_FOUND",
  "message": "Entity not found"
}

​
Tipo de Entidad Inválido (400)

{
  "error": "INVALID_ENTITY_TYPE",
  "message": "KYC validation is only available for person entities"
}

​
KYC No Configurado (400)

{
  "error": "KYC_NOT_CONFIGURED",
  "message": "La integración KYC no está configurada for this organization. Please contact your administrator."
}

​
Doble chequeo RENAPER (Argentina)

Con doubleCheckRenaper: true y entidad de Argentina, tras la aprobación del proveedor KYC la API ejecuta una verificación cruzada contra el registro oficial (RENAPER). Si falla, la validación pasa a rejected y el motivo se guarda en metadata.

​
Cómo enviarlo

  • Body: { "entityId": "...", "integrationCode": "...", "doubleCheckRenaper": true }
  • Query: POST /api/kyc/validations?doubleCheckRenaper=true con el mismo body. Si van ambos, prevalece el query.

​
Dónde se guarda el resultado

En metadata.responseDoubleChecks.renaper. Si falla, un código se añade también a metadata.warnings. Campos de metadata.responseDoubleChecks.renaper:
CampoTipoDescripción
verifiedbooleantrue si el chequeo pasó.
matchResultstring"match" | "mismatch" | "error".
verifiedAtstringISO timestamp del chequeo.
personalNumberstringNúmero de trámite desde KYC.
idTramitePrincipalstringNúmero de trámite desde RENAPER.
renaperDataobjectRespuesta cruda de RENAPER.
errorCodestringPresente si falla; ver códigos abajo.

​
Códigos de error (cuando falla RENAPER)

El motivo del rechazo es un código en metadata.warnings y en metadata.responseDoubleChecks.renaper.errorCode. La UI debe traducir estos códigos.
CódigoSignificado
RENAPER_DNI_MISSINGNo se obtuvo número de documento (DNI) en la verificación.
RENAPER_GENDER_MISSINGFalta género (M/F) para llamar a RENAPER.
RENAPER_VERIFICATION_UNAVAILABLENo se pudo completar la verificación cruzada (ej. error de red). Reintentar.
RENAPER_DNI_NOT_MATCHEl número de documento no coincide con el registro oficial.
RENAPER_TRAMITE_DATA_MISSINGFaltan datos para comparar el número de trámite.
RENAPER_TRAMITE_ID_NOT_MATCHEl 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).

​
Próximos Pasos

Después de crear una validación:
  1. Extrae la URL de verificación de providerSessionUrl
  2. Comparte la URL con tu cliente vía email, SMS o en tu app
  3. Configura endpoint webhook para recibir notificaciones de finalización
  4. Monitorea el estado de validación usando el ID de validación

Obtener URL de KYC

Aprende cómo recuperar la URL

Integración Webhook

Configura notificaciones webhook