> ## 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.

# Cancelar Validação KYC

> Cancelar uma validação KYC pendente, em andamento ou em revisão — na API KYC da gu1 para fluxos de verificação de identidade, com exemplos para cancel.

## Resumo

Este endpoint permite cancelar uma validação KYC que está em status `pending`, `in_progress` ou `in_review`. Quando cancelada:

* O status da validação muda para `cancelled`
* A sessão do provedor é encerrada (o usuário não pode mais acessar a URL de verificação)
* A validação é marcada como não atual (`isCurrent: false`)
* Você pode criar uma nova validação para a mesma entidade depois

<Warning>
  Esta ação não pode ser desfeita. O usuário precisará iniciar um novo processo de validação se ainda precisar verificar sua identidade.
</Warning>

## Quando Usar Isto

* **Cancelamento solicitado pelo usuário**: O cliente não quer mais completar a verificação
* **Dados incorretos**: As informações da entidade foram inseridas incorretamente
* **Validação duplicada**: A validação foi criada por engano
* **Necessidade de reiniciar o processo**: Precisa começar do zero com uma nova sessão de verificação

## Requisição

### Endpoint

```
DELETE https://api.gu1.ai/api/kyc/validations/{id}/cancel
```

### Parâmetros de Rota

<ParamField path="id" type="string" required>
  O ID da validação a ser cancelada
</ParamField>

### Headers

```json theme={null}
{
  "Authorization": "Bearer YOUR_API_KEY",
  "Content-Type": "application/json"
}
```

### Parâmetros do Body

<ParamField body="reason" type="string" required>
  Motivo para cancelar a validação (mínimo 5 caracteres)

  **Tipo**: `string` (comprimento mínimo: 5)

  **Exemplo**: `"Usuário solicitou cancelar o processo de verificação"`
</ParamField>

## Resposta

### Resposta de Sucesso (200 OK)

Retorna o objeto de validação atualizado com status `cancelled`:

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "entityId": "123e4567-e89b-12d3-a456-426614174000",
  "organizationId": "org_abc123",
  "validationSessionId": "session_xyz789",
  "status": "cancelled",
  "provider": "kyc_provider",
  "providerSessionUrl": "https://verify.example.com/session_xyz789",
  "isCurrent": false,
  "metadata": {
    "cancelledBy": "user_123",
    "cancelledAt": "2025-01-27T10:30:00Z",
    "cancellationReason": "Usuário solicitou cancelar o processo de verificação"
  },
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-01-27T10:30:00Z"
}
```

## Exemplo de Requisição

<CodeGroup>
  ```javascript Node.js theme={null}
  const validationId = '550e8400-e29b-41d4-a716-446655440000';

  const response = await fetch(
    `https://api.gu1.ai/api/kyc/validations/${validationId}/cancel`,
    {
      method: 'DELETE',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        reason: 'Usuário solicitou cancelar o processo de verificação'
      })
    }
  );

  const cancelled = await response.json();
  console.log('Validação cancelada:', cancelled.status);
  ```

  ```python Python theme={null}
  import requests

  validation_id = '550e8400-e29b-41d4-a716-446655440000'

  response = requests.delete(
      f'https://api.gu1.ai/api/kyc/validations/{validation_id}/cancel',
      headers={
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json',
      },
      json={
          'reason': 'Usuário solicitou cancelar o processo de verificação'
      }
  )

  cancelled = response.json()
  print('Validação cancelada:', cancelled['status'])
  ```

  ```curl cURL theme={null}
  curl -X DELETE https://api.gu1.ai/api/kyc/validations/550e8400-e29b-41d4-a716-446655440000/cancel \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "reason": "Usuário solicitou cancelar o processo de verificação"
    }'
  ```
</CodeGroup>

## 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 cancelada se o status for `pending`, `in_progress` ou `in_review`:

```json theme={null}
{
  "error": "INVALID_STATUS",
  "message": "Cannot cancel validation with status 'approved'. Only 'pending', 'in_progress', or 'in_review' validations can be cancelled."
}
```

### 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

<AccordionGroup>
  <Accordion title="A Sessão é Excluída do Provedor">
    Quando você cancela uma validação, tentamos excluir a sessão do provedor de KYC. A URL de verificação não funcionará mais para o usuário.
  </Accordion>

  <Accordion title="Registro de Auditoria">
    O motivo do cancelamento é salvo nos metadados da validação e nos registros de auditoria. Isso ajuda a manter a conformidade e rastrear por que as validações foram canceladas.
  </Accordion>

  <Accordion title="Não É Possível Cancelar Validações Concluídas">
    Você não pode cancelar validações que já estão `approved`, `rejected`, `expired`, `abandoned` ou `cancelled`. Apenas validações `pending`, `in_progress` ou `in_review` podem ser canceladas.
  </Accordion>

  <Accordion title="Criar Nova Validação Após o Cancelamento">
    Após cancelar, você pode criar uma nova validação KYC para a mesma entidade. A validação anterior permanecerá no histórico com status `cancelled`.
  </Accordion>
</AccordionGroup>

## Próximos Passos

<CardGroup cols={2}>
  <Card title="Criar Validação KYC" icon="play" href="/pt/use-cases/kyc/create-validation">
    Iniciar uma nova sessão de verificação
  </Card>

  <Card title="Consultar Status de Verificação" icon="magnifying-glass" href="/pt/use-cases/kyc/check-status">
    Consultar resultados de validação
  </Card>
</CardGroup>