Skip to main content
POST
/
api
/
kyc
/
validations
/
{id}
/
reject
Rechazar Validación KYC
curl --request POST \
  --url http://api.gu1.ai/api/kyc/validations/{id}/reject \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "reason": "<string>"
}
'

​
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

​
id
string
required
El ID de validación a rechazar

​
Headers

{
  "Authorization": "Bearer YOUR_API_KEY",
  "Content-Type": "application/json"
}

​
Parámetros del Body

​
reason
string
required
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: 
{
  "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

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);

​
Respuestas de Error

​
Validación No Encontrada (404)

{
  "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): 
{
  "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: 
{
  "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 Validación

Aprobar manualmente una validación

Consultar Estado de Verificación

Consultar resultados de validación