Skip to main content
POST
http://api.gu1.ai
/
api
/
kyc
/
validations
/
{id}
/
reject
Rejeitar Validação 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>"
}
'

​
Visão Geral

Este endpoint permite rejeitar manualmente uma validação KYC. Quando você rejeita:
  • 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 rejeitar 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 rejected
  • A validação é marcada como não atual (isCurrent: false)
  • O motivo da rejeição é salvo em metadata e logs de auditoria
A rejeição manual só deve ser usada quando você identificou risco de fraude, violações de política ou outras razões legítimas para negar a verificação. O motivo da rejeição é obrigatório para conformidade de auditoria.

​
Quando Usar Isto

  • Documentos fraudulentos detectados: Os documentos parecem falsos, alterados ou roubados
  • Dados inconsistentes: A informação não coincide entre diferentes fontes
  • Alto risco detectado: A avaliação interna de risco sinaliza preocupações
  • Violação de políticas: O usuário não atende aos seus requisitos de verificação
  • Coincidência com lista de sanções: O usuário aparece em listas de vigilância ou sanções

​
Request

​
Endpoint

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

​
Parâmetros de Rota

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

​
Headers

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

​
Parâmetros do Body

​
reason
string
required
Motivo para rejeitar manualmente a validação (mínimo 5 caracteres)Tipo: string (comprimento mínimo: 5)Exemplo: "Falha na verificação de autenticidade do documento - suspeita de fraude"

​
Resposta

​
Resposta de Sucesso (200 OK)

Retorna o objeto de validação atualizado com status 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": "Falha na verificação de autenticidade do documento - suspeita de fraude"
  },
  "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}/reject`,
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      reason: 'Falha na verificação de autenticidade do documento - suspeita de fraude'
    })
  }
);

const rejected = await response.json();
console.log('Validação rejeitada:', rejected.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 rejeitada 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 reject. Current status is \"approved\". Manual rejection 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 rejeitá-la
  • Se está expired ou abandoned, também não pode ser rejeitada manualmente
  • Se está in_progress, o usuário ainda está preenchendo o formulário de verificação
  • Você só pode rejeitar 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 rejeitar, 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 rejeitar validações que já estão approved, rejected ou cancelled. Esses status são protegidos para manter a integridade dos dados.
O motivo da rejeição é salvo tanto nos metadata da validação quanto nos logs de auditoria. Isso é crítico para conformidade e requisitos regulatórios.
A rejeição manual só é permitida quando o provedor reporta a validação como in_review (em revisão). Isso previne rejeitar validações que:
  • O provedor já aprovou 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 rejeitada, a validação NÃO recebe um timestamp verifiedAt e é marcada como não atual para a entidade.
Após a rejeição, o usuário pode criar uma nova validação KYC para a mesma entidade se quiser tentar novamente a verificação.

​
Melhores Práticas

  • Seja específico com os motivos: Documente claramente por que a validação foi rejeitada
  • Siga procedimentos de fraude: Garanta que a rejeição siga seus protocolos internos de prevenção de fraude
  • Considere requisitos regulatórios: Algumas jurisdições exigem documentação específica para rejeições
  • Revise dados frescos: A sincronização automática garante que você veja os documentos e resultados biométricos mais recentes
  • Documente internamente: Mantenha notas detalhadas sobre indicadores de fraude ou violações de políticas
  • Treine sua equipe: Garanta que a equipe entenda os critérios de rejeição e quando escalar

​
Próximos Passos

Aprovar Validação

Aprovar manualmente uma validação

Consultar Status de Verificação

Consultar resultados de validação