A Receita Federal publicou, em setembro de 2026, uma nova documentação técnica para as interfaces de programação de aplicações, as APIs, ligadas à apuração da Contribuição sobre Bens e Serviços (CBS). A notícia chama atenção pelos serviços de consulta a débitos, créditos, pagamentos e recolhimentos, mas a mudança mais importante para quem desenvolve ERP está na forma de integração: os dados serão entregues de maneira assíncrona e incremental, em arquivos gerados após a solicitação, e não como uma resposta completa e imediata a cada chamada.

Essa diferença parece pequena até imaginarmos a rotina de uma empresa com milhares de documentos fiscais. O ERP precisa solicitar o processamento, guardar um tíquete, receber ou recuperar o resultado, baixar um arquivo temporário, importar apenas as alterações e preservar evidências para conciliação. Neste artigo, vou explicar o que a Receita disponibilizou, como o fluxo técnico funciona e quais decisões de arquitetura evitam perda de dados, duplicidade e exposição de credenciais. O objetivo não é fornecer um conector pronto, porque credenciais e ambientes dependem do enquadramento de cada contribuinte, mas transformar a documentação oficial em um plano de implementação verificável.

O que foi anunciado e por que isso importa

Segundo a notícia oficial da Receita Federal sobre as APIs da CBS, as consultas de débitos e créditos estão previstas para o início de outubro de 2026; pagamentos e recolhimentos como adquirente, para o início de novembro; e a emissão de DARF para recolhimento como adquirente (RAD) e pagamento do próprio contribuinte (PCONT), para o fim de novembro. A disponibilização ocorrerá nos ambientes de produção restrita, ligado ao piloto, e de produção beta. Portanto, o cronograma deve orientar testes e preparação, não ser interpretado como garantia de estabilidade definitiva de todos os contratos.

A novidade em relação à versão anterior é a consulta incremental. Em vez de baixar repetidamente todo o conjunto do período, o consumidor recebe as inclusões e atualizações ocorridas desde a consulta anterior. A documentação de débitos e a documentação de créditos registram uma janela máxima de oito dias, com uma exceção para a primeira consulta, que retorna as movimentações desde o primeiro dia do mês corrente. Na prática, isso reduz volume e tempo de processamento, mas transfere ao integrador a responsabilidade de manter uma rotina frequente, registrar o que foi importado e saber recuperar uma execução interrompida.

As APIs não substituem a emissão correta dos documentos fiscais nem a lógica interna de conferência. Elas oferecem uma visão legível por máquina do que chegou à apuração assistida. Para compreender o outro lado desse fluxo, vale consultar também o artigo sobre ACBrNFe e os campos IBS/CBS da NT 2025.002. Uma integração útil deve comparar a visão do ERP, formada por documentos emitidos e recebidos, com a visão processada pela administração tributária.

O fluxo assíncrono muda o desenho da integração

A regra comum das APIs assíncronas exige credenciais válidas para o estabelecimento matriz, token de acesso e um webhook HTTPS publicamente acessível. A autenticação usa OAuth 2.0 no fluxo Client Credentials: o sistema apresenta identificador e segredo da aplicação, recebe um token e o envia no cabeçalho Authorization. O CNPJ informado no caminho é a raiz com oito dígitos, o que também precisa ser considerado quando o ERP administra várias filiais.

Depois da autenticação, o fluxo pode ser entendido em seis etapas:

1. O integrador solicita a consulta de um recurso, como débitos ou créditos, e informa a URL HTTPS de retorno.
2. A API aceita a solicitação e devolve um tiqueteSolicitacao e uma estimativa de atendimento, sem trazer naquele momento o arquivo final.
3. O ERP persiste o tíquete e marca a execução como pendente. Essa gravação deve ocorrer antes de qualquer tentativa de acompanhamento.
4. Ao terminar o processamento, a Receita chama o webhook com o resultado; se a notificação não chegar, o cliente pode consultar o endpoint de situação da solicitação.
5. Em caso de sucesso, a resposta contém uma URL assinada e seu horário de expiração. O ERP baixa o JSON, valida o conteúdo e guarda uma cópia controlada ou evidência equivalente conforme sua política fiscal.
6. Somente depois de importar e conciliar o arquivo, a execução é marcada como concluída. Se houver falha entre download e gravação, o mesmo artefato deve poder ser reprocessado sem duplicar lançamentos.

