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:

Breaking Changes - NT-007: Novas regras de PIS/COFINS na emissão de NFS-e via API

Data de obrigatoriedade: 30/06/2026
Versão da API afetada: v3
Classificação: Breaking Change — ação requerida apenas para clientes Regime Normal (Lucro Real/Presumido)

Visão geral

A NT-007 (Nota Técnica 007 do padrão nacional de NFS-e) altera as regras de validação, normalização e envio ao fisco de informações relacionadas a PIS e COFINS na emissão de notas fiscais de serviço.

O impacto é exclusivo para clientes do Regime Normal (Lucro Real ou Presumido). Clientes do Simples Nacional não possuem alterações de payload, respostas da API, validações ou XML enviado ao fisco.

A partir de 30/06/2026, clientes do Regime Normal deverão:

• Informar obrigatoriamente o campo pisCofinsTaxStatus.
• Informar os novos campos operationPis e operationCofins.
• Deixar de enviar pisCofinsRetentionType, que passa a ser calculado automaticamente pelo Asaas.

Quem é afetado

Clientes afetados

Clientes do Regime Normal (Lucro Real ou Presumido) que utilizam os seguintes endpoints:

Clientes não afetados

Clientes do Simples Nacional. Nenhuma alteração será necessária em payloads, respostas, validações ou XML.

Resumo das mudanças

Ações recomendadas

Para adequar sua integração à NT-007:

1. Identifique se o cliente utiliza Regime Normal.
2. Adicione pisCofinsTaxStatus.
3. Passe a enviar operationPis e operationCofins.
4. Pare de enviar pisCofinsRetentionType.
5. Atualize os parsers para ler os novos campos de resposta.
6. Substitua o enum depreciado TAXABLE_CONTRIBUTION_OPERATION.
7. Realize testes utilizando a flag useTaxSystemReformNT007.

Período de migração

Até 30/06/2026, as regras antigas e as regras da NT-007 podem coexistir.

Para ativar antecipadamente as validações da NT-007, envie:

{
  "taxes": {
    "useTaxSystemReformNT007": true
  }
}

Comportamento durante a migração

Após 30/06/2026, as regras da NT-007 passam a ser aplicadas automaticamente para todos os clientes do Regime Normal.

Exemplo de adoção antecipada

Com a aplicação automática das regras da NT-007, o envio da flag deixa de ser necessário.

{
  "payment": "pay_xxx",
  "taxes": {
    "useTaxSystemReformNT007": true,
    "pisCofinsTaxStatus": "STANDARD_TAXABLE_OPERATION",
    "operationPis": 0.65,
    "operationCofins": 3.00,
    "pis": 0.65,
    "cofins": 3.00,
    "csll": 1.00
  }
}

Referência técnica

BC-1 — pisCofinsTaxStatus obrigatório

Aplicação

Clientes Regime Normal.

Endpoints

• /v3/invoices
• /v3/subscriptions

Antes

{
  "taxes": {
    "pis": 0.65,
    "cofins": 3.00
  }
}

Depois

{
  "taxes": {
    "pis": 0.65,
    "cofins": 3.00,
    "csll": 1.00,
    "pisCofinsTaxStatus": "STANDARD_TAXABLE_OPERATION",
    "operationPis": 0.65,
    "operationCofins": 3.00
  }
}

Erro retornado

{
  "errors": [
    {
      "description": "A Situação tributária do PIS/COFINS é obrigatória"
    }
  ]
}

BC-2 — pisCofinsRetentionType calculado automaticamente

pisCofinsRetentionType deixa de ser um campo controlado pelo cliente.

O valor passa a ser calculado automaticamente com base nos percentuais informados de PIS, COFINS e CSLL:

• Se PIS > 0 e COFINS > 0 e CSLL > 0 → PIS_COFINS_CSLL_WITHHELD
• Se PIS > 0 e COFINS > 0 → PIS_COFINS_WITHHELD_CSLL_NOT_WITHHELD
• Se apenas PIS > 0 → PIS_WITHHELD_COFINS_CSLL_NOT_WITHHELD
• (...combinações análogas para os demais cenários...)
• Se todos zero/nulos → PIS_COFINS_CSLL_NOT_WITHHELD

Ação requerida

Remova o campo do payload e utilize o valor retornado pela API para conciliação.

BC-3 — Validações de operationPis e operationCofins

Os campos operationPis / operationCofins (em /v3/invoices e /v3/subscriptions) passam a ser validados pela restrição NT-007 do pisCofinsTaxStatus. Essa é a mesma família de regras que antes recaía sobre o par pisCofinsTaxStatus + pisCofinsRetentionType — agora ela é exigida sobre os percentuais de operação.

Mudança de comportamento do CST NONE: antes os campos de operação eram livres com NONE. Após a NT-007, pisCofinsTaxStatus = NONE exige operationPis e operationCofins nulos (ALWAYS_NULL_PIS_COFINS). Os campos legados pis/cofins continuam sem restrição para esse status.

Regras

Mensagens de erro

Valor deve ser nulo

{
  "errors": [
    {
      "description": "O percentual de PIS de operação deve ser nulo para a Situação tributária do PIS/COFINS selecionada"
    }
  ]
}

Valor deve ser zero

{
  "errors": [
    {
      "description": "O percentual de PIS de operação deve ser zero para a Situação tributária do PIS/COFINS selecionada"
    }
  ]
}

