Skip to main content
POST
http://api.gu1.ai
/
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>"
}
'
{
  "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

Comprendiendo la secuencia completa desde la creación de la entidad hasta la validación KYC:
1. El entityId proviene de POST /entities
  • Sí, el entityId proviene de crear primero una entidad persona mediante POST /api/entities
  • No puedes crear una validación KYC sin una entidad existente
  • Guarda el entityId después de la creación de la entidad para usarlo en la solicitud de validación KYC
2. Código de Integración
  • global_gueno_validation_kyc es el código estándar para verificación KYC completa
  • Este código debe coincidir con una integración configurada para tu organización
  • En sandbox, este código funciona de inmediato sin configuración
3. URL de Verificación
  • El providerSessionUrl en la respuesta es lo que envías a tu usuario
  • Esta URL normalmente es válida por 30 días (verifica el campo expiresAt)
  • Los usuarios completan todo el flujo de verificación en la página alojada del proveedor
4. Webhook vs Polling
  • Los webhooks proporcionan notificación instantánea cuando se completa la verificación
  • También puedes hacer polling a GET /api/kyc/validations/:id para actualizaciones de estado
  • Mejor práctica: Usar webhooks + polling como respaldo

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

​
Comportamientos Importantes

​
Manejo de Entidades Duplicadas

¿Qué sucede si llamas a POST /entities múltiples veces con el mismo taxId?La API creará entidades duplicadas con diferentes UUIDs. Esto es por diseño para admitir casos de uso como:
  • Mantenimiento de registros históricos
  • Múltiples intentos de verificación
  • Diferentes contextos de entidad (ej: la misma persona en diferentes roles)
Mejor Práctica para Evitar Duplicados:
  1. Verifica si la entidad existe primero: Usa GET /api/entities?taxId=12345678 antes de crear
  2. Guarda el entityId en tu base de datos: Mapea tu ID de usuario al entityId de gu1
  3. Usa el entityId existente: Reutiliza la misma entidad para múltiples validaciones KYC
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' }
});

let entityId;
if (existing.data && existing.data.length > 0) {
  entityId = existing.data[0].id; // Usar entidad existente
} else {
  // Crear nueva entidad
  const newEntity = 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' })
  });
  entityId = newEntity.data.id;
}

// Ahora 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 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.

​
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"
  },
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-01-15T10:30:00Z"
}

​
Campos de Respuesta

​
providerSessionUrl
string
La URL de verificación para compartir con tu cliente
​
status
string
Estado actual: pending, in_progress, approved, rejected, expired, abandoned

​
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."
}

​
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