Breaking changes
A API do Asaas está em constante evolução. Algumas alterações são consideras Breaking changes (alterações significativas) pois podem impactar diretamente integrações que esperam que o Asaas responda sempre da mesma forma.
Todas as Breaking Changes são comunicadas para os clientes que serão impactados por e-mail. Você também pode acompanhar alterações programadas através do nosso canal no Discord ou este documento. As comunicações podem ser enviadas para toda a base de clientes ou somente para clientes que utilizem aquela funcionalidade específica, como subcontas, por exemplo.
Confira abaixo o calendário de alterações significativas com a data em que elas entrarão em vigor:
24/11/2025
Confirmação anual dos dados comerciais de contas e subcontasA partir do dia 24 de novembro de 2025, será obrigatória a confirmação ou atualização anual dos dados comerciais da sua conta e subcontas, conforme exigência do Bacen.
As contas com dados comerciais não confirmados ou atualizados terão o acesso à API bloqueado!
Consulte o nosso guia sobre Confirmação Anual de Dados Comerciais para Subcontas para mais detalhes.
17/11/2025
Ciclo de vida automático para chaves de API inativas
- O que mudará? Para fortalecer a segurança da plataforma, o Asaas irá implementar um ciclo de vida automatizado para chaves de API. Chaves que permanecerem inativas por longos períodos serão desabilitadas (após 3 meses) ou expiradas permanentemente (após 6 meses).
- Qual o impacto? Se você possui chaves de API que são usadas com pouca frequência (intervalos maiores que 3 meses), sua integração pode ser interrompida. Chaves desabilitadas retornam erro 401 e precisam ser reativadas manualmente. Chaves expiradas não podem ser recuperadas.
- Ação necessária: Revise todas as suas chaves de API para garantir que não há credenciais importantes em risco de inativação. Considere usar os Webhooks de Chaves de API para monitorar esses eventos de forma automática. Entenda todas as regras em nosso Guia de Ciclo de Vida.
31/10/2025
Correção no retorno do endpoint de exclusão de parcelamentos
- O que mudará? O endpoint para remover um parcelamento(
DELETE /v3/installments/{id}) será corrigido para alinhar-se ao padrão de toda a nossa API. Anteriormente, a resposta retornava um número inteiro. A partir de agora, o campo id na resposta retornará uma string no formato UUID.- Qual o impacto? Esta alteração pode quebrar integrações que esperam receber um número inteiro e realizam validação estrita de tipos.
- Ação necessária: Ajuste sua aplicação para tratar o campo id na resposta do endpoint como uma string. Nenhuma outra alteração é necessária.
Abaixo as alterações significativas que já entraram em vigor:
08/09/2025
Alteração nas respostas dos endpoints referente a antecipações de recebíveis
O atributo defaultFee, que aparece no retorno de algumas operações de antecipação de recebíveis, será removido
Atualmente, ele é sempre retornado como null e não possui mais nenhuma funcionalidade. A remoção faz parte de um esforço para limpar atributos obsoletos e tornar as respostas da nossa API mais enxutas.
Como este atributo não é documentado e não possui mais utilidade, não esperamos nenhum impacto em sua integração. Esta comunicação é um ato de transparência para que vocês estejam sempre cientes das melhorias que realizamos na plataforma.
30/08/2025
Padronização do User-Agent em Webhooks Asaas(Produção)
Para melhorar a confiabilidade e a segurança das nossas notificações, padronizamos o User-Agent que enviamos em todos os nossos webhooks, incluindo o mecanismo de validação de saque em nosso ambiente de produção.
- Novo User-Agent (Produção):
Asaas_Prod/3.0 - Novo User-Agent para o mecanismo de validação de saque (Produção):
Asaas_Prod
15/08/2025
Padronização do User-Agent em Webhooks Asaas(Sandbox)
Para melhorar a confiabilidade e a segurança das nossas notificações, padronizamos o User-Agent que enviamos em todos os nossos webhooks, incluindo o mecanismo de validação de saque em nosso ambiente de testes(Sandbox).
- Novo User-Agent (Sandbox):
Asaas_Hmlg/3.0 - Novo User-Agent para o mecanismo de validação de saque (Sandbox):
Asaas_Hmlg
07/07/2025
Alteração nas respostas dos endpoints referente a dados comerciais
O objeto revenueServiceRegister, que atualmente é retornado nas respostas dos endpoints GET /v3/myAccount/commercialInfo/ e POST /v3/myAccount/commercialInfo/, será removido nas próximas semanas.
Como este objeto nunca foi documentado oficialmente, não esperamos que esta mudança afete as integrações. Esta é uma comunicação proativa para garantir total transparência com a comunidade.
Pedimos que, por garantia, revisem suas integrações que consomem os endpoints de Dados Comerciais para confirmar que não há nenhuma dependência inesperada neste objeto revenueServiceRegister.
14/04/2025
⚠️ MUDANÇA NAS CASAS DECIMAIS ACEITAS EM SPLITS
A partir desta data, faremos uma alteração nas casas decimais aceitas na criação ou atualização de splits.
Splits fixos (criados com fixedValue), aceitarão apenas duas casas decimais. Ex: 9.32 Splits percentuais (criados com percentualValue), aceitarão apenas quatro casas decimais. Ex: 92.3444
Caso o split seja criado com mais casas decimais que o permitido, passaremos a retornar uma exceção traduzida, indicando o motivo do erro.
Confira na sua integração a maneira de envio dos splits e ajuste-a caso necessário.
Essa mudança visa padronizar as regras do split e evitar possíveis cortes de casas decimais ou arredondamentos, garantindo que o split seja executado no valor exato indicado em sua criação/atualização.
Qualquer dúvida, basta nos acionar no e-mail [email protected]
10/03/2025
Novidade: Novo Prefixo de Identificação das Chaves API!: Para facilitar a identificação da sua chave API entre os ambientes de Produção e Sandbox, as chaves API agora seguirão um novo prefixo:
- Produção:
$aact_prod_{hash} - Sandbox:
$aact_hmlg_{hash}
Importante:
- As chaves já existentes continuarão funcionando normalmente.
- O novo formato será aplicado somente às chaves geradas após 10/03.
- Não é obrigatório gerar uma nova chave, somente se desejar.
Veja mais sobre aqui.
17/02/2025
- Anteriormente, a nossa abrangência de consulta para analisar se um Cliente possuía protesto era estadual. Agora, o Asaas oferece esta consulta em abrangência nacional, não sendo mais necessário informar o estado ao solicitar uma Consulta Serasa. Por esse motivo, a propriedade
stateserá retirada do retorno do recurso no dia 17/02. - Identificamos um retorno incorreto na nossa API de parcelamentos, onde o atributo
refundsque deveria retornar uma lista de estornos realizados nesse parcelamento acaba retornando uma lista de lista de estornos. Com isso, para manter a consistência da API, no dia 17/02 iremos alterar seu retorno para que seja uma lista de objetos de estorno.
12/11/2024
- A alteração para uso da nova rota de nossa API entrou em vigor. A partir desta data, conforme comunicados prévios, a conexão com o Asaas deve ser realizada através do domínio https://api.asaas.com/v3, conforme descrito em nossa seção de autenticação.
23/10/2024
23/10/2024
21/10/2024
20/09/2024
- Ação necessária: Atualização domínio API Asaas ⚠️
- Padronização do retorno de faturamento/renda mensal
16/09/2024
30/08/2024
05/08/2024
02/07/2024
14/06/2024
29/05/2024
30/05/2024
15/04/2024
- Remoção do campo tradingName em dados comerciais das contas
- Mudança no formato do campo retornado via API e Webhooks