Excluir um cliente

Remove permanentemente um cliente da sua conta pelo ID. Use quando precisar apagar um cadastro criado por engano, eliminar duplicidades ou atender a um pedido de exclusão de dados (LGPD/GDPR). A operação é irreversível: depois de confirmada, o cliente não pode ser recuperado e o mesmo id não volta a existir.

DELETE /v1/customers/{customerId}

Como funciona

Você envia uma requisição DELETE informando o ID do cliente na URL. O servidor localiza o cliente, remove o cadastro e devolve um objeto de confirmação (não o cliente completo). Não há corpo na requisição.

Pontos importantes do mecanismo:

• Irreversível. Não há "lixeira" nem desfazer. Trate como exclusão definitiva.
• Não retorna o objeto do cliente. A resposta é um envelope curto com deleted: true, o id removido e links HATEOAS para create e list (não há mais self de leitura — o recurso deixou de existir).
• Recursos vinculados. Um cliente pode ter transações no histórico. Por regra de negócio, a exclusão de um cliente com vínculos que não podem ser desfeitos é recusada com 422 customerDeleteNotProcessable. Verifique dependências antes de excluir (veja Boas práticas).
• id opaco. Passe o id exatamente como recebido; não monte nem altere o valor. Veja Convenções.

Quando usar

• Apagar um cadastro criado por engano ou em duplicidade.
• Atender a um pedido de exclusão de dados (direito ao esquecimento).
• Limpar clientes de teste no ambiente sandbox.

Quando não usar (e alternativas):

• Apenas parar de cobrar / inativar um contato: não exclua. Prefira atualizar o cadastro com Atualizar (ex.: marcar via metadata/externalReference do seu lado).
• Manter histórico fiscal/contábil: se o cliente tem transações que precisam ser preservadas, não exclua — a operação pode ser recusada e, mesmo quando possível, você perde a referência cadastral. Mantenha o registro e apenas marque como inativo no seu sistema.

Requisição

Headers

Não há Content-Type aqui porque a requisição não tem corpo.

Parâmetros de caminho

Exemplo curl

curl -X DELETE https://api.selectwin.io/v1/customers/cus_01hqzvabc \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ"

Resposta

200 OK — objeto de confirmação. A resposta não inclui os dados do cliente; apenas confirma a exclusão.

{
  "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": "DELETE",
      "description": "Delete the customer."
    },
    "create": {
      "href": "https://api.selectwin.io/v1/customers",
      "method": "POST",
      "description": "Create a new customer."
    },
    "list": {
      "href": "https://api.selectwin.io/v1/customers",
      "method": "GET",
      "description": "List all customers."
    }
  }
}

Campos da resposta

Erros

Trate erros pelo error.code, nunca pela message (o code é estável; o texto pode mudar). Para o envelope completo, veja Tratamento de Erros e o Catálogo de Códigos de Erro.

Como o objetivo é remover o cliente, um 404 customerNotFound numa repetição costuma significar que a exclusão já aconteceu. Trate esse caso como sucesso idempotente no seu fluxo.

Exemplo de erro (404):

{
  "error": {
    "code": "customerNotFound",
    "statusCode": 404,
    "category": "client",
    "message": "Customer not found."
  }
}

Boas práticas

• Verifique dependências antes. Consulte o cliente com Read (que traz transactions) ou liste transações por cliente para confirmar que a remoção é segura e evitar 422 customerDeleteNotProcessable.
• Trate o 404 como sucesso idempotente. Em retries, "cliente não encontrado" geralmente quer dizer "já excluído". Não trate como falha grave.
• Não precisa de X-Idempotency-Key aqui. DELETE é naturalmente idempotente: uma repetição (timeout de rede, retry automático) não causa efeito duplicado. A chave de idempotência é voltada a operações de escrita (POST/PUT). Veja Idempotência.
• Confirme pelo status 200/deleted: true, não pela presença de dados do cliente — eles não retornam.
• Considere inativar em vez de excluir quando houver histórico relevante: a exclusão remove a referência cadastral de transações passadas.
• Registre uma trilha de auditoria (quem excluiu, quando, por quê), especialmente para pedidos de LGPD/GDPR — guarde o id retornado.
• Confirme a ação na sua UI antes de chamar o endpoint: por ser irreversível, um clique acidental é definitivo.

Veja também

• Visão geral de Clientes — o objeto, o ciclo de vida e todas as operações.
• Criar cliente · Ler cliente · Atualizar cliente · Listar clientes
• Convenções · Idempotência · Catálogo de Códigos de Erro