Esse é um fluxo de mensageria, embora seja iniciado por HTTP. Tratar tudo como um botão “consultar agora” preso à tela cria uma aplicação frágil, porque o processamento pode levar tempo e a documentação estabelece limite de até quatro horas. O ideal é separar interface, agendador, cliente de autenticação, receptor do webhook, baixador de arquivos, importador e mecanismo de conciliação. Em sistemas Delphi, essa separação pode ser feita com serviços ou classes de domínio independentes do formulário, seguindo a mesma necessidade de desacoplamento discutida em como adaptar um ERP Delphi à Reforma Tributária.

Uma arquitetura mínima para o ERP

Antes de escrever o cliente HTTP, vale modelar o estado da integração. Uma tabela de controle pode registrar CNPJ raiz, tipo de consulta, tíquete, data da solicitação, estado, tentativas, data do arquivo, hash do conteúdo, resultado da importação e identificador de correlação. O token, o segredo e a URL assinada não devem fazer parte desse histórico. Para cada item fiscal importado, use uma chave natural estável, como período, origem, tipo e chave do documento, complementada pela data de atualização quando o contrato assim exigir.

Uma solicitação de débitos no ambiente restrito usa o método HTTP POST no caminho /apuracao-cbs-prr/v2/debitos/{cnpj}. O cliente envia o token OAuth no cabeçalho de autorização, informa que o conteúdo está em JSON e fornece no corpo a propriedade urlRetorno, com o endereço HTTPS do webhook. Essa descrição reproduz a estrutura pública documentada, mas não foi executada com credenciais reais. O exemplo completo de chamada pode ser consultado diretamente na documentação oficial da API de débitos, evitando que tokens sejam copiados para scripts ou históricos de terminal.

Uma resposta aceita usa HTTP 201 e informa o tíquete. O webhook posterior não deve confiar apenas na existência desse valor: procure-o na tabela de solicitações, confirme que pertence ao contribuinte e ao serviço esperados e recuse transições de estado incoerentes. Como a entrega de notificações pode se repetir, processe o evento de forma idempotente, isto é, uma segunda entrega do mesmo resultado não pode criar outro lote nem alterar indevidamente os saldos.

O arquivo de débitos inclui período de apuração, origem, tipo e chave do documento, datas de emissão, registro e atualização, além de valores como CBS apurada, extinta, suspensa, inexigível e saldo devedor. O retorno de créditos segue estrutura voltada aos créditos incluídos ou atualizados. Já a consulta de pagamentos abrange valores que extinguem débitos por pagamento do contribuinte, recolhimento do adquirente e split payment; a consulta de recolhimentos como adquirente cobre RAD e split payment. Esses conjuntos têm significados distintos e não devem ser comprimidos prematuramente em uma única tabela de “movimentos” sem rastreabilidade da origem.

Consulta incremental exige disciplina operacional

Em uma API incremental, “não veio nada” não significa necessariamente “não há movimento”. Pode significar que outra execução já avançou a referência mantida pelo serviço, que o arquivo expirou antes do download ou que a resposta foi baixada e não importada. Por isso, bloqueie consultas concorrentes do mesmo tipo para o mesmo CNPJ, mantenha o estado de cada lote e crie alertas para solicitações pendentes além do tempo esperado.

A documentação limita a abertura a quatro chamadas por dia e mantém o arquivo disponível pela URL assinada por 48 horas. Esses limites desaconselham repetição agressiva. Use o webhook como caminho principal e a consulta de situação como recuperação, com espera progressiva entre tentativas. Uma rotina diária pode ser suficiente em muitos cenários, mas a frequência correta deve considerar volume, prazo da área fiscal e futuras regras do ambiente utilizado.

Na importação, não some simplesmente todos os valores recebidos. Como o retorno inclui registros novos e atualizados, adote uma operação de inclusão ou atualização, conhecida como upsert, e guarde a última versão recebida junto do instante informado pela fonte. Depois, confronte o resultado com os documentos locais. Uma tela de conciliação útil deve mostrar documentos presentes nos dois lados com valores diferentes, documentos existentes somente no ERP, documentos existentes somente na apuração e alterações recebidas após uma conferência anterior.

