Skip to main content
DELETE
/
api
/
kyc
/
validations
/
{id}
/
cancel
Cancelar Validação KYC
curl --request DELETE \
  --url http://api.gu1.ai/api/kyc/validations/{id}/cancel \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "reason": "<string>"
}
'

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

​
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

​
id
string
required
O ID da validação a ser cancelada

​
Headers

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

​
Parâmetros do Body

​
reason
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"

​
Resposta

​
Resposta de Sucesso (200 OK)

Retorna o objeto de validação atualizado com status cancelled: 
{
  "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

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);

​
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 cancelada se o status for pending, in_progress ou in_review: 
{
  "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: 
{
  "error": "VALIDATION_ERROR",
  "message": "Reason must be at least 5 characters"
}

​
Notas Importantes

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

​
Próximos Passos

Criar Validação KYC

Iniciar uma nova sessão de verificação

Consultar Status de Verificação

Consultar resultados de validação