Skip to main content
POST
/
api
/
kyc
/
validations
/
{id}
/
approve
Aprovar Validação 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>"
}
'

​
Visão Geral

Este endpoint permite aprovar manualmente uma validação KYC. Quando você aprova:
  • Sincronização automática com o provedor: O sistema primeiro sincroniza com o provedor KYC para obter o status mais recente
  • Validação de status: Você só pode aprovar se o status do provedor for in_review (o usuário completou a verificação e requer revisão manual da equipe de compliance)
  • O status da validação muda para approved
  • A validação é marcada como verificada com timestamp
  • O motivo da aprovação é salvo em metadata e logs de auditoria
  • Com doubleCheckRenaper: RENAPER não é reexecutado nem o enforce do cruzamento é reaplicado; a API reutiliza metadata.responseDoubleChecks.renaper e warnings já calculados em in_review. A decisão é humana após revisar esses dados na UI.
A aprovação manual só deve ser usada quando você realizou verificação adicional ou tem razões suficientes para anular o processo automatizado. O motivo da aprovação é obrigatório para conformidade de auditoria.

​
Quando Usar Isto

  • Verificação adicional concluída: Você realizou revisão manual de documentos ou dados biométricos
  • Exceção de negócio: Você tem razões comerciais para aprovar apesar de problemas menores
  • Anulação de avaliação de risco: Sua equipe de risco aprovou a validação
  • Atraso do provedor: O provedor de verificação está demorando muito, mas sua revisão interna está completa

​
Request

​
Endpoint

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

​
Parâmetros de Rota

​
id
string
required
O ID de validação a aprovar

​
Headers

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

​
Parâmetros do Body

​
reason
string
required
Motivo para aprovar manualmente a validação (mínimo 5 caracteres)Tipo: string (comprimento mínimo: 5)Exemplo: "Revisão manual concluída com sucesso - todos os documentos verificados"

​
Resposta

​
Resposta de Sucesso (200 OK)

Retorna o objeto de validação atualizado com status 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": "Revisão manual concluída com sucesso - todos os documentos verificados"
  },
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-01-27T10:30:00Z"
}

​
Exemplo 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: 'Revisão manual concluída com sucesso - todos os documentos verificados'
    })
  }
);

const approved = await response.json();
console.log('Validação aprovada:', approved.status);

​
Respostas de Erro

​
Validação Não Encontrada (404)

{
  "error": "NOT_FOUND",
  "message": "Validation not found"
}

​
Status Inválido (400)

A validação só pode ser aprovada se o status do provedor for in_review (o usuário completou a verificação e requer revisão manual da equipe 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)."
}
O que isso significa?
  • Se o provedor já aprovou (approved) ou rejeitou (rejected) a validação, você não pode anular essa decisão
  • Se a validação está cancelled, você não pode aprová-la
  • Se está expired ou abandoned, também não pode ser aprovada manualmente
  • Se está in_progress, o usuário ainda está preenchendo o formulário de verificação
  • Você só pode aprovar quando o provedor reporta que a validação está in_review (o usuário completou todos os passos de verificação e requer revisão manual da equipe de compliance)

​
Motivo Inválido (400)

O motivo deve ter pelo menos 5 caracteres: 
{
  "error": "VALIDATION_ERROR",
  "message": "Reason must be at least 5 characters"
}

​
Notas Importantes

Antes de aprovar, o sistema sincroniza automaticamente com o provedor KYC para obter os dados de verificação mais recentes. Isso garante que você tome decisões baseadas na informação mais atualizada.
Você não pode aprovar validações que já estão approved, rejected ou cancelled. Esses status são protegidos para manter a integridade dos dados.
O motivo da aprovação é salvo tanto nos metadata da validação quanto nos logs de auditoria. Isso é crítico para conformidade e requisitos regulatórios.
A aprovação manual só é permitida quando o provedor reporta a validação como in_review (em revisão). Isso previne aprovar validações que:
  • O provedor já rejeitou ou completou
  • Ainda não têm dados de verificação completos (status pending ou in_progress)
  • O usuário ainda está preenchendo o formulário (status in_progress)
Quando aprovada, a validação recebe um timestamp verifiedAt e se torna a validação atual para a entidade.

​
Melhores Práticas

  • Sempre forneça motivos detalhados: Inclua detalhes específicos sobre por que a aprovação manual é necessária
  • Documente seu processo: Mantenha documentação interna para os critérios de aprovação manual
  • Revise dados frescos: A sincronização automática garante que você veja os documentos e resultados biométricos mais recentes
  • Use com moderação: A aprovação manual deve ser a exceção, não a regra
  • Treine sua equipe: Garanta que a equipe entenda quando a aprovação manual é apropriada

​
Próximos Passos

Rejeitar Validação

Rejeitar manualmente uma validação

Consultar Status de Verificação

Consultar resultados de validação