Esse desenho é especialmente importante para devoluções, cancelamentos, suspensões e pagamentos, porque o saldo não é apenas a soma bruta da emissão. O artigo devoluções na era do IBS/CBS ajuda a entender por que a ligação entre o documento original e os eventos posteriores precisa permanecer íntegra.

Segurança e observabilidade sem vazar segredos

A URL assinada autoriza o download do arquivo durante sua validade de 48 horas e deve ser tratada como segredo temporário. A Receita orienta que ela não seja gravada em logs, mensagens de erro, métricas, histórico do navegador ou ferramentas de rastreamento. O mesmo cuidado vale para client_secret, token OAuth e dados pessoais. Registre apenas o necessário para auditoria: tíquete, horário, serviço, resultado, código de erro não sensível, hash do arquivo e identificador de correlação.

O webhook deve usar certificado TLS válido, rota dedicada, limitação de requisições e proteção contra repetição. Responda com HTTP 2xx somente depois de aceitar duravelmente a notificação; caso contrário, uma falha temporária pode ser confundida com entrega concluída. A verificação inicial por HEAD, mencionada na documentação, comprova apenas que a URL está acessível e não autentica o conteúdo recebido. Assim, a aplicação ainda precisa validar o tíquete e o contexto antes de iniciar qualquer download.

Também é prudente separar os endereços e as credenciais de produção restrita e produção. Nunca permita que uma simples configuração visual troque o ambiente sem trilha de auditoria. Dados do piloto não produzem efeitos fiscais, jurídicos ou cadastrais, conforme as perguntas frequentes do Piloto da CBS, mas essa ausência de efeito não autoriza práticas inseguras: o piloto é justamente o momento de testar renovação de credenciais, indisponibilidade, repetição de webhook, expiração do arquivo e recuperação de falhas.

Um roteiro prático de implementação

Uma software house pode começar sem esperar todos os serviços entrarem no ar. Primeiro, isole no ERP um módulo de integração com configuração por ambiente e por CNPJ raiz. Depois, implemente o armazenamento de solicitações e uma máquina de estados simples: criada, aceita, processando, disponível, importada, conciliada ou com erro. Em seguida, construa o webhook e teste sua disponibilidade externa sem expor funções administrativas na mesma rota.

Com essa base, implemente um único recurso, preferencialmente débitos, e valide o ciclo completo com dados controlados. Simule notificações repetidas, token expirado, JSON inválido, URL já vencida, indisponibilidade do banco e reinício do serviço entre download e importação. Só então replique o padrão para créditos, pagamentos e recolhimentos, preservando modelos de domínio separados. Por fim, entregue à área fiscal uma conciliação compreensível, com filtros por período e documento e possibilidade de exportar divergências.

Não codifique listas de origem e tipos de documento como descrições espalhadas em telas. Centralize os códigos publicados, registre a versão do contrato e monitore alterações na documentação oficial da apuração da CBS. Como os documentos estavam na versão inicial em setembro de 2026 e o cronograma é progressivo, mudanças são esperadas. Testes de contrato, executados contra exemplos controlados, ajudam a identificar campos novos, cardinalidades diferentes e valores ainda desconhecidos sem derrubar toda a importação.

Limitações que precisam ficar claras

Este desenho se baseia na documentação disponível em 17 de setembro de 2026. Ele não substitui o manual de credenciais do Receita Integra, a validação jurídica das regras da CBS nem os testes no ambiente autorizado para cada empresa. Também não é correto concluir que todos os contribuintes já podem consumir todos os endpoints: o anúncio apresenta datas futuras e distingue produção restrita de produção beta.

A matéria do Portal Contábeis que motivou este artigo resume o anúncio, mas os detalhes de segurança, limites e formato foram conferidos nas fontes primárias da Receita. Essa distinção é importante porque uma notícia indica a direção; o contrato técnico oficial determina como o software deve se comportar. Antes de implantar, confira a versão das páginas e mantenha uma decisão explícita sobre retenção dos arquivos, acesso dos usuários e evidências necessárias à fiscalização.

