Endpoint responsável por restaurar uma cobrança removida anteriormente.

Essa chamada permite reativar a cobrança utilizando o mesmo identificador original, desde que ela esteja em um estado compatível com restauração.

Quando utilizar

Utilize este endpoint quando sua integração precisar recuperar uma cobrança removida anteriormente e recolocá-la no fluxo operacional.

Alguns cenários comuns incluem:

• restauração de cobrança removida por engano;
• reversão de exclusão operacional;
• recuperação de registros removidos em testes;
• correção de sincronização entre o sistema de origem e o Asaas;
• reativação de uma cobrança que ainda precisa permanecer disponível para acompanhamento, consulta ou pagamento.

Quando não utilizar

Não utilize este endpoint para:

• criar uma nova cobrança;
• atualizar dados de uma cobrança existente;
• estornar uma cobrança paga;
• cancelar uma assinatura;
• restaurar um parcelamento removido;
• restaurar um cliente removido;
• reativar cobranças que não pertencem à conta autenticada;
• corrigir cobranças que ainda podem ser atualizadas por outros endpoints.

Caso a intenção seja alterar dados da cobrança, utilize o endpoint de atualização de cobrança.

Caso a intenção seja devolver valores ao pagador, utilize o fluxo de estorno correspondente ao meio de pagamento.

Parâmetro da requisição

Este endpoint utiliza apenas o identificador da cobrança no path da requisição.

Exemplo de identificador:

pay_123456789

O id deve corresponder a uma cobrança existente na conta Asaas autenticada e previamente removida.

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

Permissão e autenticação

Para utilizar este endpoint, a requisição deve ser autenticada com uma API Key válida da conta Asaas.

A chave utilizada deve pertencer ao mesmo ambiente da requisição:

• API Key de Sandbox para chamadas em Sandbox;
• API Key de Produção para chamadas em Produção.

Caso a API Key esteja ausente, inválida ou pertença a outro ambiente, a requisição poderá retornar erro de autorização.

Dependências da restauração

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

• a cobrança foi criada anteriormente no Asaas;
• a cobrança pertence à conta autenticada;
• o id da cobrança foi armazenado corretamente pela integração;
• a cobrança foi removida anteriormente;
• o cliente vinculado à cobrança ainda permite a continuidade do fluxo;
• a cobrança está em um estado compatível com restauração;
• a integração está preparada para atualizar o status interno após a restauração.

Funcionamento da restauração

A restauração reativa uma cobrança removida anteriormente, mantendo o mesmo id original.

Após uma restauração concluída com sucesso:

• a cobrança volta a ficar disponível para consulta;
• a cobrança pode voltar ao fluxo operacional correspondente;
• o identificador original da cobrança é mantido;
• a cobrança não é recriada;
• uma nova cobrança não é gerada;
• os dados vinculados à cobrança devem ser consultados novamente pela integração.

A restauração não altera automaticamente outros recursos que sua aplicação mantenha no sistema de origem, como pedido, venda, status interno, conciliação ou histórico de sincronização.

Comportamentos importantes

Ao utilizar este endpoint, considere os seguintes comportamentos:

• a restauração só é aplicável a cobranças previamente removidas;
• a chamada utiliza o mesmo id da cobrança original;
• a operação não cria uma nova cobrança;
• a operação não estorna valores;
• a operação não altera automaticamente pedidos, vendas ou registros internos da integração;
• a cobrança restaurada deve ser consultada novamente após a operação;
• o estado final da cobrança deve ser usado para atualizar o sistema de origem;
• chamadas repetidas para uma cobrança já restaurada podem ser recusadas pela API;
• se a cobrança não estiver elegível para restauração, a API poderá retornar erro.

Regras de negócio importantes

Antes de implementar este endpoint, considere as seguintes regras:

• a cobrança deve existir no Asaas;
• a cobrança deve ter sido removida anteriormente;
• o id informado deve pertencer à conta autenticada;
• a requisição deve ser autenticada com uma API Key válida;
• a cobrança precisa estar em um estado compatível com restauração;
• a restauração mantém o mesmo identificador da cobrança;
• a restauração não cria uma nova cobrança;
• a restauração não altera automaticamente o histórico interno da integração;
• a restauração não substitui fluxos de estorno, cancelamento ou atualização;
• a API pode recusar a operação caso a cobrança não seja elegível.

A documentação pública do endpoint não informa um prazo máximo fixo para restauração. Por isso, trate a elegibilidade como uma validação realizada pela API no momento da requisição.

Exemplo de chamada

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

