Quando um ERP consulta a apuração da CBS, a resposta interessa a duas equipes. Quem mantém a integração precisa saber se todos os retornos chegaram e se foram gravados uma única vez. Quem fecha a apuração precisa explicar por que um valor apareceu, mudou ou deixou de estar disponível para uso. A migração das consultas de débitos e créditos para a versão 2.0 reúne essas duas responsabilidades.
A Receita Federal informou que liberou as consultas em 28 de outubro de 2026, em produção restrita e em produção beta. O comunicado também informa que quem já tem chaves deve cancelá-las e gerar novas para usar as APIs. Para organizar a mudança, vale separar três decisões: como renovar o acesso, como registrar cada consulta e como reconciliar os dados antes de liberar o resultado para o fiscal.
O artigo sobre webhook e download assíncrono no ERP descreve o transporte dos retornos. Aqui, a pergunta começa depois que a integração tem acesso ao serviço: como demonstrar que a migração trouxe os dados esperados, preservou o histórico e deixou um caminho de recuperação para quando uma consulta falhar?
Renove o acesso com uma janela de mudança
Comece com um inventário. Identifique quais serviços usam a credencial atual, em qual ambiente, para quais contribuintes e sob qual responsabilidade. Uma mesma credencial pode estar referenciada em tarefas diferentes dentro do seu ambiente. Se o cancelamento ocorrer antes dessa verificação, uma rotina que você nem lembrava de incluir na mudança pode parar no próximo processamento.
A Receita orienta obter a chave no serviço Gerar Credencial de Acesso, disponível no portal de Serviços da Receita Federal ou no portal Tributação sobre Consumo. Confirme também a representação do contribuinte quando o acesso depender de procurador digital. A existência de uma chave guardada no ERP não comprova que ela autoriza uma consulta para qualquer empresa cadastrada.
Combine uma janela de mudança com a equipe fiscal. Registre a última consulta concluída de débitos e a de créditos, verifique solicitações pendentes e prepare o cadastro da nova credencial no cofre usado pelo aplicativo. Durante o corte, pause as rotinas que dependem da chave a cancelar, aplique a orientação da Receita e teste as novas consultas antes de retomar a execução periódica. Uma reversão no código pode ser útil, mas não deve pressupor que a chave cancelada voltará a funcionar.
Separe configuração de produção restrita e produção beta. No ERP, uma configuração deve carregar o ambiente, a empresa representada e a referência para o segredo, sem gravar a chave em relatórios ou mensagens de erro. Se uma empresa estiver configurada no ambiente errado, um retorno tecnicamente válido ainda será inadequado para a conferência do fechamento.
Trate o retorno incremental como atualização de estado
A documentação de débitos explica que a consulta traz inclusões e atualizações. Para quem tem consulta concluída nos últimos três meses, a janela usa a solicitação concluída mais recente e se limita aos últimos oito dias. Na ausência de consulta concluída nesse período, a busca começa no primeiro dia do mês corrente. Confirme também as regras de créditos para a operação que o ERP efetivamente executar.
O ponto de engenharia é que a janela do serviço não equivale a um histórico completo que o cliente pode pedir novamente a qualquer momento. Se o ERP ficar parado, voltar a chamar o serviço resolve a conectividade, mas pode deixar uma lacuna no acervo local. Registre o último retorno processado, preserve os comprovantes de execução e trate lacunas como pendências de conciliação. Uma consulta vazia é um resultado daquela janela. Ela não autoriza apagar valores anteriormente registrados.
Mantenha um controle separado para débitos e créditos. Para cada solicitação, guarde o ambiente, o contribuinte, a operação, o tíquete, o horário de processamento e o resultado da importação. Em um segundo nível, registre os itens fiscais importados e seus vínculos com o documento de referência e a origem. Assim, é possível repetir o processamento do mesmo arquivo sem abrir outra solicitação apenas para reparar uma gravação local.
Na camada de persistência, aplique os retornos de forma idempotente. Isso significa que importar novamente o mesmo lote deve produzir o mesmo estado final. Defina a identidade de cada registro a partir dos identificadores documentados e verifique seu escopo antes de criar a chave do banco. Evite usar só o número da nota, que pode aparecer em séries, estabelecimentos e situações distintas. Também evite somar o valor recebido ao saldo anterior sem confirmar se o serviço retornou um novo lançamento ou a atualização de um lançamento existente.
Distinga valores do tributo e estados da apuração
A consulta de débitos oferece elementos de rastreabilidade, como a origem e o documento fiscal de referência. O comunicado da Receita também menciona valores em estados como suspenso, extinto e devedor. Na tela de conferência, preserve essas distinções. Um número agregado pode até servir como resumo, desde que a equipe consiga abrir os itens e entender como aquele total foi obtido.
Em créditos, preserve as parcelas e os estados descritos na documentação. O valor apurado ajuda a explicar a origem do crédito. O que já foi apropriado, o que ainda está a apropriar e o que foi utilizado respondem a perguntas diferentes sobre seu uso. Um cadastro que guarda apenas um campo chamado saldo perde essa separação e torna difícil explicar uma diferença quando o fiscal compara o ERP com a Receita.
Uma prática útil é guardar o retorno original em armazenamento de acesso restrito, separado da visão que a equipe usa no fechamento. A visão pode evoluir com o produto. A evidência original ajuda a reconstruir por que o ERP apresentou determinado valor. Trate o arquivo como documento fiscal de acesso controlado: estabeleça permissões, prazo de retenção e um procedimento de consulta. Um log técnico aberto a toda a equipe não é o lugar adequado para esse material.
Aplicação prática
Roteiro de conferência elaborado para este artigo.
Imagine um débito fictício registrado inicialmente com valor devedor de R$ 100. Em um retorno posterior, o mesmo registro passa a mostrar R$ 60 devedor e R$ 40 extinto. A pergunta do teste é se o ERP atualizou o estado daquele débito e conservou a evidência de ambas as leituras. Se o relatório passa a mostrar R$ 160 devedor, provavelmente o sistema tratou uma atualização como um segundo lançamento. Se ele mantém os R$ 100 anteriores, a importação pode ter ignorado a mudança.
Faça o mesmo exercício com um crédito fictício que passa de um estado a outro. Verifique se a atualização aparece na competência esperada e se pode ser associada ao mesmo registro fiscal. Adicione um cenário em que o arquivo seja recebido duas vezes e outro em que a gravação falhe no meio. No segundo caso, confirme se o reprocessamento corrige a importação sem multiplicar os itens que já entraram. Esses testes podem ser construídos com dados sintéticos e não dependem de reproduzir uma operação fiscal real.
Antes de liberar a integração, execute uma conferência por amostragem em ambiente de teste. Compare itens individualmente, agrupe por competência e examine as diferenças entre o estado atual do ERP e o retorno consultado. Registre também o instante da comparação. Uma comparação feita antes de o documento entrar no processamento da apuração pode produzir uma divergência aparente que desaparece quando ambos os sistemas estão na mesma referência temporal.
Em produção beta, limite a primeira execução a contribuintes e rotinas que a equipe consegue acompanhar. Para cada divergência, registre a natureza do problema: credencial, acesso, solicitação, download, gravação, identificação do item ou interpretação fiscal. Essa classificação reduz o tempo de diagnóstico. Uma chave inválida exige uma resposta diferente de um arquivo duplicado, mesmo quando ambos os problemas aparecem para o usuário como ausência de dados.
Defina quem responde por cada pendência. Desenvolvimento verifica a entrega e a persistência. Fiscal verifica se o item e o estado correspondem à apuração esperada. Operação confirma a janela de execução e mantém o histórico de incidentes. O aceite deve reunir essas três perspectivas, com evidências suficientes para que outra pessoa consiga repetir a conferência.
Planeje a recuperação antes do primeiro incidente
Faça uma simulação em que a integração fica indisponível durante um feriado prolongado. Peça à equipe que localize a última solicitação processada, identifique a janela coberta pelo próximo retorno e aponte o intervalo que precisa de conferência. A simulação deve terminar com uma lista de ações e responsáveis, e não apenas com a confirmação de que a aplicação voltou a responder.
Também vale conferir o efeito de um retorno processado fora de ordem. A fila de download pode terminar uma tarefa antiga depois de uma recente. Defina como o ERP reconhece a ordem das evidências antes de substituir um estado já conciliado. Quando houver dúvida, preserve ambos os registros e encaminhe a diferença para análise. Essa é uma proteção do sistema cliente, que precisa ser testada com os campos e as garantias da documentação oficial.
Conclusão
A migração para as APIs 2.0 é uma oportunidade para tornar a apuração rastreável. Prepare a renovação da credencial, separe os ambientes e valide a leitura incremental como uma mudança de estado dos registros. Comece com um conjunto pequeno de casos e preserve evidências que expliquem cada divergência. O resultado esperado é um ERP que consegue mostrar de onde veio o dado, qual versão processou e por que o valor exibido está pronto para conferência.
Referências
BRASIL. Receita Federal. Receita Federal libera acesso às novas APIs de apuração da CBS. 9 nov. 2026. Disponível em: https://www.gov.br/receitafederal/pt-br/assuntos/noticias/2026/novembro/receita-federal-libera-acesso-as-novas-apis-de-apuracao-da-cbs. Acesso em: 10 nov. 2026.
BRASIL. Receita Federal. Consultar débitos em operações de consumo. [s. d.]. Disponível em: https://docs.receitafederal.gov.br/apuracao-cbs/debito.html. Acesso em: 10 nov. 2026.
BRASIL. Receita Federal. Consultar créditos em operações de consumo. [s. d.]. Disponível em: https://docs.receitafederal.gov.br/apuracao-cbs/credito.html. Acesso em: 10 nov. 2026.
SILVEIRA, Régys Borges da. APIs da CBS: como adaptar webhook e download assíncrono no seu ERP. 24 out. 2026. Disponível em: https://regys.com.br/apis-cbs-webhook-download-assincrono-erp/. Acesso em: 10 nov. 2026.
0 comentário(s)