Clientes - Exclusão

#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

• 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, os dados pessoais do cliente são apagados (veja abaixo o que sai e o que fica), e o ID não poderá ser utilizado novamente para consultas ou atualizações.

#O que a exclusão apaga

Numa única operação, irreversível:

• Cadastro: nome, e-mail, documento, telefone, nascimento, gênero, e-mails adicionais, referência externa e metadata.
• Endereços do cliente.
• Sessões de checkout do cliente (as que ele pagou e os carrinhos que abandonou, achados pelo cliente vinculado à sessão ou pelo e-mail/documento que ele digitou — este, só nas sessões sem cliente vinculado e sem pagamento em andamento: a sessão de outro cliente com o mesmo e-mail não é tocada; inclusive as vendas de marketplace feitas em nome da sua conta): os dados do comprador (customer, address, campos personalizados) e do navegador (IP, aparelho, cookies de atribuição). O pedido (itens, totais, cupons) continua.
• Links do portal do cliente: todos os que estavam válidos deixam de abrir.
• Pagamentos combinados (2 cartões ou cartão + Pix): a base de cobrança guardada para cobrar as partes (documento da compra, documento do destinatário do frete, IP e navegador). As transações das partes ficam, como qualquer transação. Um pedido combinado ainda em andamento deixa de cobrar a próxima parte e é desfeito.
• Conta na área de membros desta loja, se o cliente tiver uma (o mesmo apagamento de quando o aluno apaga a própria conta): o e-mail de acesso, as sessões e os links de entrada, o texto de comentários e avaliações, as anotações e o progresso. A matrícula fica, anônima (o registro da venda), e o certificado emitido fica, sem o nome.
• Mensagens do SmartOps (e-mail, SMS e WhatsApp) desta loja: das mensagens enviadas para o e-mail e o telefone do cliente (e das que foram para um contato antigo dele) saem o contato e o texto — fica só o registro de que a mensagem foi enviada (evento, status e datas), sem nada que identifique o cliente. Saem também os avisos ao seu sistema sobre elas, a fila do SMS (o número e o texto) e a janela de conversa do WhatsApp. O descadastro continua valendo, para o cliente não voltar a receber mensagens, sem guardar o e-mail ou o telefone dele. Num cliente de sandbox, só as mensagens de teste são alcançadas.

O que fica: o histórico financeiro (transações e assinaturas guardam a cópia dos dados do comprador do momento da cobrança, por obrigação fiscal) e os eventos de webhook já emitidos, até o prazo de retenção deles.

#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