Conclusão

As novas APIs da CBS aproximam a apuração assistida dos sistemas empresariais, mas não oferecem apenas mais alguns endpoints REST. Elas estabelecem um processo assíncrono, incremental e orientado a conciliação. O ganho de eficiência prometido pela redução do volume só aparece quando o ERP controla o ciclo completo: solicitação, tíquete, webhook, download, importação idempotente, atualização de registros e confronto com os documentos internos.

Para desenvolvedores e profissionais contábeis, a implicação prática mais importante é começar pelo modelo operacional, não pela chamada HTTP. Um conector que baixa JSON sem controlar estado pode produzir uma falsa sensação de integração. Um módulo que preserva origem, histórico, segurança e divergências transforma os dados da Receita em informação realmente útil para conferir a apuração. O piloto e a produção beta devem ser usados para provar esse comportamento enquanto os contratos evoluem, antes que a rotina passe a carregar consequências fiscais efetivas.

Referências

BRASIL. Lei Complementar nº 214, de 16 de janeiro de 2025. Brasília, DF: Presidência da República, 2025. Disponível em: https://www.planalto.gov.br/ccivil_03/leis/lcp/lcp214.htm. Acesso em: 17 set. 2026.

PORTAL CONTÁBEIS. Receita publica APIs para apuração da CBS. Portal Contábeis, 15 set. 2026. Disponível em: https://www.contabeis.com.br/noticias/79409/receita-publica-apis-para-apuracao-da-cbs/. Acesso em: 17 set. 2026.

RECEITA FEDERAL DO BRASIL. Consultar créditos em operações de consumo (CBS). Documentação da apuração CBS, 3 set. 2026. Disponível em: https://docs.receitafederal.gov.br/apuracao-cbs/credito.html. Acesso em: 17 set. 2026.

RECEITA FEDERAL DO BRASIL. Consultar débitos em operações de consumo (CBS). Documentação da apuração CBS, 3 set. 2026. Disponível em: https://docs.receitafederal.gov.br/apuracao-cbs/debito.html. Acesso em: 17 set. 2026.

RECEITA FEDERAL DO BRASIL. Consultar pagamentos de CBS. Documentação da apuração CBS, 3 set. 2026. Disponível em: https://docs.receitafederal.gov.br/apuracao-cbs/pagamentos.html. Acesso em: 17 set. 2026.

RECEITA FEDERAL DO BRASIL. Consultar recolhimentos de CBS como adquirente. Documentação da apuração CBS, 17 set. 2026. Disponível em: https://docs.receitafederal.gov.br/apuracao-cbs/recolhimentos.html. Acesso em: 17 set. 2026.

RECEITA FEDERAL DO BRASIL. Consultar situação da solicitação. Documentação da apuração CBS, 3 set. 2026. Disponível em: https://docs.receitafederal.gov.br/apuracao-cbs/situacao-solicitacao.html. Acesso em: 17 set. 2026.

RECEITA FEDERAL DO BRASIL. Piloto da Reforma Tributária do Consumo. Brasília, DF, 24 jun. 2025. Atualizado em: 29 jul. 2025. Disponível em: https://www.gov.br/receitafederal/pt-br/acesso-a-informacao/perguntas-frequentes/piloto-da-reforma-tributaria-do-consumo. Acesso em: 17 set. 2026.

RECEITA FEDERAL DO BRASIL. Receita Federal publica nova documentação técnica das APIs de apuração de CBS. Brasília, DF, 14 set. 2026. Disponível em: https://www.gov.br/receitafederal/pt-br/assuntos/noticias/2026/setembro/receita-federal-publica-nova-documentacao-tecnica-das-apis-de-apuracao-de-cbs. Acesso em: 17 set. 2026.

RECEITA FEDERAL DO BRASIL. Regras comuns de solicitação e retorno das APIs assíncronas. Documentação da apuração CBS, 3 set. 2026. Disponível em: https://docs.receitafederal.gov.br/apuracao-cbs/guiaapiassincrona.html. Acesso em: 17 set. 2026.