> ## 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.
# Aprovar Validação KYC
> Aprovar manualmente uma validação KYC — na API KYC da gu1 para fluxos de verificação de identidade, com exemplos para approve validation.
## 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
O ID de validação a aprovar
### Headers
```json theme={null}
{
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json"
}
```
### Parâmetros do Body
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`:
```json theme={null}
{
"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
```javascript Node.js theme={null}
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);
```
```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}/approve',
headers={
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json',
},
json={
'reason': 'Revisão manual concluída com sucesso - todos os documentos verificados'
}
)
approved = response.json()
print('Validação aprovada:', approved['status'])
```
```curl cURL theme={null}
curl -X POST https://api.gu1.ai/api/kyc/validations/550e8400-e29b-41d4-a716-446655440000/approve \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"reason": "Revisão manual concluída com sucesso - todos os documentos verificados"
}'
```
## 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 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):
```json theme={null}
{
"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:
```json theme={null}
{
"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 manualmente uma validação
Consultar resultados de validação