> ## 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.
# Rechazar Validación KYC
> Rechazar manualmente una validación KYC — en la API KYC de gu1 para flujos de verificación de identidad, con ejemplos para reject validation.
## Descripción General
Este endpoint permite rechazar manualmente una validación KYC. Cuando rechazas:
* **Sincronización automática con el proveedor**: El sistema primero sincroniza con el proveedor KYC para obtener el estado más reciente
* **Validación de estado**: Solo puedes rechazar si el estado del proveedor es `in_review` (el usuario completó la verificación y requiere revisión manual del equipo de compliance)
* El estado de la validación cambia a `rejected`
* La validación se marca como no actual (`isCurrent: false`)
* La razón de rechazo se guarda en metadata y logs de auditoría
El rechazo manual solo debe usarse cuando has identificado riesgo de fraude, violaciones de política u otras razones legítimas para denegar la verificación. La razón de rechazo es obligatoria para cumplimiento de auditoría.
## Cuándo Usar Esto
* **Documentos fraudulentos detectados**: Los documentos parecen falsos, alterados o robados
* **Datos inconsistentes**: La información no coincide entre diferentes fuentes
* **Alto riesgo detectado**: La evaluación interna de riesgo señala preocupaciones
* **Violación de políticas**: El usuario no cumple con tus requisitos de verificación
* **Coincidencia con lista de sanciones**: El usuario aparece en listas de vigilancia o sanciones
## Request
### Endpoint
```
POST https://api.gu1.ai/api/kyc/validations/{id}/reject
```
### Parámetros de Ruta
El ID de validación a rechazar
### Headers
```json theme={null}
{
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json"
}
```
### Parámetros del Body
Razón para rechazar manualmente la validación (mínimo 5 caracteres)
**Tipo**: `string` (longitud mínima: 5)
**Ejemplo**: `"Fallo en la verificación de autenticidad del documento - sospecha de fraude"`
## Respuesta
### Respuesta Exitosa (200 OK)
Devuelve el objeto de validación actualizado con estado `rejected`:
```json theme={null}
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"entityId": "123e4567-e89b-12d3-a456-426614174000",
"organizationId": "org_abc123",
"validationSessionId": "session_xyz789",
"status": "rejected",
"provider": "kyc_provider",
"providerSessionUrl": "https://verify.example.com/session_xyz789",
"isCurrent": false,
"metadata": {
"manuallyRejectedBy": "user_123",
"manuallyRejectedAt": "2025-01-27T10:30:00Z",
"rejectionReason": "Fallo en la verificación de autenticidad del documento - sospecha de fraude"
},
"createdAt": "2025-01-15T10:30:00Z",
"updatedAt": "2025-01-27T10:30:00Z"
}
```
## Ejemplo de Request
```javascript Node.js theme={null}
const validationId = '550e8400-e29b-41d4-a716-446655440000';
const response = await fetch(
`https://api.gu1.ai/api/kyc/validations/${validationId}/reject`,
{
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json',
},
body: JSON.stringify({
reason: 'Fallo en la verificación de autenticidad del documento - sospecha de fraude'
})
}
);
const rejected = await response.json();
console.log('Validación rechazada:', rejected.status);
```
```python Python theme={null}
import requests
validation_id = '550e8400-e29b-41d4-a716-446655440000'
response = requests.post(
f'https://api.gu1.ai/api/kyc/validations/{validation_id}/reject',
headers={
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json',
},
json={
'reason': 'Fallo en la verificación de autenticidad del documento - sospecha de fraude'
}
)
rejected = response.json()
print('Validación rechazada:', rejected['status'])
```
```curl cURL theme={null}
curl -X POST https://api.gu1.ai/api/kyc/validations/550e8400-e29b-41d4-a716-446655440000/reject \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"reason": "Fallo en la verificación de autenticidad del documento - sospecha de fraude"
}'
```
## Respuestas de Error
### Validación No Encontrada (404)
```json theme={null}
{
"error": "NOT_FOUND",
"message": "Validation not found"
}
```
### Estado Inválido (400)
La validación solo puede rechazarse si el estado del proveedor es `in_review` (el usuario completó la verificación y requiere revisión manual del equipo de compliance):
```json theme={null}
{
"error": "INVALID_STATUS",
"message": "Cannot manually reject. Current status is \"approved\". Manual rejection is only allowed when status is \"in_review\" (validation requires manual review from compliance team)."
}
```
**¿Qué significa esto?**
* Si el proveedor ya aprobó (`approved`) o rechazó (`rejected`) la validación, no puedes anular esa decisión
* Si la validación está `cancelled`, no puedes rechazarla
* Si está `expired` o `abandoned`, tampoco se puede rechazar manualmente
* Si está `in_progress`, el usuario aún está llenando el formulario de verificación
* **Solo puedes rechazar** cuando el proveedor reporta que la validación está `in_review` (el usuario completó todos los pasos de verificación y requiere revisión manual del equipo de compliance)
### Razón Inválida (400)
La razón debe tener al menos 5 caracteres:
```json theme={null}
{
"error": "VALIDATION_ERROR",
"message": "Reason must be at least 5 characters"
}
```
## Notas Importantes
Antes de rechazar, el sistema sincroniza automáticamente con el proveedor KYC para obtener los datos de verificación más recientes. Esto asegura que tomes decisiones basadas en la información más actualizada.
No puedes rechazar validaciones que ya están `approved`, `rejected` o `cancelled`. Estos estados están protegidos para mantener la integridad de los datos.
La razón de rechazo se guarda tanto en los metadata de la validación como en los logs de auditoría. Esto es crítico para el cumplimiento y requisitos regulatorios.
El rechazo manual solo está permitido cuando el proveedor reporta la validación como `in_review` (en revisión). Esto previene rechazar validaciones que:
* El proveedor ya ha aprobado o completado
* Aún no tienen datos de verificación completos (estado `pending` o `in_progress`)
* El usuario aún está llenando el formulario (estado `in_progress`)
Cuando se rechaza, la validación NO recibe un timestamp `verifiedAt` y se marca como no actual para la entidad.
Después del rechazo, el usuario puede crear una nueva validación KYC para la misma entidad si quiere reintentar la verificación.
## Mejores Prácticas
* **Sé específico con las razones**: Documenta claramente por qué la validación fue rechazada
* **Sigue procedimientos de fraude**: Asegúrate de que el rechazo siga tus protocolos internos de prevención de fraude
* **Considera requisitos regulatorios**: Algunas jurisdicciones requieren documentación específica para rechazos
* **Revisa datos frescos**: La sincronización automática asegura que veas los documentos y resultados biométricos más recientes
* **Documenta internamente**: Mantén notas detalladas sobre indicadores de fraude o violaciones de políticas
* **Capacita a tu equipo**: Asegúrate de que el personal entienda los criterios de rechazo y cuándo escalar
## Próximos Pasos
Aprobar manualmente una validación
Consultar resultados de validación