> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gu1.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Listar Validaciones KYC de una Entidad

> Recupera todo el historial de validaciones KYC de una entidad específica — en la API KYC de gu1 para flujos de verificación de identidad.

## 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

<ParamField path="entityId" type="string" required>
  El UUID de la entidad para recuperar validaciones
</ParamField>

### Parámetros de Query

<ParamField query="page" type="integer" default="1">
  Número de página para paginación (comienza en 1)
</ParamField>

<ParamField query="limit" type="integer" default="100">
  Número de validaciones por página (máx 100)
</ParamField>

<ParamField query="status" type="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
</ParamField>

<ParamField query="isCurrent" type="boolean">
  Filtrar para mostrar solo la validación activa actual (`true`) o validaciones históricas (`false`)
</ParamField>

### Encabezados

```json theme={null}
{
  "Authorization": "Bearer YOUR_API_KEY"
}
```

## Respuesta

### Respuesta Exitosa (200 OK)

Retorna una lista paginada de validaciones:

```json theme={null}
{
  "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

<ResponseField name="validations" type="array">
  Array de objetos de validación
</ResponseField>

<ResponseField name="total" type="integer">
  Número total de validaciones que coinciden con la consulta
</ResponseField>

<ResponseField name="page" type="integer">
  Número de página actual
</ResponseField>

<ResponseField name="limit" type="integer">
  Número de validaciones por página
</ResponseField>

## Ejemplos de Solicitudes

### Obtener Todas las Validaciones de una Entidad

<CodeGroup>
  ```javascript Node.js theme={null}
  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'})`);
  });
  ```

  ```python Python theme={null}
  import requests

  entity_id = '123e4567-e89b-12d3-a456-426614174000'

  response = requests.get(
      f'https://api.gu1.ai/api/kyc/entities/{entity_id}/validations',
      headers={
          'Authorization': 'Bearer YOUR_API_KEY',
      }
  )

  result = response.json()
  print(f"Se encontraron {result['total']} validaciones")
  print(f"Página actual: {result['page']} de {result['total'] // result['limit'] + 1}")

  for validation in result['validations']:
      current_status = 'actual' if validation['isCurrent'] else 'histórica'
      print(f"{validation['id']}: {validation['status']} ({current_status})")
  ```

  ```curl cURL theme={null}
  curl -X GET "https://api.gu1.ai/api/kyc/entities/123e4567-e89b-12d3-a456-426614174000/validations" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```
</CodeGroup>

***

### Filtrar por Estado

Obtener solo validaciones aprobadas:

<CodeGroup>
  ```javascript Node.js theme={null}
  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`);
  ```

  ```python Python theme={null}
  import requests

  entity_id = '123e4567-e89b-12d3-a456-426614174000'

  response = requests.get(
      f'https://api.gu1.ai/api/kyc/entities/{entity_id}/validations',
      headers={'Authorization': 'Bearer YOUR_API_KEY'},
      params={'status': 'approved'}
  )

  result = response.json()
  print(f"Se encontraron {result['total']} validaciones aprobadas")
  ```

  ```curl cURL theme={null}
  curl -X GET "https://api.gu1.ai/api/kyc/entities/123e4567-e89b-12d3-a456-426614174000/validations?status=approved" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```
</CodeGroup>

***

### Obtener Solo la Validación Actual

<CodeGroup>
  ```javascript Node.js theme={null}
  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');
  }
  ```

  ```python Python theme={null}
  import requests

  entity_id = '123e4567-e89b-12d3-a456-426614174000'

  response = requests.get(
      f'https://api.gu1.ai/api/kyc/entities/{entity_id}/validations',
      headers={'Authorization': 'Bearer YOUR_API_KEY'},
      params={'isCurrent': 'true'}
  )

  result = response.json()

  if result['validations']:
      current_validation = result['validations'][0]
      print(f"Estado de validación actual: {current_validation['status']}")
  else:
      print('No se encontró validación actual')
  ```

  ```curl cURL theme={null}
  curl -X GET "https://api.gu1.ai/api/kyc/entities/123e4567-e89b-12d3-a456-426614174000/validations?isCurrent=true" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```
</CodeGroup>

***

### Ejemplo de Paginación

<CodeGroup>
  ```javascript Node.js theme={null}
  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}`);
  ```

  ```python Python theme={null}
  import requests

  def get_all_validations(entity_id, api_key):
      page = 1
      limit = 50
      all_validations = []

      while True:
          response = requests.get(
              f'https://api.gu1.ai/api/kyc/entities/{entity_id}/validations',
              headers={'Authorization': f'Bearer {api_key}'},
              params={'page': page, 'limit': limit}
          )

          result = response.json()
          all_validations.extend(result['validations'])

          print(f"Página {page} obtenida: {len(result['validations'])} validaciones")

          # Verificar si hemos obtenido todas las validaciones
          if len(all_validations) >= result['total']:
              break

          page += 1

      return all_validations

  entity_id = '123e4567-e89b-12d3-a456-426614174000'
  validations = get_all_validations(entity_id, 'YOUR_API_KEY')
  print(f"Total de validaciones obtenidas: {len(validations)}")
  ```
</CodeGroup>

## Respuestas de Error

### Entidad No Encontrada (404)

```json theme={null}
{
  "error": "NOT_FOUND",
  "message": "Entity not found"
}
```

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

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

### No Autorizado (401)

```json theme={null}
{
  "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:

```javascript theme={null}
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:

```javascript theme={null}
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:

```javascript theme={null}
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:

```javascript theme={null}
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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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`.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## 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

<CardGroup cols={2}>
  <Card title="Obtener Validación Actual" icon="check-circle" href="/es/use-cases/kyc/current-validation">
    Obtener solo la validación activa de una entidad
  </Card>

  <Card title="Crear Validación KYC" icon="play" href="/es/use-cases/kyc/create-validation">
    Iniciar una nueva sesión de verificación
  </Card>

  <Card title="Verificar Estado de Entidad" icon="shield-check" href="/es/use-cases/kyc/check-status">
    Obtener resumen del estado de verificación
  </Card>

  <Card title="Sincronizar Validación" icon="arrows-rotate" href="/es/use-cases/kyc/sync-validation">
    Refrescar datos de validación manualmente
  </Card>
</CardGroup>