Retorno esperado

Em caso de sucesso, a API retorna status 200 OK.

Após receber sucesso na restauração, recomenda-se consultar a cobrança restaurada para recuperar seus dados atualizados e confirmar o status atual no Asaas.

Fluxo recomendado após o retorno 200:

Solicitar restauração da cobrança
↓
Receber retorno 200 OK
↓
Consultar a cobrança pelo mesmo id
↓
Validar o status atual da cobrança
↓
Atualizar o registro no sistema de origem
↓
Retomar o fluxo operacional, se aplicável

Exemplo de consulta após restauração

Depois de restaurar a cobrança, sua integração pode consultar o mesmo id para validar o estado atual do recurso.

curl --request GET \
  --url https://api-sandbox.asaas.com/v3/payments/pay_123456789 \
  --header 'accept: application/json' \
  --header 'access_token: $ASAAS_API_KEY'

Essa consulta ajuda a confirmar se a cobrança voltou ao fluxo esperado e quais dados devem ser refletidos no sistema de origem.

Idempotência e chamadas repetidas

Não trate este endpoint como uma operação idempotente.

Se a cobrança já tiver sido restaurada, uma nova tentativa de restauração poderá retornar erro, pois a cobrança pode não estar mais no estado removido.

Para evitar chamadas desnecessárias:

• registre internamente quando a restauração for solicitada;
• consulte a cobrança antes de tentar restaurá-la novamente;
• trate erros de forma segura;
• não execute retentativas automáticas sem validar o estado atual da cobrança.

Relação com outros recursos

A restauração da cobrança não atualiza automaticamente os registros mantidos pela sua aplicação.

Após restaurar a cobrança, avalie se é necessário atualizar também:

• pedido ou venda no sistema de origem;
• status interno da cobrança;
• logs de auditoria;
• controle de conciliação financeira;
• comunicações enviadas ao cliente;
• regras de cobrança, vencimento ou acompanhamento;
• registros relacionados a split, assinatura ou parcelamento, quando aplicável.

Caso a cobrança restaurada esteja vinculada a outros fluxos, consulte os recursos relacionados antes de retomar a operação.

Impactos operacionais

A restauração de uma cobrança removida pode impactar diretamente a sincronização entre o Asaas e o sistema de origem.

Alguns impactos importantes:

• uma cobrança que estava marcada como removida pode voltar a aparecer como ativa ou disponível para acompanhamento;
• o sistema de origem precisa deixar de tratar a cobrança como removida;
• fluxos automáticos podem voltar a considerar a cobrança em consultas ou rotinas internas;
• comunicações internas ou externas podem precisar ser revisadas;
• relatórios, dashboards e conciliações podem precisar refletir a restauração;
• ações futuras devem considerar o status atualizado da cobrança no Asaas.

Por isso, sempre atualize o registro interno após a restauração e mantenha logs da operação.

Erros comuns

Alguns erros comuns ao utilizar este endpoint incluem:

Boas práticas

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

• armazenar o id da cobrança no momento da criação;
• registrar internamente quando uma cobrança for removida;
• restaurar apenas cobranças removidas indevidamente;
• consultar a cobrança antes da restauração quando houver dúvida sobre o estado atual;
• consultar a cobrança novamente após o retorno 200;
• atualizar o status da cobrança no sistema de origem;
• evitar retentativas automáticas sem validação prévia;
• diferenciar restauração de atualização, remoção, cancelamento e estorno;
• registrar logs da operação para auditoria;
• testar o fluxo em Sandbox antes de utilizar em Produção.

Cuidados em Sandbox

Este endpoint pode ser utilizado em Sandbox para validar o fluxo de restauração de cobranças removidas.

Durante os testes, recomenda-se validar:

• criação de uma cobrança fictícia;
• remoção da cobrança;
• restauração utilizando o mesmo id;
• consulta da cobrança após a restauração;
• atualização do status no sistema de origem;
• tentativa de restauração com id inválido;
• tentativa de restauração de cobrança que não foi removida;
• comportamento da aplicação em caso de erro 400, 401 ou 404.

Esses testes ajudam a garantir que sua integração trate corretamente os fluxos de remoção e restauração antes de operar em Produção.

Conteúdos relacionados

Consulte também:

• Criar nova cobrança;
• Recuperar uma única cobrança;
• Recuperar status de uma cobrança;
• Atualizar cobrança existente;
• Excluir cobrança;
• Estornar cobrança;
• Restaurar cobrança removida com dados resumidos na resposta;
• Listar cobranças;
• Webhooks para cobranças.