Listar Validaciones KYC de una Entidad

Descripción General

Este endpoint recupera el historial completo de validaciones KYC de una entidad específica. Esto es útil para auditorías, seguimiento de cumplimiento y comprensión del proceso de verificación de una entidad. Características principales:

Retorna todas las validaciones (actuales e históricas) de una entidad
Soporta paginación para historiales grandes de validaciones
Incluye detalles completos de verificación para cada validación
Ordenado por fecha de creación (más reciente primero)
Muestra qué validación está actualmente activa

Cuándo Usar Esto

Auditar historial de verificación: Ver todos los intentos de KYC y sus resultados
Reportes de cumplimiento: Rastrear intentos de verificación para cumplimiento regulatorio
Soporte al usuario: Investigar por qué falló o tuvo éxito la verificación de un usuario
Analíticas: Analizar tasas de éxito de verificación y patrones de abandono
Depuración: Solucionar problemas de verificación revisando el historial completo

Solicitud

Endpoint

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

Parámetros de Ruta

entityId

string

required

El UUID de la entidad para recuperar validaciones

Parámetros de Query

page

integer

default:"1"

Número de página para paginación (comienza en 1)

limit

integer

default:"100"

Número de validaciones por página (máx 100)

status

string

Filtrar validaciones por estado. Valores posibles:

pending - Validación creada, usuario no ha comenzado
in_progress - Usuario está completando activamente 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 - Validación expirada (usuario no completó a tiempo)
abandoned - Usuario comenzó pero no completó
cancelled - Validación fue cancelada por la organización

isCurrent

boolean

Filtrar para mostrar solo la validación activa actual (true) o validaciones históricas (false)

Encabezados

{
  "Authorization": "Bearer YOUR_API_KEY"
}

Respuesta

Respuesta Exitosa (200 OK)

Retorna una lista paginada de validaciones:

