Endpoint responsável por restaurar um cliente previamente removido da conta Asaas.

A restauração permite que um cadastro de cliente volte a ficar disponível para uso em fluxos operacionais da integração, como consulta, atualização cadastral, criação de cobranças, assinaturas e demais recursos que dependem de um cliente ativo.

Este endpoint deve ser utilizado quando a remoção do cliente foi indevida ou quando sua aplicação precisa reativar um cadastro removido anteriormente sem criar um novo cliente duplicado.

Quando utilizar este endpoint

Utilize este endpoint quando sua integração precisar:

• reverter a remoção indevida de um cliente;
• recuperar um cadastro removido por erro operacional;
• reativar um cliente que ainda precisa ser utilizado em novos fluxos;
• corrigir uma sincronização incorreta entre sua base e o Asaas;
• evitar a criação de um novo cliente duplicado;
• manter o mesmo identificador do cliente em integrações que já armazenavam o id do Asaas.

Esse endpoint é útil em cenários em que o cliente foi removido, mas ainda precisa continuar relacionado à operação da sua plataforma.

Quando não utilizar

Não utilize este endpoint para:

• criar um novo cliente;
• restaurar cobranças, assinaturas ou outros recursos removidos;
• recuperar um cliente cujo identificador não é conhecido;
• substituir o fluxo de criação de cliente;
• reativar registros que não pertencem à conta autenticada;
• corrigir dados cadastrais do cliente.

Caso o objetivo seja alterar informações cadastrais de um cliente ativo, utilize o endpoint de atualização de cliente.

Parâmetro da requisição

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

O id deve corresponder a um cliente previamente criado no Asaas, normalmente no formato:

cus_000005401844

Este endpoint não utiliza parâmetros no body.

Pré-requisitos

Antes de solicitar a restauração, verifique se:

• o cliente foi criado anteriormente no Asaas;
• o cliente foi removido previamente;
• sua aplicação possui o identificador id do cliente;
• a chave de API utilizada pertence à conta em que o cliente foi criado;
• o cliente não foi substituído por outro cadastro na sua base interna;
• sua aplicação está preparada para sincronizar novamente o status do cliente após a restauração.

Fluxo recomendado

Em uma integração típica, o fluxo de restauração de cliente deve seguir as etapas abaixo:

Identificar o cliente removido na base interna
↓
Validar o id do cliente no Asaas
↓
Solicitar a restauração
↓
Validar a resposta da API
↓
Consultar o cliente restaurado
↓
Atualizar o status do cliente na base interna
↓
Retomar fluxos que dependem do cliente ativo

Após restaurar o cliente, recomenda-se realizar uma nova consulta para confirmar o estado atual do cadastro antes de seguir com operações dependentes, como criação de cobranças ou assinaturas.

Exemplo de chamada

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

Exemplo de resposta

Após a restauração, a API retorna os dados do cliente restaurado.

{
  "object": "customer",
  "id": "cus_000005401844",
  "dateCreated": "2026-06-30",
  "name": "Cliente Exemplo",
  "email": "[email protected]",
  "cpfCnpj": "12345678909",
  "phone": "1130000000",
  "mobilePhone": "11990000000",
  "deleted": false
}

Comportamento da restauração

Ao restaurar um cliente removido:

• o cadastro volta a ficar disponível para consulta e uso na conta Asaas;
• o mesmo identificador id do cliente é mantido;
• o cliente pode voltar a ser utilizado em novos fluxos que exigem um cliente ativo;
• a operação não cria um novo cliente;
• a operação não altera automaticamente dados cadastrais do cliente;
• a operação não deve ser tratada como criação de um novo registro;
• sua aplicação deve atualizar a situação do cliente na base interna após o sucesso da chamada.

A restauração deve ser entendida como uma reversão da remoção do cadastro do cliente, e não como uma recriação completa.

Relação com outros recursos

Clientes podem estar relacionados a outros recursos da API, como:

