> ## 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.
# Verificar Estado de Validación
> Consultar resultados de validación KYC y detalles de verificación — en la API KYC de gu1 para flujos de verificación de identidad, con ejemplos para check.
## 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](/es/use-cases/kyc/webhook-integration) 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
```javascript Node.js theme={null}
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);
}
```
```python Python theme={null}
validation_id = '550e8400-e29b-41d4-a716-446655440000'
response = requests.get(
f'https://api.gu1.ai/api/kyc/validations/{validation_id}',
headers={'Authorization': 'Bearer TU_API_KEY'}
)
validation = response.json()
print('Estado:', validation['status'])
print('Verificado:', validation['status'] == 'approved')
if validation['status'] == 'approved':
print('Datos verificados:', validation['extractedData'])
```
## 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
```json theme={null}
{
"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
Estado actual de validación:
* **`pending`** - Validación creada, esperando que el cliente inicie
* **`in_progress`** - Cliente 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, 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
* **`cancelled`** - Validación cancelada manualmente
## Objeto `decision`
Cuando el estado es `approved` o `rejected`, el campo `decision` contiene el resultado completo del flujo KYC. Gu1 **siempre persiste y devuelve ambas formas** por cada feature: objeto singular (legacy) **y** array de un elemento (actual). Podés leer `id_verification` o `id_verifications[0]`; se mantienen sincronizados. Lo mismo aplica a `liveness` / `liveness_checks`, `face_match` / `face_matches`, `aml_screening` / `aml_screenings` e `ip_analysis` / `ip_analyses`.
Los campos de media (`front_image`, `reference_image`, `images.*`, etc.) son **claves de almacenamiento Gu1** (`kyc/...`) tras el ingest. Obtenelas vía la [API de media de validación](/es/use-cases/kyc/validation-media). Filas antiguas pueden tener URLs HTTPS de corta duración hasta sincronizar.
Ver ejemplos completos (aprobado y rechazado) en [Eventos webhook KYC — objeto decision](/es/webhooks/events/kyc-events#objeto-decision-payloaddecision).
### Resultados por feature
Cada bloque incluye **`status`** (`Approved`, `Declined`, `In Review`, etc.), **`score`** opcional, **`warnings`** y referencias a media:
| Clave | Alias array | Campos típicos |
| ----------------- | --------------------- | -------------------------------------------------------------------------------------------------------- |
| `id_verification` | `id_verifications[0]` | `document_type`, `document_number`, `front_image`, `back_image`, `portrait_image`, `warnings`, `matches` |
| `liveness` | `liveness_checks[0]` | `score`, `method`, `reference_image`, `video_url`, `warnings`, `matches` |
| `face_match` | `face_matches[0]` | `score`, `source_image`, `target_image`, `warnings` |
| `aml_screening` | `aml_screenings[0]` | `status`, `warnings` |
| `ip_analysis` | `ip_analyses[0]` | `ip_address`, `country`, `is_vpn`, `warnings` |
Gu1 también expone campos normalizados en **`extractedData`**, **`verifiedFields`** y **`warnings`** de nivel superior (códigos de riesgo).
## Patrones de Integración Comunes
### Patrón 1: Verificar Antes de Permitir Acción
```javascript theme={null}
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
```javascript theme={null}
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](/es/use-cases/kyc/webhook-integration) 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
Iniciar nueva sesión de verificación
Obtener notificaciones en tiempo real