CBS: as APIs da apuração assistida passam à versão 2.0, com consulta incremental e credencial nova

Publicado em 10 de novembro de 2026 · conferido nas fontes oficiais em 10/11/2026

A Receita Federal liberou em 28/10/2026 a versão 2.0 das APIs de consulta da apuração da CBS: os débitos e os créditos que a Receita apura a partir dos documentos fiscais, os mesmos que o serviço "Minha Apuração Assistida" mostra no portal. A mudança está no modo de consultar: cada chamada devolve só o que entrou ou mudou desde a última consulta, a resposta não sai na hora: vem por arquivo, depois de um processamento que pode levar até 4 horas, e quem já tinha chave de acesso precisa cancelá-la e gerar outra. As APIs estão em produção restrita (testes) e em produção (beta), segundo a notícia da Receita de 09/11/2026.

O que mudou

A notícia de setembro diz por quê: as consultas incrementais reduzem o volume de cada resposta, o tempo de processamento e o tamanho dos arquivos. A Receita diz que atendeu a sugestões de profissionais da contabilidade, de empresas de software e de contribuintes com elevado volume de transações, e pede que as empresas de software e os contribuintes que integram seus sistemas consultem a documentação e planejem as adequações.

O que já está no ar e o que vem

A notícia de 09/11 diz que "novos serviços via API vinculados à apuração de CBS serão disponibilizados em novembro".

Como funciona a consulta

1. O sistema pede um token ao servidor de autenticação (OAuth 2.0, fluxo "client credentials"), com o client_id e o client_secret da credencial.
2. Chama a API (débitos, créditos, pagamentos ou recolhimentos) com POST, o token no cabeçalho Authorization: Bearer e o CNPJ base, de 8 dígitos, no endereço. A credencial é a do estabelecimento matriz.
3. No corpo vai a urlRetorno, o endereço de um webhook do contribuinte para receber o aviso de pronto. Ela é opcional: sem webhook, vai vazia ("").
4. A API responde HTTP 201 com o tiqueteSolicitacao e uma estimativa de tempo em segundos (-1 quando não há estimativa).
5. Quando o processamento termina, a Receita avisa no webhook (no sucesso, com o tíquete e a situação; no erro, só com o código e a mensagem do erro); sem ele, o sistema consulta a situação da solicitação pelo tíquete: PENDENTE, EM_PROCESSAMENTO, CONCLUIDA, ERRO ou EXPIRADA.
6. Com CONCLUIDA, o sistema pede o link de download e recebe a urlAssinada, um link temporário.
7. Baixa o arquivo com um GET direto na urlAssinada, sem o token e sem outros cabeçalhos. O arquivo é JSON, em UTF-8.

Se o webhook for informado, a Receita confere antes, com uma chamada HEAD, se ele responde; se não responder, a solicitação é recusada.

A janela: o que cada consulta devolve

• Com uma consulta concluída nos últimos 3 meses, a API devolve o que entrou ou mudou desde ela, limitado aos últimos 8 dias.
• Sem consulta concluída nos últimos 3 meses, a busca começa no 1º dia do mês corrente.

O exemplo é da própria Receita: uma consulta feita em 29/09/2026, às 10h, depois de uma concluída em 10/09/2026, devolve só as alterações de 22/09/2026, 0h, em diante. O que mudou entre 10 e 21/09 não volta nessa consulta, e a documentação não diz como recuperá-lo pela API. Pelo mesmo exemplo, a janela começa à 0h do sétimo dia antes da consulta.

Na nossa leitura da regra do mês corrente, uma consulta feita em novembro sem outra concluída nos 3 meses anteriores devolve o que entrou ou mudou de 01/11 em diante, e não desde a liberação da versão 2.0, em 28/10.

Os limites

O que vem no arquivo

• Débitos, por período de apuração: a origem do débito (a operação normal, devoluções, cancelamentos, perecimento no transporte, nota de crédito de multa e juros), o tipo e a chave do documento (NF-e, NFC-e, CT-e, NFS-e, NF3-e, NFCom, BP-e e outros), as datas de emissão, registro e atualização, e os valores de CBS: apurado, excedente (o que não foi processado por inconsistência com o documento vinculado), inexigível, suspenso (pela classificação tributária, o cClassTrib), pagamento antecipado, extinto e saldo devedor.
• Créditos: o valor apurado, a parte a apropriar e a apropriada, a utilizada para compensar débitos, o saldo credor e o que foi objeto de pedido de ressarcimento, além do inapropriável, do suspenso, do prescrito, do inutilizável e do restabelecido.
• Pagamentos e recolhimentos: por DARF, com o tipo (RAD ou PCONT) e a composição por período, vencimento, principal, multa, juros e total.

