Excluir um cliente

Visão Geral

Este endpoint permite excluir permanentemente um cliente do sistema através de seu identificador único. Ele é especialmente útil para remover registros de clientes inativos, atender a solicitações de direito ao esquecimento (LGPD/GDPR), ou corrigir registros duplicados no sistema.

Precauções

ATENÇÃO! Por favor, leia estas informações importantes antes de usar este endpoint.

• Operação Irreversível: A exclusão de um cliente é uma operação permanente e não pode ser desfeita.
• Dependências: Antes de excluir um cliente, verifique se ele não possui transações ativas ou outros recursos vinculados.
• Conformidade Legal: Avaliar as implicações legais de remover os dados do cliente, especialmente em relação a registros fiscais.

Descrição

O endpoint Excluir Cliente permite remover permanentemente um cliente específico a partir de seu ID único. Após a exclusão, todas as informações associadas ao cliente serão removidas, e o ID não poderá ser utilizado novamente para consultas ou atualizações.

Requisição

DELETE /v1/customers/{customerId}

Parâmetros de Caminho (Path)

Resposta - 200 OK

Se a requisição for bem-sucedida, o servidor retornará um código de status HTTP 200 OK com uma confirmação da exclusão.

Exemplo de Resposta

{
  "id": "cus_01hqzvabc",
  "resource": "customer",
  "deleted": true,
  "merchant": {
    "name": "Seller Name",
    "merchantId": "bus_1234567890",
    "isSubAccount": false
  },
  "_links": {
    "self": {
      "href": "https://api.selectwin.io/v1/customers/cus_01hqzvabc",
      "method": "GET",
      "description": "Read a customer."
    },
    "create": {
      "href": "https://api.selectwin.io/v1/customers",
      "method": "POST",
      "description": "Create a new customer."
    },
    "update": {
      "href": "https://api.selectwin.io/v1/customers/cus_01hqzvabc",
      "method": "PUT",
      "description": "Update the customer."
    },
    "delete": {
      "href": "https://api.selectwin.io/v1/customers/cus_01hqzvabc",
      "method": "DELETE",
      "description": "Delete the customer."
    },
    "list": {
      "href": "https://api.selectwin.io/v1/customers",
      "method": "GET",
      "description": "List all customers."
    }
  }
}

Atributos da Resposta

Respostas de Erro

400 Bad Request

Ocorre quando a requisição contém dados inválidos ou está mal formatada.

{
  "error": {
    "status": "Bad Request",
    "statusCode": 400,
    "category": "validation",
    "message": "Validation errors occurred.",
    "params": [
      {
        "customerId": "The format of the customer ID is invalid."
      }
    ]
  }
}

404 Not Found

Ocorre quando o customerId não existe ou não pertence à sua conta (customerNotFound).

{
  "error": {
    "status": "Not Found",
    "statusCode": 404,
    "category": "resource",
    "message": "Customer not found."
  }
}

409 Conflict

Ocorre quando o cliente possui uma assinatura ativa (não cancelada). Cancele a(s) assinatura(s) antes de excluir (customerHasActiveSubscription).

{
  "error": {
    "status": "Conflict",
    "statusCode": 409,
    "category": "conflict",
    "message": "This customer has an active subscription and cannot be deleted. Cancel the subscription first."
  }
}

Casos de Uso

1. Direito ao Esquecimento: Atender solicitações de remoção de dados conforme LGPD/GDPR
2. Limpeza de Registros: Remover clientes inativos ou duplicados do sistema
3. Correção de Erros: Eliminar registros criados incorretamente
4. Cancelamento de Conta: Processar solicitações de cancelamento de serviço

Melhores Práticas

1. Confirmar Antes de Excluir: Implemente uma confirmação adicional antes de executar a exclusão
2. Verificar Dependências: Verifique recursos vinculados ao cliente antes de solicitar a exclusão
3. Documentar Exclusões: Mantenha registros de auditoria das exclusões realizadas
4. Backup de Dados: Considere realizar backup dos dados antes de excluir clientes importantes

Integração com Outros Endpoints

• Use Consultar Cliente para verificar os dados do cliente antes da exclusão
• Use Listar Clientes para identificar clientes que podem ser removidos
• Use Listar Transações para verificar se o cliente possui transações ativas