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

​
Descripción General

Este endpoint permite aprobar manualmente una validación KYC. Cuando apruebas:
  • 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 aprobar 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 approved
  • La validación se marca como verificada con timestamp
  • La razón de aprobación se guarda en metadata y logs de auditoría
  • Con doubleCheckRenaper: no se vuelve a ejecutar RENAPER ni se re-aplica el cruce; se reutilizan metadata.responseDoubleChecks.renaper y warnings ya calculados en in_review. La decisión es humana tras revisar esos datos en la UI.
La aprobación manual solo debe usarse cuando has realizado verificación adicional o tienes razones suficientes para anular el proceso automatizado. La razón de aprobación es obligatoria para cumplimiento de auditoría.

​
Cuándo Usar Esto

  • Verificación adicional completada: Has realizado revisión manual de documentos o datos biométricos
  • Excepción de negocio: Tienes razones comerciales para aprobar a pesar de problemas menores
  • Anulación de evaluación de riesgo: Tu equipo de riesgo ha aprobado la validación
  • Retraso del proveedor: El proveedor de verificación está tardando demasiado pero tu revisión interna está completa

​
Request

​
Endpoint

POST https://api.gu1.ai/api/kyc/validations/{id}/approve

​
Parámetros de Ruta

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

​
Headers

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

​
Parámetros del Body

​
reason
string
required
Razón para aprobar manualmente la validación (mínimo 5 caracteres)Tipo: string (longitud mínima: 5)Ejemplo: "Revisión manual completada exitosamente - todos los documentos verificados"

​
Respuesta

​
Respuesta Exitosa (200 OK)

Devuelve el objeto de validación actualizado con estado approved: 
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "entityId": "123e4567-e89b-12d3-a456-426614174000",
  "organizationId": "org_abc123",
  "validationSessionId": "session_xyz789",
  "status": "approved",
  "provider": "kyc_provider",
  "providerSessionUrl": "https://verify.example.com/session_xyz789",
  "isCurrent": true,
  "verifiedAt": "2025-01-27T10:30:00Z",
  "metadata": {
    "manuallyApprovedBy": "user_123",
    "manuallyApprovedAt": "2025-01-27T10:30:00Z",
    "approvalReason": "Revisión manual completada exitosamente - todos los documentos verificados"
  },
  "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}/approve`,
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      reason: 'Revisión manual completada exitosamente - todos los documentos verificados'
    })
  }
);

const approved = await response.json();
console.log('Validación aprobada:', approved.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 aprobarse 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 approve. Current status is \"approved\". Manual approval 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 aprobarla
  • Si está expired o abandoned, tampoco se puede aprobar manualmente
  • Si está in_progress, el usuario aún está llenando el formulario de verificación
  • Solo puedes aprobar 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 aprobar, 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 aprobar 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 aprobación 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.
La aprobación manual solo está permitida cuando el proveedor reporta la validación como in_review (en revisión). Esto previene aprobar validaciones que:
  • El proveedor ya ha rechazado 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 aprueba, la validación recibe un timestamp verifiedAt y se convierte en la validación actual para la entidad.

​
Mejores Prácticas

  • Siempre proporciona razones detalladas: Incluye detalles específicos sobre por qué la aprobación manual es necesaria
  • Documenta tu proceso: Mantén documentación interna para los criterios de aprobación manual
  • Revisa datos frescos: La sincronización automática asegura que veas los documentos y resultados biométricos más recientes
  • Usa con moderación: La aprobación manual debe ser la excepción, no la regla
  • Capacita a tu equipo: Asegúrate de que el personal entienda cuándo la aprobación manual es apropiada

​
Próximos Pasos

Rechazar Validación

Rechazar manualmente una validación

Consultar Estado de Verificación

Consultar resultados de validación