Endpoint responsável por remover um cliente cadastrado na conta Asaas.

Essa operação deve ser utilizada com cuidado, pois a remoção do cliente impacta recursos vinculados, como assinaturas e cobranças que ainda estejam em aberto.

Quando utilizar

Utilize este endpoint quando sua integração precisar remover um cliente que não deve mais permanecer ativo no cadastro da conta.

Alguns cenários comuns incluem:

• exclusão de cadastros incorretos;
• limpeza de dados de teste;
• remoção de duplicidades;
• correção de clientes criados indevidamente;
• remoção de um cliente que não será mais utilizado em novos fluxos;
• sincronização de uma exclusão realizada no sistema de origem.

Quando não utilizar

Não utilize este endpoint para:

• atualizar dados cadastrais de um cliente;
• corrigir nome, e-mail, telefone, CPF/CNPJ ou endereço;
• cancelar apenas uma cobrança específica;
• cancelar apenas uma assinatura específica;
• estornar valores pagos;
• devolver dinheiro ao pagador;
• remover cobranças já pagas;
• substituir uma rotina de inativação no sistema de origem;
• apagar histórico financeiro interno da sua aplicação.

Caso a intenção seja alterar dados do cliente, utilize o endpoint de atualização de cliente.

Caso a intenção seja remover apenas uma cobrança, utilize o endpoint de remoção de cobrança.

Caso a intenção seja encerrar uma recorrência, avalie o endpoint de remoção ou atualização de assinatura.

Parâmetro da requisição

Este endpoint utiliza apenas o identificador do cliente no path da requisição.

Exemplo de identificador:

cus_000005401844

O id deve corresponder a um cliente existente na conta Asaas autenticada.

Este endpoint não exige envio de parâmetros no corpo da requisição.

Autenticação e autorização

Para remover um cliente, a requisição deve ser autenticada com uma API Key válida da conta Asaas.

Antes de executar a operação, valide se:

• a API Key pertence ao ambiente correto, Sandbox ou Produção;
• a API Key pertence à conta em que o cliente foi criado;
• a aplicação possui autorização para realizar operações de remoção;
• o cliente informado no path pertence à conta autenticada;
• o identificador utilizado corresponde ao cliente correto.

Impacto da remoção

Ao remover um cliente, o sistema também remove:

• assinaturas vinculadas;
• cobranças aguardando pagamento;
• cobranças vencidas.

Isso significa que a operação pode afetar fluxos financeiros que ainda estavam em aberto para esse cliente.

Cuidados antes da exclusão

Antes de remover um cliente, valide se existem recursos vinculados que precisam ser mantidos.

Recomenda-se verificar:

• se o cliente possui cobranças aguardando pagamento;
• se o cliente possui cobranças vencidas;
• se o cliente possui assinaturas ativas;
• se existem pedidos, vendas ou contratos vinculados no sistema de origem;
• se o cliente ainda pode receber novas cobranças por alguma automação;
• se Webhooks ou rotinas internas dependem do cliente ativo;
• se a remoção deve ser refletida em sistemas externos, como ERP, CRM ou plataforma própria.

Fluxo recomendado antes da remoção:

Identificar o cliente no sistema de origem
↓
Validar o id do cliente no Asaas
↓
Consultar dados atuais do cliente
↓
Verificar cobranças e assinaturas vinculadas
↓
Confirmar que os recursos impactados podem ser removidos
↓
Executar a remoção
↓
Atualizar o status do cliente no sistema de origem

Exemplo de chamada

curl --request DELETE \
  --url https://api-sandbox.asaas.com/v3/customers/cus_000005401844 \
  --header 'accept: application/json' \
  --header 'access_token: $ASAAS_API_KEY'

Retorno esperado

Em caso de sucesso, a API retorna 200 OK.

Exemplo de retorno de sucesso:

{
  "deleted": true,
  "id": "cus_000005401844"
}