• cobranças;
• assinaturas;
• notificações;
• notas fiscais;
• cobranças parceladas;
• configurações internas da sua aplicação.

A restauração do cliente não deve ser usada como garantia de que todos os fluxos vinculados estarão automaticamente prontos para uso sem validação.

Após restaurar o cliente, recomenda-se consultar os recursos relacionados que sua aplicação utiliza para confirmar se o fluxo pode continuar normalmente.

Exemplos:

• se o cliente será usado para criar uma nova cobrança, consulte o cliente restaurado antes da criação;
• se o cliente estava associado a uma assinatura, valide o status da assinatura;
• se havia cobranças anteriores, consulte o status dessas cobranças antes de atualizar a conciliação;
• se sua aplicação removeu ou inativou o cliente internamente, sincronize novamente a base local.

Idempotência e chamadas repetidas

Não trate este endpoint como uma operação idempotente sem validar a resposta da API.

Se a restauração for solicitada mais de uma vez para o mesmo cliente, o comportamento pode variar conforme o estado atual do cadastro.

Possíveis cenários:

Por isso, após uma chamada bem-sucedida, atualize sua base interna para evitar novas tentativas desnecessárias.

Regras de negócio importantes

Antes de implementar este endpoint, considere as seguintes regras:

• somente clientes previamente removidos podem ser restaurados;
• o id informado deve pertencer a um cliente da conta autenticada;
• o endpoint não cria clientes novos;
• o endpoint não restaura cobranças, assinaturas ou outros recursos removidos separadamente;
• o endpoint não atualiza dados cadastrais;
• a restauração mantém o identificador original do cliente;
• a aplicação deve validar se o cliente restaurado está apto para o fluxo seguinte;
• a documentação pública do endpoint não informa um prazo limite para restauração de clientes removidos.

Erros comuns

Alguns erros comuns ao utilizar este endpoint incluem:

Boas práticas

Ao implementar a restauração de clientes removidos, recomenda-se:

• armazenar o id do cliente retornado pelo Asaas no momento da criação;
• evitar criar um novo cliente antes de tentar restaurar o cadastro removido;
• registrar logs de quem solicitou a restauração e quando ela ocorreu;
• consultar o cliente após a restauração para confirmar o estado atualizado;
• sincronizar a base interna da sua aplicação após sucesso da chamada;
• validar recursos relacionados antes de retomar processos automáticos;
• tratar erros 400, 401 e 404 de forma clara para o operador ou usuário interno;
• evitar retentativas automáticas sem verificar o estado atual do cliente;
• testar o fluxo em Sandbox antes de disponibilizar a funcionalidade em Produção.

Impactos operacionais

A restauração de um cliente pode impactar fluxos internos da integração.

Alguns impactos possíveis são:

• reativação do cliente em cadastros internos;
• retomada da possibilidade de criar cobranças para o cliente;
• necessidade de sincronizar status entre Asaas e sistema externo;
• risco de duplicidade caso a aplicação crie um novo cliente em vez de restaurar o existente;
• divergência em relatórios se o cliente estiver removido em um sistema e ativo em outro;
• necessidade de validar cobranças, assinaturas ou registros relacionados após a restauração.

Por isso, trate a restauração como uma operação administrativa sensível e mantenha rastreabilidade interna.

Cuidados em Sandbox

Este endpoint pode ser testado em Sandbox.

Recomenda-se validar os seguintes cenários:

• criar um cliente;
• remover o cliente;
• restaurar o cliente;
• consultar o cliente após a restauração;
• tentar restaurar novamente o mesmo cliente;
• tentar restaurar um ID inexistente;
• validar como sua aplicação atualiza a base interna em cada resposta.

Esses testes ajudam a definir o comportamento esperado antes da operação em Produção.

Conteúdos relacionados

Consulte também:

• Criar novo cliente;
• Listar clientes;
• Recuperar um único cliente;
• Atualizar cliente existente;
• Remover cliente;
• Criar nova cobrança;
• Criar assinatura;
• O que pode ser testado em Sandbox.