Skip to main content

​
Resumen

Después de que un cliente complete su verificación KYC, puedes consultar los resultados para verificar el estado, datos extraídos y detalles de decisión.
Aunque puedes consultar esta API, recomendamos fuertemente usar webhooks para recibir notificaciones en tiempo real cuando se complete la verificación.

​
Obtener Validación por ID

GET https://api.gu1.ai/api/kyc/validations/{id}

​
Ejemplo

const validationId = '550e8400-e29b-41d4-a716-446655440000';

const response = await fetch(
  `https://api.gu1.ai/api/kyc/validations/${validationId}`,
  {
    headers: {
      'Authorization': 'Bearer TU_API_KEY'
    }
  }
);

const validation = await response.json();

console.log('Estado:', validation.status);
console.log('Verificado:', validation.status === 'approved');

if (validation.status === 'approved') {
  console.log('Datos verificados:', validation.extractedData);
  console.log('Campos verificados:', validation.verifiedFields);
}

​
Obtener Validación Actual para Entidad

GET https://api.gu1.ai/api/kyc/entities/{entityId}/current

​
Obtener Estado KYC de Entidad

GET https://api.gu1.ai/api/kyc/entities/{entityId}/status

​
Respuesta

{
  "entityId": "123e4567-e89b-12d3-a456-426614174000",
  "hasKyc": true,
  "isVerified": true,
  "currentValidation": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "approved",
    "metadata",
    "verifiedAt": "2025-01-15T11:00:00Z"
  },
  "lastVerifiedAt": "2025-01-15T11:00:00Z",
  "expiresAt": "2026-01-15T11:00:00Z",
  "needsReverification": false
}

​
Valores de Estado

​
status
string
Estado actual de validación:
  • pending - Validación creada, esperando que el cliente inicie
  • in_progress - Cliente está completando activamente la verificación
  • approved - Verificación exitosa, identidad confirmada
  • rejected - Verificación fallida, identidad no confirmada
  • expired - Sesión de verificación expiró (típicamente después de 7 días)
  • abandoned - Cliente inició pero no completó la verificación

​
Objeto de Decisión

Cuando el estado es approved o rejected, el campo decision contiene resultados detallados: 
{
  "decision": {
    "document_details": {
      "type": "passport",
      "number": "AB123456",
      "country": "AR"
    },
    "extracted_information": {
      "firstName": "Juan",
      "lastName": "Pérez",
      "dateOfBirth": "1990-05-20",
      "nationality": "AR"
    },
    "verification_results": {
      "documentAuthenticity": "pass",
      "faceMatch": "pass",
      "liveness": "pass",
      "aml": "clear"
    },
    "warnings": []
  }
}

​
Patrones de Integración Comunes

​
Patrón 1: Verificar Antes de Permitir Acción

async function requerirVerificacion(entityId) {
  const status = await fetch(
    `https://api.gu1.ai/api/kyc/entities/${entityId}/status`,
    {
      headers: { 'Authorization': 'Bearer TU_API_KEY' }
    }
  ).then(r => r.json());

  if (!status.isVerified) {
    throw new Error('El cliente debe completar verificación de identidad');
  }

  if (status.needsReverification) {
    throw new Error('La verificación de identidad expiró. Por favor reverifica.');
  }

  return true;
}

​
Patrón 2: Características Condicionales Según Verificación

async function obtenerCaracteristicasCliente(entityId) {
  const status = await obtenerEstadoKyc(entityId);

  return {
    caracteristicasBasicas: true,
    caracteristicasAvanzadas: status.isVerified,
    transaccionesAltoLimite: status.isVerified && !status.needsReverification,
    transferenciasInternacionales: status.isVerified && tieneAprobacionAml(status)
  };
}

​
Mejores Prácticas

En lugar de verificar repetidamente el estado de validación, usa webhooks para recibir notificaciones en tiempo real.
Almacena el estado de verificación en tu base de datos y actualízalo vía webhooks. No consultes la API en cada solicitud.
Las verificaciones pueden expirar después de cierto período (típicamente 1 año). Verifica needsReverification y solicita a los clientes reverificar cuando sea necesario.

​
Próximos Pasos

Crear Validación KYC

Iniciar nueva sesión de verificación

Integración Webhook

Obtener notificaciones en tiempo real