Após receber sucesso na remoção, atualize o registro correspondente no sistema de origem para evitar novas tentativas de cobrança, assinatura ou sincronização para o cliente removido.

Comportamento da remoção

Ao utilizar este endpoint, considere os seguintes comportamentos:

• a operação remove o cliente do fluxo ativo da conta;
• assinaturas vinculadas ao cliente são removidas;
• cobranças aguardando pagamento vinculadas ao cliente são removidas;
• cobranças vencidas vinculadas ao cliente são removidas;
• a operação não cria um novo cliente;
• a operação não altera automaticamente registros no sistema de origem;
• a operação não representa estorno ou devolução de valores;
• chamadas repetidas para um cliente já removido podem retornar erro;
• caso a remoção tenha sido indevida, avalie o endpoint de restauração de cliente removido.

Regras de negócio importantes

Antes de implementar este endpoint, considere as seguintes regras:

• o cliente deve existir no Asaas;
• o id informado deve pertencer à conta autenticada;
• a requisição deve ser feita com API Key válida;
• a remoção afeta assinaturas vinculadas;
• a remoção afeta cobranças aguardando pagamento;
• a remoção afeta cobranças vencidas;
• a remoção não deve ser usada para corrigir dados cadastrais;
• a remoção não deve ser usada para devolver valores de cobranças pagas;
• a integração deve impedir a criação de novas cobranças para clientes removidos;
• o sistema de origem deve ser atualizado após a remoção.

Dependências com outros recursos

O cliente pode estar relacionado a diversos recursos da integração.

Antes de remover, avalie impactos em:

Impactos operacionais

A remoção de um cliente pode impactar rotinas comerciais, financeiras e de suporte.

Alguns impactos importantes:

• cobranças em aberto podem deixar de estar disponíveis;
• assinaturas vinculadas podem ser removidas;
• automações internas podem falhar caso tentem usar o cliente removido;
• relatórios internos podem apresentar divergência se o sistema de origem não for atualizado;
• equipes de atendimento podem não localizar o cliente como ativo;
• integrações externas podem continuar tentando sincronizar dados se não forem atualizadas;
• a remoção incorreta pode exigir restauração posterior, quando aplicável.

Por isso, registre internamente quem solicitou a remoção, quando ela ocorreu e qual foi o motivo operacional.

Diferença entre remover, atualizar e restaurar cliente

Tratamento de erros

Alguns erros comuns ao utilizar este endpoint incluem:

Boas práticas

Para uma implementação mais segura, recomenda-se:

• armazenar o id do cliente no momento da criação;
• consultar o cliente antes de removê-lo;
• verificar cobranças e assinaturas vinculadas;
• bloquear novas cobranças internas antes de remover o cliente;
• interromper automações que possam recriar cobranças para o cliente;
• registrar logs da operação no sistema de origem;
• diferenciar remoção de cliente, remoção de cobrança, cancelamento de assinatura e estorno;
• atualizar o status interno após a remoção;
• evitar retentativas automáticas sem validar o estado atual do cliente;
• testar o fluxo em Sandbox antes de utilizar em Produção.

Cuidados em Sandbox

Em Sandbox, utilize este endpoint para validar o comportamento da sua integração antes de operar em Produção.

Durante os testes, recomenda-se validar:

• criação de um cliente fictício;
• criação de cobranças aguardando pagamento para esse cliente;
• criação de assinatura vinculada ao cliente;
• remoção do cliente;
• consulta posterior do cliente removido;
• comportamento das cobranças e assinaturas vinculadas;
• tentativa de remoção com id inválido;
• atualização do sistema de origem após o retorno 200;
• restauração do cliente removido, quando aplicável ao fluxo.

Conteúdos relacionados

Consulte também:

• Criar novo cliente;
• Listar clientes;
• Recuperar um único cliente;
• Atualizar cliente existente;
• Restaurar cliente removido;
• Criar nova cobrança;
• Excluir cobrança;
• Criar nova assinatura;
• Remover assinatura;
• Webhooks para cobranças.