Nos débitos e nos créditos, fora o valor apurado e o saldo (devedor ou credor), os campos com valor zero não vêm no arquivo; nos créditos, os grupos de apropriação e de utilização vêm mesmo zerados. Sem nada na janela, a lista de apurações vem vazia.

O que fazer

1. Gere a credencial nova. O serviço é o "Gerar Credencial de Acesso para API", no portal de Serviços da Receita Federal ou no da Tributação sobre Consumo (consumo.tributos.gov.br), com a conta gov.br. Sem o e-CNPJ, quem gera precisa representar a empresa, como representante ou procurador. Quem já tem chave gerada cancela a antiga e gera outra.
2. Guarde a credencial e o token só no servidor (backend), num cofre de segredos, com acesso restrito e troca periódica da credencial, como recomenda o manual do Receita Integra.
3. Implemente o token com cache: POST no servidor do token da Receita, api.receitafederal.gov.br/token, reaproveitado durante a hora de validade. Com dois tokens por hora, pedir um a cada chamada esgota o limite.
4. Decida entre webhook e consulta da situação. Com webhook: HTTPS, uma rota só para isso, que responda ao HEAD e fique no ar durante todo o processamento; e, como camada adicional que a Receita recomenda, aceite o aviso só do IP de origem que ela publica para produção (189.9.61.23/32), por lista de permissão no firewall, no WAF ou no gateway. Para a produção restrita, a documentação não traz IP. O aviso da Receita não tem assinatura nem autenticação: na nossa leitura, trate-o como um sinal e confirme pela consulta da situação antes de baixar; o aviso de erro nem traz o tíquete. A consulta da situação é também a contingência que a Receita indica, caso o aviso não chegue.
5. Agende as consultas dentro das 4 aberturas por dia e por API, com uma consulta concluída no máximo a cada 7 dias: pelo exemplo da Receita, a consulta de 29/09 só volta até 22/09, 0h. Na nossa leitura, com folga, diariamente ou a cada poucos dias, porque o processamento pode levar horas e a janela conta da consulta concluída mais recente.
6. Baixe e guarde o arquivo na primeira vez. O link vale por tempo limitado (confira o urlAssinadaExpiraEm, quando vier), e a documentação lista o "download já realizado" entre os casos de arquivo indisponível. Não grave a urlAssinada nem o token em log.
7. Concilie com o sistema, na nossa leitura, pela chave do documento: os débitos contra os documentos emitidos e os créditos contra os documentos de que vieram, quando o crédito trouxer a chave (nele, ela é opcional). Valor excedente aponta inconsistência com o documento vinculado. Valor suspenso vem da classificação tributária (cClassTrib): num débito, vale conferir a classificação do item no cadastro do sistema, porque a nota é sua; num crédito, ela vem do documento do fornecedor.

O que este texto não cobre

• As APIs de emissão de DARF (RAD e PCONT), que a Receita prevê para o final de novembro e que ainda não estão na documentação.
• O endereço de testes (produção restrita) das consultas: a documentação dá o de produção e, para testes, só o do download. O manual do Receita Integra também só traz o servidor do token de produção.
• A tela do serviço "Gerar Credencial de Acesso" e as procurações que ele aceita.
• O efeito jurídico da apuração assistida e as regras da CBS de 2026 na Lei Complementar 214/2025.
• O IBS: as APIs desta página são as da CBS, da Receita Federal.

Fontes oficiais

• Receita Federal, notícia de 09/11/2026
• Receita Federal, notícia de 14/09/2026, com o cronograma
• Documentação técnica das APIs da apuração da CBS
• Documentação técnica, regras comuns das APIs assíncronas
• Documentação técnica, dúvidas frequentes
• Documentação técnica, consultar débitos
• Documentação técnica, consultar créditos
• Documentação técnica, consultar pagamentos
• Documentação técnica, consultar recolhimentos
• Documentação técnica, situação da solicitação
• Documentação técnica, link para download
• Receita Integra, Documentação Técnica v1.4 (Serpro), em Documentos › Técnicos › Receita Integra

Precisa ajustar o cadastro fiscal, o ERP ou o SPED para essa mudança? Fale com a Knisstech.