{
  "validations": [
    {
      "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",
      "workflow_type": "standard",
      "session_id": "7c0fa22d-0cfa-4a78-8090-7c842397e788",
      "session_number": 921,
      "features": ["ID_VERIFICATION", "LIVENESS", "FACE_MATCH", "IP_ANALYSIS"],
      "images": {
        "documentFront": "kyc/global_gueno_validation_kyc/org-uuid/entity-uuid/validation-uuid/document-front.jpg",
        "documentBack": "kyc/global_gueno_validation_kyc/org-uuid/entity-uuid/validation-uuid/document-back.jpg",
        "selfie": "kyc/global_gueno_validation_kyc/org-uuid/entity-uuid/validation-uuid/selfie.jpg"
      },
      "id_verification": {
        "status": "Approved",
        "node_id": "feature_ocr",
        "document_type": "Passport",
        "document_number": "AB123456",
        "first_name": "John",
        "last_name": "Doe",
        "full_name": "John Doe",
        "date_of_birth": "1990-05-20",
        "nationality": "US",
        "gender": "M",
        "age": 35,
        "issuing_state": "US",
        "expiration_date": "2030-05-20",
        "date_of_issue": "2020-05-20",
        "front_image": "kyc/global_gueno_validation_kyc/org-uuid/entity-uuid/validation-uuid/document-front.jpg",
        "back_image": "kyc/global_gueno_validation_kyc/org-uuid/entity-uuid/validation-uuid/document-back.jpg",
        "portrait_image": "kyc/global_gueno_validation_kyc/org-uuid/entity-uuid/validation-uuid/selfie.jpg",
        "warnings": [],
        "matches": []
      },
      "id_verifications": [
        {
          "status": "Approved",
          "node_id": "feature_ocr",
          "document_type": "Passport",
          "document_number": "AB123456",
          "first_name": "John",
          "last_name": "Doe",
          "full_name": "John Doe",
          "date_of_birth": "1990-05-20",
          "nationality": "US",
          "gender": "M",
          "age": 35,
          "issuing_state": "US",
          "expiration_date": "2030-05-20",
          "date_of_issue": "2020-05-20",
          "front_image": "kyc/global_gueno_validation_kyc/org-uuid/entity-uuid/validation-uuid/document-front.jpg",
          "back_image": "kyc/global_gueno_validation_kyc/org-uuid/entity-uuid/validation-uuid/document-back.jpg",
          "portrait_image": "kyc/global_gueno_validation_kyc/org-uuid/entity-uuid/validation-uuid/selfie.jpg",
          "warnings": [],
          "matches": []
        }
      ],
      "liveness": {
        "status": "Approved",
        "node_id": "feature_liveness",
        "score": 98,
        "method": "PASSIVE",
        "reference_image": "kyc/global_gueno_validation_kyc/org-uuid/entity-uuid/validation-uuid/liveness-reference.jpg",
        "video_url": "kyc/global_gueno_validation_kyc/org-uuid/entity-uuid/validation-uuid/liveness-video.webm",
        "face_quality": 92.5,
        "warnings": [],
        "matches": []
      },
      "liveness_checks": [
        {
          "status": "Approved",
          "node_id": "feature_liveness",
          "score": 98,
          "method": "PASSIVE",
          "reference_image": "kyc/global_gueno_validation_kyc/org-uuid/entity-uuid/validation-uuid/liveness-reference.jpg",
          "video_url": "kyc/global_gueno_validation_kyc/org-uuid/entity-uuid/validation-uuid/liveness-video.webm",
          "face_quality": 92.5,
          "warnings": [],
          "matches": []
        }
      ],
      "face_match": {
        "status": "Approved",
        "node_id": "feature_face_match",
        "score": 95,
        "source_image": "kyc/global_gueno_validation_kyc/org-uuid/entity-uuid/validation-uuid/document-front.jpg",
        "target_image": "kyc/global_gueno_validation_kyc/org-uuid/entity-uuid/validation-uuid/selfie.jpg",
        "warnings": []
      },
      "face_matches": [
        {
          "status": "Approved",
          "node_id": "feature_face_match",
          "score": 95,
          "source_image": "kyc/global_gueno_validation_kyc/org-uuid/entity-uuid/validation-uuid/document-front.jpg",
          "target_image": "kyc/global_gueno_validation_kyc/org-uuid/entity-uuid/validation-uuid/selfie.jpg",
          "warnings": []
        }
      ],
      "aml_screening": {
        "status": "Approved",
        "node_id": "feature_aml",
        "warnings": []
      },
      "aml_screenings": [
        {
          "status": "Approved",
          "node_id": "feature_aml",
          "warnings": []
        }
      ],
      "ip_analysis": {
        "status": "Approved",
        "node_id": "feature_ip_analysis",
        "ip_address": "203.0.113.10",
        "country": "US",
        "region": "New York",
        "city": "New York",
        "is_vpn": false,
        "is_proxy": false,
        "warnings": []
      },
      "ip_analyses": [
        {
          "status": "Approved",
          "node_id": "feature_ip_analysis",
          "ip_address": "203.0.113.10",
          "country": "US",
          "region": "New York",
          "city": "New York",
          "is_vpn": false,
          "is_proxy": false,
          "warnings": []
        }
      ]
    },
      "extractedData": {
        "firstName": "John",
        "lastName": "Doe",
        "dateOfBirth": "1990-01-15",
        "documentType": "Passport"
      },
      "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"
      }
    },
    {
      "id": "440e8400-e29b-41d4-a716-446655440001",
      "entityId": "123e4567-e89b-12d3-a456-426614174000",
      "organizationId": "org_abc123",
      "validationSessionId": "session_abc456",
      "status": "abandoned",
      "provider": "Gu1 KYC",
      "providerSessionUrl": "https://verify.example.com/session_abc456",
      "isCurrent": false,
      "decision": null,
      "extractedData": null,
      "verifiedAt": null,
      "createdAt": "2025-01-20T14:00:00Z",
      "updatedAt": "2025-01-21T10:00:00Z",
      "metadata": {
        "integrationCode": "global_gueno_validation_kyc",
        "integrationName": "Gu1 KYC"
      }
    }
  ],
  "total": 2,
  "page": 1,
  "limit": 100
}

Campos de Respuesta

validations

array

Array de objetos de validación

total

integer

Número total de validaciones que coinciden con la consulta

page

integer

Número de página actual

limit

integer

Número de validaciones por página

Ejemplos de Solicitudes

Obtener Todas las Validaciones de una Entidad

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

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