Valor obrigatório

{
  "errors": [
    {
      "description": "O percentual de PIS de operação é obrigatório para a Situação tributária do PIS/COFINS selecionada"
    }
  ]
}

Caso especial: retenção de PIS/COFINS com CST não configurado (NONE)

Se você já enviava valores de PIS e COFINS retidos (pis, cofins), mas ainda não havia definido pisCofinsTaxStatus ou o valor estava como NONE / código 00, a adequação automática realizada pelo Asaas não inclui a definição do CST nesse cenário.

Isso ocorre porque, nesses casos, o risco de classificação automática incorreta é alto. Por isso, a definição do CST precisa ser feita manualmente pelo cliente.

A partir de 30/06/2026, com pisCofinsTaxStatus = NONE, os campos operationPis e operationCofins passam a ser obrigatoriamente nulos. Isso significa que as informações de retenção de PIS/COFINS deixarão de constar na nota emitida enquanto o CST permanecer como NONE.

Ação necessária: revise sua configuração e defina o pisCofinsTaxStatus correto para o seu contexto tributário. Caso sua operação envolva retenção de PIS/COFINS, o CST mais comum é STANDARD_TAXABLE_OPERATION / código 01. Confirme com sua contabilidade antes de alterar.

BC-4 — Sobrescrita automática para NONE

Os seguintes valores são convertidos automaticamente para NONE:

A conversão ocorre quando todos os percentuais de PIS e COFINS estiverem zerados ou nulos.

Exemplo

Enviado

{
  "taxes": {
    "pisCofinsTaxStatus": "TAXABLE_PER_MEASURE_UNIT_OPERATION",
    "pis": 0,
    "cofins": 0,
    "operationPis": null,
    "operationCofins": null
  }
}

Persistido

{
  "taxes": {
    "pisCofinsTaxStatus": "NONE",
    "operationPis": null,
    "operationCofins": null
  }
}

Ação requerida

Utilize o valor retornado na resposta para conciliação.

BC-5 — Novos campos de resposta

Exemplo

{
  "taxes": {
    "retainIss": false,
    "iss": 5.00,
    "pis": 0.65,
    "cofins": 3.00,
    "csll": 1.00,
    "pisCofinsTaxStatus": "STANDARD_TAXABLE_OPERATION",
    "pisCofinsRetentionType": "PIS_COFINS_CSLL_WITHHELD",
    "operationPis": 0.65,
    "operationCofins": 3.00
  }
}

BC-6 — Enum depreciado

O valor:

TAXABLE_CONTRIBUTION_OPERATION

permanece funcionando temporariamente, mas está marcado como depreciado.

Ação requerida

Migrar para o valor correto conforme a tabela oficial de enums.

Retrocompatibilidade

Durante o período de migração:

Referência de enums

pisCofinsTaxStatus

Demais valores permanecem sem restrição de validação NT-007.

pisCofinsRetentionType

Agora calculado pelo sistema, não deve mais ser informado, mas ainda é retornado na API.

Catálogo de erros

Cronograma

FAQ

Sou Simples Nacional. Preciso mudar algo?

Não.

Posso continuar enviando pisCofinsRetentionType?

Idealmente não, pois o campo será apenas usado para conversões de retrocompatibilidade ou ignorado e recalculado pelo nosso backend.

Minhas notas antigas vão quebrar?

Não durante o período de migração.

Como testar antes da obrigatoriedade?

Envie:

{
  "useTaxSystemReformNT007": true
}

O XML enviado ao fisco muda?

Sim, para clientes Regime Normal.

Alterações principais:

• vPis e vCofins passam a refletir os valores de operação.
• vRetCSLL passa a representar a soma consolidada das retenções de PIS, COFINS e CSLL.

Suporte

Em caso de dúvidas ou problemas, acesse a Central de Ajuda ou entre em contato com o suporte.

🚧

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:

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)

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

23/10/2024

• Novos eventos de Webhook para bloqueio por divergência de split

23/10/2024

• Novos tipos de FinancialTransaction para bloqueio por divergência de split

21/10/2024

• TEDs após às 15h serão agendados para o próximo dia

20/09/2024

• Ação necessária: Atualização domínio API Asaas ⚠️
• Padronização do retorno de faturamento/renda mensal

16/09/2024

• Novo motivo de cancelamento nos objetos de split

30/08/2024

• Atualize os dados cadastrais de todas as suas contas até 30/08 para que elas não sejam bloqueadas

05/08/2024

• Bloqueio no envio de cpfCnpj inválido

02/07/2024

• Novo fluxo de eventos em boletos

14/06/2024

• Agora novas contas raiz são obrigadas a informar o User-Agent no header das requisições

29/05/2024

• Novo formato de data: yyyy-MM-dd nos retornos e Webhooks de Pagamento de Contas

30/05/2024

• ⚠️ Novo campo obrigatório de faturamento/renda mensal para todas as contas

15/04/2024

• Remoção do campo tradingName em dados comerciais das contas
• Mudança no formato do campo retornado via API e Webhooks

25/03/2024

• Inclusão de campo com ID do evento em envios de Webhooks

21/12/2023

• Mudança no formato de novos IDs gerados em Notificações de Cobrança

05/12/2023

• Mudança no formato de novos IDs gerados em cobranças, assinaturas, links de pagamento e links de estorno