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. ### Atenção A remoção impacta outros objetos vinculados ao cliente. Avalie previamente se existem cobranças, assinaturas ou fluxos operacionais que precisam ser mantidos antes de executar essa operação. *** ## 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. | Parâmetro | Local | Obrigatório | Descrição | | --------- | ----- | ----------- | ---------------------------------------------- | | `id` | Path | Sim | Identificador único do cliente a ser removido. | Exemplo de identificador: ```text 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. ### Boa prática Em integrações com múltiplos ambientes, valide se o `id` do cliente e a API Key pertencem ao mesmo ambiente. Um cliente criado em Sandbox não pode ser removido usando credenciais de Produção, e o contrário também se aplica. *** ## 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. ### Atenção A remoção do cliente não deve ser tratada como estorno, reembolso ou devolução de valores. Se houver cobrança paga e a intenção for devolver valores ao pagador, utilize o fluxo de estorno adequado ao meio de pagamento. *** ## 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: ```text 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 ```bash curl --request DELETE \ --url https://api-sandbox.asaas.com/v3/customers/cus_000005401844 \ --header 'accept: application/json' \ --header 'access_token: $ASAAS_API_KEY' ``` ### Observação O identificador `cus_000005401844` é apenas ilustrativo. Utilize o ID real do cliente retornado pela API do Asaas no momento da criação, listagem ou consulta individual. *** ## Retorno esperado Em caso de sucesso, a API retorna `200 OK`. Exemplo de retorno de sucesso: ```json { "deleted": true, "id": "cus_000005401844" } ``` | Campo | Descrição | | --------- | ---------------------------------------------- | | `deleted` | Indica que o cliente foi removido com sucesso. | | `id` | Identificador do cliente removido. | 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. ### Atenção Não dependa de uma ordem interna específica de remoção dos recursos vinculados. Trate a operação como uma remoção do cliente e dos objetos impactados informados pela API, e depois consulte os recursos necessários para sincronizar sua aplicação. *** ## 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: | Recurso | Impacto possível | | ------------------------------ | ---------------------------------------------------------------------------- | | Cobranças aguardando pagamento | Podem ser removidas junto com o cliente. | | Cobranças vencidas | Podem ser removidas junto com o cliente. | | Assinaturas | Podem ser removidas junto com o cliente. | | Notificações | Fluxos de comunicação relacionados ao cliente podem deixar de fazer sentido. | | Sistema de origem | O cliente deve ser marcado como removido, inativo ou equivalente. | | Webhooks | Eventos posteriores podem exigir atualização do status interno. | | ERP, CRM ou e-commerce | Dados sincronizados devem ser revisados para evitar divergências. | *** ## 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 | Operação | Quando usar | | -------------------------- | ------------------------------------------------------------------------- | | Atualizar cliente | Quando o cadastro está correto, mas algum dado precisa ser alterado. | | Remover cliente | Quando o cliente não deve mais permanecer ativo no cadastro da conta. | | Restaurar cliente removido | Quando um cliente removido precisa ser recuperado, se o cenário permitir. | | Criar novo cliente | Quando se trata de um novo pagador que ainda não existe na conta. | ### Boa prática Se o problema for apenas dado incorreto, prefira atualizar o cliente em vez de removê-lo. Use a remoção apenas quando o cadastro realmente não deve mais permanecer ativo. *** ## Tratamento de erros Alguns erros comuns ao utilizar este endpoint incluem: | Status HTTP | Possível causa | Como corrigir | | -------------------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | | `400 Bad Request` | Requisição inválida ou operação não permitida para o estado atual do cliente | Revise o identificador informado e valide os recursos vinculados ao cliente | | `401 Unauthorized` | API Key ausente, inválida ou pertencente ao ambiente incorreto | Confirme a API Key utilizada e o ambiente da requisição | | `404 Not found` | Cliente não encontrado para o `id` informado | Verifique se o ID foi armazenado corretamente e se pertence à conta autenticada | | Cliente já removido | Nova tentativa de remover um cliente que não está mais ativo | Consulte o cliente ou avalie se é necessário restaurá-lo | | Divergência no sistema de origem | Cliente removido no Asaas, mas ainda ativo internamente | Atualize o status do cliente na sua aplicação | *** ## 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.

200Ok

400Bad Request

401Unauthorized