const result = await response.json();
console.log(`Se encontraron ${result.total} validaciones`);
console.log(`Página actual: ${result.page} de ${Math.ceil(result.total / result.limit)}`);

result.validations.forEach(validation => {
  console.log(`${validation.id}: ${validation.status} (${validation.isCurrent ? 'actual' : 'histórica'})`);
});

Filtrar por Estado

Obtener solo validaciones aprobadas:

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

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

const result = await response.json();
console.log(`Se encontraron ${result.total} validaciones aprobadas`);

Obtener Solo la Validación Actual

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

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

const result = await response.json();

if (result.validations.length > 0) {
  const currentValidation = result.validations[0];
  console.log('Estado de validación actual:', currentValidation.status);
} else {
  console.log('No se encontró validación actual');
}

Ejemplo de Paginación

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

async function getAllValidations(entityId) {
  let page = 1;
  const limit = 50;
  let allValidations = [];

  while (true) {
    const response = await fetch(
      `https://api.gu1.ai/api/kyc/entities/${entityId}/validations?page=${page}&limit=${limit}`,
      {
        method: 'GET',
        headers: {
          'Authorization': 'Bearer YOUR_API_KEY',
        },
      }
    );

    const result = await response.json();
    allValidations = allValidations.concat(result.validations);

    console.log(`Página ${page} obtenida: ${result.validations.length} validaciones`);

    // Verificar si hemos obtenido todas las validaciones
    if (allValidations.length >= result.total) {
      break;
    }

    page++;
  }

  return allValidations;
}

const validations = await getAllValidations(entityId);
console.log(`Total de validaciones obtenidas: ${validations.length}`);

Respuestas de Error

Entidad No Encontrada (404)

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

Parámetros de Query Inválidos (400)

{
  "error": "VALIDATION_ERROR",
  "message": "Invalid status value. Must be one of: pending, in_progress, approved, rejected, expired, abandoned, cancelled"
}

No Autorizado (401)

{
  "error": "UNAUTHORIZED",
  "message": "Invalid or missing API key"
}

Casos de Uso

1. Pista de Auditoría para Cumplimiento

Rastrear todos los intentos de verificación para cumplimiento regulatorio:

async function getVerificationAuditTrail(entityId) {
  const response = await fetch(
    `https://api.gu1.ai/api/kyc/entities/${entityId}/validations`,
    {
      headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
    }
  );

  const result = await response.json();

  // Generar reporte de auditoría
  const auditReport = result.validations.map(v => ({
    validationId: v.id,
    status: v.status,
    provider: v.provider,
    createdAt: v.createdAt,
    completedAt: v.verifiedAt || v.updatedAt,
    isCurrent: v.isCurrent,
    manualAction: v.metadata?.manuallyApprovedBy || v.metadata?.manuallyRejectedBy,
  }));

  return auditReport;
}

2. Calcular Tasa de Éxito

Analizar tasas de éxito de verificación:

async function calculateSuccessRate(entityId) {
  const response = await fetch(
    `https://api.gu1.ai/api/kyc/entities/${entityId}/validations`,
    {
      headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
    }
  );

  const result = await response.json();
  const validations = result.validations;

  const completed = validations.filter(v =>
    ['approved', 'rejected'].includes(v.status)
  );

  const approved = validations.filter(v => v.status === 'approved');
  const rejected = validations.filter(v => v.status === 'rejected');
  const abandoned = validations.filter(v => v.status === 'abandoned');

  return {
    total: validations.length,
    completed: completed.length,
    approved: approved.length,
    rejected: rejected.length,
    abandoned: abandoned.length,
    successRate: completed.length > 0
      ? (approved.length / completed.length * 100).toFixed(2) + '%'
      : 'N/A',
    abandonmentRate: validations.length > 0
      ? (abandoned.length / validations.length * 100).toFixed(2) + '%'
      : 'N/A',
  };
}

3. Encontrar Validaciones Fallidas para Soporte

Ayudar a usuarios que tuvieron problemas de verificación:

async function findFailedValidations(entityId) {
  const response = await fetch(
    `https://api.gu1.ai/api/kyc/entities/${entityId}/validations?status=rejected`,
    {
      headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
    }
  );

  const result = await response.json();

  // Extraer razones de fallo
  const failures = result.validations.map(v => ({
    validationId: v.id,
    rejectedAt: v.updatedAt,
    reason: v.metadata?.rejectionReason || 'No especificado',
    warnings: v.warnings || [],
    decision: v.decision,
  }));

  return failures;
}

