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:

🚧
Padronização do campo ISPB para CNPJ Alfanumérico
O que vai mudar?
Devido à transição nacional para o CNPJ Alfanumérico, realizaremos a alteração da tipagem do campo ispb em nossa API. Atualmente, embora a documentação já preveja o formato como string, o retorno em produção ainda ocorre como numérico em alguns objetos. No dia da mudança, esses campos passarão a ser retornados como String.
Objetos e endpoints afetados:
Decodificar um QRCode para pagamento: Afeta os dados do recebedor na decodificação de QR Codes (POST /v3/pix/qrCodes/decode) e na leitura de chaves Pix.
Recuperar uma única transação: Afeta os dados do pagador em consultas de transações Pix (GET /v3/pix/transactions/id).
Qual o impacto?
Aplicações que realizam o parse manual desses objetos esperando um tipo Integer/Long ou que possuam validações de schema rígidas para tipos numéricos poderão falhar ao processar os retornos, resultando em erros de integração ou falhas na decodificação de pagamentos Pix.
Ação necessária
Revise o tratamento desses endpoints em sua integração. Certifique-se de que seu parser de JSON e suas classes de dados (DTOs) estejam preparados para tratar o campo ispb como uma String. Recomendamos realizar essa alteração em seu ambiente de testes o quanto antes para garantir a retrocompatibilidade.
Data da mudança: 20/05/2026

Abaixo as alterações significativas que já entraram em vigor:

31/03/2026

Atualização de configurações de Notas Fiscais

O que mudou

A alteração afeta exclusivamente o objeto taxes dentro do corpo da requisição de atualização da nota fiscal, ou da configuração de nota fiscal de assinaturas. A partir desta mudança, enviar o objeto taxes de forma parcial, irá remover os demais tributos configurados. Os demais campos do endpoint não tiveram seu comportamento alterado.

Anteriormente, o objeto taxes operava com semântica de PATCH: campos não enviados dentro dele eram ignorados, preservando os valores já configurados na nota fiscal.

A partir desta alteração, o objeto taxes passa a operar com semântica de PUT: campos ausentes dentro dele são interpretados como null, removendo os valores previamente configurados.

PUT/POST em /v3/subscriptions/{id}/invoiceSettings ou PUT em /v3/invoices/{id}

{
  "effectiveDate": "2026-01-01",
  "taxes": {
    "iss": 5.00,
    "retainIss": true
  }
}

Antes

effectiveDate era atualizado normalmente.
Dentro de taxes, apenas iss e retainIss eram atualizados. Campos como cofins, pis e csll mantinham seus valores anteriores.

Agora

effectiveDate continua sendo atualizado normalmente.
Dentro de taxes, iss e retainIss são atualizados, mas todos os demais campos: cofins, pis, csll, inss, ir, pisCofinsRetentionType, pisCofinsTaxStatus, nbsCode, taxSituationCode, taxClassificationCode, operationIndicatorCode são definidos com o valor padrão (geralmente null).

Campos do objeto taxes afetados

Todos os campos abaixo passam a ser tratados como parte de uma substituição completa. Campos não enviados dentro do objeto taxes serão definidos como null, ou zerados:

Campo	Tipo	Descrição
`retainIss`	Boolean	Reter ISS na fonte
`iss`	Decimal	Alíquota de ISS (%)
`cofins`	Decimal	Alíquota de COFINS (%)
`csll`	Decimal	Alíquota de CSLL (%)
`inss`	Decimal	Alíquota de INSS (%)
`ir`	Decimal	Alíquota de IR (%)
`pis`	Decimal	Alíquota de PIS (%)
`pisCofinsRetentionType`	Enum	Tipo de retenção PIS/COFINS
`pisCofinsTaxStatus`	Enum	Status tributário PIS/COFINS
`nbsCode`	String	Código NBS
`taxSituationCode`	String	Código da situação tributária
`taxClassificationCode`	String	Código da classificação tributária
`operationIndicatorCode`	String	Indicador de operação

Recomendações para novas integrações

1. Trate o objeto taxes como uma substituição completa

Ao enviar o objeto taxes, inclua sempre o estado completo desejado para todos os campos de impostos. Nunca assuma que campos não enviados dentro de taxes serão preservados.

2. Consulte antes de escrever

Caso a sua integração precise alterar apenas um subconjunto dos campos de taxes, realize uma requisição GET para obter os valores atuais antes de enviar o PUT. Em seguida, mescle os campos a alterar sobre os valores existentes e envie o objeto taxes completo.

// 1. Obter configuração atual da nota fiscal
GET /api/v3/invoices/{id}
 
// 2. Enviar o PUT com o objeto taxes completo,
// incluindo os valores existentes dos campos que não devem ser alterados

Exemplo

PUT em /api/v3/invoices/{id}

{
  "effectiveDate": "2026-01-01",
  "taxes": {
    "retainIss": true,
    "iss": 5.00,
    "pis": 0.65,
    "cofins": 3.00,
    "pisCofinsRetentionType": "WITHHELD",
    "pisCofinsTaxStatus": "STANDARD_TAXABLE_OPERATION",
    "csll": 1.00,
    "inss": null,
    "ir": null,
    "nbsCode": "1.0101.11.00",
    "taxSituationCode": "011",
    "taxClassificationCode": "011001",
    "operationIndicatorCode": "030102"
  }
}

3. Trate null como intenção explícita de remoção

Se um campo de taxes deve ser removido da configuração fiscal, envie-o explicitamente como null. Não enviar o campo produz o mesmo efeito, mas a forma explícita torna a intenção clara e o código mais legível e resistente a mudanças futuras.

4. Revise integrações existentes que usam atualização parcial de taxes

Integrações que hoje enviam apenas os campos de impostos que mudam, confiando que os demais serão preservados, precisam ser atualizadas. A forma mais segura de identificar esse padrão é auditar todas as chamadas aos endpoints afetados e verificar se o payload de taxes está completo.

02/02/2026

Padronização do formato de data em Webhooks de Assinaturas

O que mudou? Identificamos uma inconsistência na formatação de datas enviadas nos eventos de webhooks relacionados a assinaturas. Para garantir a conformidade com o padrão utilizado em toda a API v3, alteramos o formato de envio dessas datas de dd/MM/yyyy para o padrão yyyy-MM-dd.
Qual o impacto? Aplicações que realizam o parse manual da string de data ou utilizam máscaras de formatação rígidas esperando dd/MM/yyyy poderão falhar ao processar esses eventos, ou interpretar as datas incorretamente.
Ação necessária: Revise o tratamento de datas no seu endpoint de recebimento de webhooks para eventos de assinatura. Ajuste seu parser para aceitar o formato yyyy-MM-dd antes da data efetiva da mudança para evitar erros de conciliação ou processamento.

02/12/2025

Ciclo de vida automático para chaves de API inativas

O que mudou? 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.

24/11/2025

Confirmação anual dos dados comerciais de contas e subcontas

A 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.

31/10/2025

Correção no retorno do endpoint de exclusão de parcelamentos

O que mudou? O endpoint para remover um parcelamento(DELETE /v3/installments/{id}) foi 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 retorna 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.

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)

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 state será retirada do retorno do recurso no dia 17/02.
Identificamos um retorno incorreto na nossa API de parcelamentos, onde o atributo refunds que 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.