Skip to main content
GET
/
api
/
kyc
/
entities
/
{entityId}
/
current
Obtener Validación KYC Actual
curl --request GET \
  --url http://api.gu1.ai/api/kyc/entities/{entityId}/current \
  --header 'Authorization: Bearer <token>'

​
Descripción General

Este endpoint recupera la validación KYC activa actual para una entidad específica. La validación “actual” es la validación más reciente marcada con isCurrent: true. Características principales:
  • Retorna la validación activa de una entidad
  • Sincroniza automáticamente con el proveedor KYC si las imágenes expiraron (> 3.5 horas)
  • Incluye todos los datos de verificación (documentos, biometría, evaluación de riesgo)
  • Retorna 404 si no existe una validación actual

​
Cuándo Usar Esto

  • Verificar estado de validación: Ver si una entidad tiene una validación KYC activa
  • Mostrar datos de verificación: Mostrar resultados de verificación de documentos y biometría en tu UI
  • Validar identidad del usuario: Verificar si un usuario completó el KYC antes de permitir ciertas acciones
  • Controles de cumplimiento: Verificar que una entidad tiene documentación KYC válida

​
Solicitud

​
Endpoint

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

​
Parámetros de Ruta

​
entityId
string
required
El ID de la entidad para obtener la validación actual

​
Encabezados

{
  "Authorization": "Bearer TU_API_KEY"
}

​
Respuesta

​
Respuesta Exitosa (200 OK)

Retorna el objeto de validación actual con todos los datos de verificación: 
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "entityId": "123e4567-e89b-12d3-a456-426614174000",
  "organizationId": "org_abc123",
  "validationSessionId": "session_xyz789",
  "status": "approved",
  "provider": "Gu1 KYC",
  "providerSessionUrl": "https://verify.example.com/session_xyz789",
  "isCurrent": true,
  "decision": {
    "status": "Approved",
    "features": ["id_verification", "liveness", "face_match"],
    "id_verification": {
      "status": "Approved",
      "document_type": "Passport",
      "document_number": "AB123456",
      "full_name": "Juan Pérez",
      "date_of_birth": "1990-01-15",
      "nationality": "AR"
    },
    "liveness": {
      "status": "Approved",
      "score": 95
    },
    "face_match": {
      "status": "Approved",
      "score": 98
    }
  },
  "extractedData": {
    "firstName": "Juan",
    "lastName": "Pérez",
    "dateOfBirth": "1990-01-15",
    "documentNumber": "AB123456",
    "documentType": "Passport",
    "nationality": "AR"
  },
  "documentsVerified": [
    {
      "type": "Passport",
      "verified": true,
      "verifiedAt": "2025-01-27T10:30:00Z"
    }
  ],
  "biometricResult": {
    "livenessScore": 0.95,
    "faceMatchScore": 0.98,
    "passed": true,
    "timestamp": "2025-01-27T10:30:00Z"
  },
  "riskAssessment": {
    "riskLevel": "low"
  },
  "verifiedFields": [
    "firstName",
    "lastName",
    "dateOfBirth",
    "nationality",
    "documentNumber",
    "documentType"
  ],
  "warnings": [],
  "verifiedAt": "2025-01-27T10:30:00Z",
  "createdAt": "2025-01-27T09:00:00Z",
  "updatedAt": "2025-01-27T10:30:00Z",
  "metadata": {
    "integrationCode": "global_gueno_validation_kyc",
    "integrationName": "Gu1 KYC"
  }
}

​
Ejemplo de Solicitud

const entityId = '123e4567-e89b-12d3-a456-426614174000';

const response = await fetch(
  `https://api.gu1.ai/api/kyc/entities/${entityId}/current`,
  {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer TU_API_KEY',
    },
  }
);

const validation = await response.json();
console.log('Estado de validación actual:', validation.status);
console.log('Verificado en:', validation.verifiedAt);

​
Respuestas de Error

​
No Se Encontró Validación Actual (404)

{
  "error": "NOT_FOUND",
  "message": "No current KYC validation found for this entity"
}
Esto significa que la entidad:
  • Nunca tuvo una validación KYC creada
  • Tiene validaciones, pero ninguna está marcada como actual (isCurrent: false)
  • Todas las validaciones están en estados terminales (cancelada, expirada, etc.)

​
Entidad No Encontrada (404)

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

​
Notas Importantes

Si las imágenes de la validación tienen más de 3.5 horas, este endpoint sincroniza automáticamente con el proveedor KYC para refrescar los datos. Esto asegura que siempre obtengas imágenes y datos de verificación frescos.
Solo una validación por entidad puede tener isCurrent: true a la vez. Cuando se crea una nueva validación, la validación actual anterior se marca automáticamente como no actual. Usa el endpoint /api/kyc/entities/:entityId/validations para recuperar validaciones históricas.
Posibles valores del campo status:
  • pending - Validación creada, el usuario no ha comenzado
  • in_progress - El usuario está completando la verificación (llenando formulario)
  • in_review - Verificación completada, requiere revisión manual del equipo de compliance
  • approved - Verificación aprobada (por el proveedor o manualmente)
  • rejected - Verificación rechazada (por el proveedor o manualmente)
  • expired - Validación expiró (el usuario no completó a tiempo)
  • abandoned - El usuario comenzó pero abandonó el proceso
  • cancelled - Validación cancelada manualmente
Si una validación fue aprobada, rechazada o cancelada manualmente, NO será actualizada por webhooks del proveedor u operaciones de sincronización. Las decisiones manuales están protegidas para mantener la integridad del registro de auditoría.

​
Próximos Pasos

Crear Validación KYC

Iniciar una nueva sesión de verificación

Listar Todas las Validaciones

Ver historial de validaciones de una entidad

Sincronizar Validación

Refrescar manualmente los datos de validación

Aprobar Validación

Aprobar manualmente una validación