4. Exportar Historial de Validación

Exportar historial completo de validación para reportes:

async function exportValidationHistory(entityId) {
  const validations = await getAllValidations(entityId); // Del ejemplo de paginación

  // Convertir a formato CSV
  const csv = [
    'ID Validación,Estado,Proveedor,Creado,Verificado,Es Actual',
    ...validations.map(v =>
      `${v.id},${v.status},${v.provider},${v.createdAt},${v.verifiedAt || ''},${v.isCurrent}`
    )
  ].join('\n');

  return csv;
}

Notas Importantes

Paginación por Defecto

Por defecto, este endpoint retorna hasta 100 validaciones por página. Si una entidad tiene más de 100 validaciones, necesitarás usar paginación para recuperar todos los registros.

Ordenamiento

Las validaciones se retornan en orden descendente por fecha de creación (más reciente primero). La validación actual normalmente aparecerá primero en la lista.

Bandera isCurrent

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 isCurrent: false.

Retención de Datos Históricos

Todas las validaciones se retienen indefinidamente para propósitos de auditoría y cumplimiento. Las validaciones históricas nunca se eliminan, incluso si están abandonadas o expiradas.

Consideraciones de Rendimiento

Para entidades con muchas validaciones (>100), considera usar paginación y filtros de estado para reducir el tamaño de respuesta y mejorar el rendimiento.

Diferencias con Endpoints Similares

Endpoint	Propósito	Caso de Uso
`GET /api/kyc/entities/:entityId/validations`	Obtener todas las validaciones de una entidad	Pista de auditoría, historial, analíticas
`GET /api/kyc/entities/:entityId/current`	Obtener solo la validación actual	Verificar si el usuario está verificado ahora
`GET /api/kyc/validations/:id`	Obtener validación específica por ID	Recuperar detalles de una validación conocida
`GET /api/kyc/validations`	Listar todas las validaciones de todas las entidades	Analíticas a nivel de organización

Próximos Pasos

Obtener Validación Actual

Obtener solo la validación activa de una entidad

Crear Validación KYC

Iniciar una nueva sesión de verificación

Verificar Estado de Entidad

Obtener resumen del estado de verificación

Sincronizar Validación

Refrescar datos de validación manualmente

​Descripción General

​Cuándo Usar Esto

​Solicitud

​Endpoint

​Parámetros de Ruta

​Parámetros de Query

​Encabezados

​Respuesta

​Respuesta Exitosa (200 OK)

​Campos de Respuesta

​Ejemplos de Solicitudes

​Obtener Todas las Validaciones de una Entidad

​Filtrar por Estado

​Obtener Solo la Validación Actual

​Ejemplo de Paginación

​Respuestas de Error

​Entidad No Encontrada (404)

​Parámetros de Query Inválidos (400)

​No Autorizado (401)

​Casos de Uso

​1. Pista de Auditoría para Cumplimiento

​2. Calcular Tasa de Éxito

​3. Encontrar Validaciones Fallidas para Soporte

​4. Exportar Historial de Validación

​Notas Importantes

​Diferencias con Endpoints Similares

​Próximos Pasos

Obtener Validación Actual

Crear Validación KYC

Verificar Estado de Entidad

Sincronizar Validación

Descripción General

Cuándo Usar Esto

Solicitud

Endpoint

Parámetros de Ruta

Parámetros de Query

Encabezados

Respuesta

Respuesta Exitosa (200 OK)

Campos de Respuesta

Ejemplos de Solicitudes

Obtener Todas las Validaciones de una Entidad

Filtrar por Estado

Obtener Solo la Validación Actual

Ejemplo de Paginación

Respuestas de Error

Entidad No Encontrada (404)

Parámetros de Query Inválidos (400)

No Autorizado (401)

Casos de Uso

1. Pista de Auditoría para Cumplimiento

2. Calcular Tasa de Éxito

3. Encontrar Validaciones Fallidas para Soporte

4. Exportar Historial de Validación

Notas Importantes

Diferencias con Endpoints Similares

Próximos Pasos