> ## 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.
# Rejeitar Validação KYC
> Rejeitar manualmente uma validação KYC — na API KYC da gu1 para fluxos de verificação de identidade, com exemplos para reject validation.
## 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
O ID de validação a rejeitar
### Headers
```json theme={null}
{
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json"
}
```
### Parâmetros do Body
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`:
```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": "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
```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: 'Falha na verificação de autenticidade do documento - suspeita de fraude'
})
}
);
const rejected = await response.json();
console.log('Validação rejeitada:', 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': 'Falha na verificação de autenticidade do documento - suspeita de fraude'
}
)
rejected = response.json()
print('Validação rejeitada:', 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": "Falha na verificação de autenticidade do documento - suspeita de fraude"
}'
```
## Respostas de Erro
### Validação Não Encontrada (404)
```json theme={null}
{
"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):
```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)."
}
```
**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:
```json theme={null}
{
"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 manualmente uma validação
Consultar resultados de validação