Credencial das APIs da CBS: o Que o Escritório Contábil Deve Controlar

Por Equipe Técnica da Diversa TecnologiaPublicado em 16/11/2026

Revisão técnica: Hugo Ramos, fundador da Diversa Tecnologia

Mesa de escritório contábil à noite com monitor exibindo painéis de dados desfocados, pastas organizadas e um pequeno servidor ao fundo, em tons de azul-marinho

A Receita Federal orientou quem já tem credenciais de acesso às APIs da CBS a gerar uma nova credencial para consultar débitos e créditos do tributo. Segundo o Portal Contábeis, a atualização foi publicada em 28 de outubro, vale para a versão 2.0 das interfaces nos ambientes de Produção Restrita e Produção Beta e exige que a credencial anterior seja cancelada antes da emissão da nova.

À primeira vista, é um passo administrativo. Para o escritório contábil, porém, é a primeira troca de um tipo de acesso que ainda não tinha lugar definido na rotina: uma credencial técnica, usada por sistemas e não por pessoas, que dá acesso a dados fiscais de clientes. Este artigo trata do que controlar nessa credencial agora que ela precisou ser trocada pela primeira vez.

O que a Receita mudou nas APIs da CBS

De acordo com a matéria, a versão 2.0 permite consultar os débitos de CBS, com origem, documento fiscal relacionado, datas, valores e situação, e os créditos, com as parcelas apropriadas, a apropriar, utilizadas e não utilizadas. Os dados seguem a mesma base da ferramenta Minha Apuração Assistida, e a geração da nova credencial é feita pelos canais "Serviços da Receita Federal" e "Tributação sobre Consumo (Beta)".

A documentação da apuração CBS detalha o funcionamento técnico. Para consumir as APIs assíncronas, é preciso ter credenciais válidas para o estabelecimento matriz e obter um token pela API de autenticação. A partir daí, o sistema abre uma solicitação, aguarda o processamento e recupera o arquivo de retorno por um endereço temporário.

O cronograma citado pela Receita também prevê funcionalidades de pagamentos e de documentos de arrecadação para novembro, sem que isso signifique que já estejam disponíveis. Ou seja, novas trocas e ajustes de integração são esperados.

Por que essa credencial é diferente do certificado digital

O escritório contábil já está acostumado a cuidar de certificados digitais A1 e A3. A credencial das APIs se parece com eles em importância, mas não em forma de uso.

A documentação descreve o fluxo OAuth2 do tipo client credentials: o sistema apresenta a credencial, recebe um token e usa esse token nas chamadas. Ninguém digita nada. A credencial costuma ficar gravada em um arquivo de configuração, em um banco de dados ou em um painel do sistema fiscal, e é justamente por isso que tende a ser esquecida.

Dois detalhes do retorno mostram por que ela merece controle próprio. O arquivo de débitos registra, no campo niConsumidor, a inscrição de quem detém a credencial, ou seja, quem consumiu o serviço (Receita Federal). E, quando quem consulta não está autorizado para aquele contribuinte, a API responde com o erro "consumidor não autorizado para este NI". A credencial, portanto, identifica o escritório perante a Receita e define o que ele pode consultar.

O cuidado é o mesmo que tratamos no inventário de certificados digitais: saber o que existe, onde está, quem usa e quando vence ou precisa ser trocado.

Onde a credencial costuma ficar exposta

Credenciais técnicas raramente vazam por um ataque sofisticado. Elas aparecem em lugares onde ninguém esperava encontrá-las. Os pontos mais comuns em um escritório são:

  • planilhas e documentos de configuração compartilhados em pastas de rede ou no e-mail;
  • mensagens trocadas com o fornecedor do sistema durante a implantação;
  • arquivos de configuração copiados de um servidor para outro sem controle;
  • scripts próprios, feitos por alguém da equipe, com a credencial escrita no código;
  • registros de erro (logs) que gravam a requisição completa, inclusive o token.

O risco de credenciais esquecidas em código e arquivos foi tema do nosso artigo sobre segredos expostos em código. A lógica vale para o escritório contábil: o que não está inventariado não é trocado, e o que não é trocado continua válido para quem o encontrar.

Troca de credencial: como organizar sem interromper a rotina

A orientação da Receita de cancelar a credencial anterior para emitir a nova cria uma janela em que as integrações antigas deixam de funcionar. Se o escritório não sabe quais sistemas usam a credencial, descobre pela falha.

Um roteiro simples para essa e para as próximas trocas:

  1. Listar os consumidores. Identifique quais sistemas, conectores e rotinas usam a credencial atual, incluindo os do fornecedor do sistema contábil ou fiscal.
  2. Combinar a janela com o fornecedor. Defina quando a credencial antiga será cancelada e quem atualiza cada configuração logo em seguida.
  3. Testar fora da produção. Use os ambientes de Produção Restrita e Produção Beta para validar a nova credencial antes de depender dela.
  4. Registrar a troca. Anote data, responsável, sistemas atualizados e o resultado do primeiro teste.
  5. Apagar as cópias antigas. Remova a credencial cancelada de planilhas, mensagens e arquivos onde ela tenha sido guardada.

A janela de 8 dias e o limite de consultas

Dois limites da documentação têm efeito direto na rotina. O primeiro é a cota: até 4 chamadas por dia por credencial e por API, reiniciada à meia-noite (Receita Federal). Um sistema mal configurado, que repete chamadas com erro, pode esgotar a cota do dia antes de a equipe perceber.

O segundo é o recorte do retorno. Se houver consulta concluída nos últimos 3 meses, a API devolve as inclusões e atualizações desde a última consulta concluída sem erro, limitadas aos últimos 8 dias. O exemplo da própria Receita mostra uma consulta feita 19 dias depois da anterior trazendo apenas as alterações dos 8 dias mais recentes.

Na prática, a consulta incremental precisa rodar com regularidade, e alguém precisa saber quando ela falhou. Uma credencial cancelada sem que a integração seja atualizada, por exemplo, pode passar dias sem chamar atenção. O monitoramento dessas rotinas é o mesmo tipo de acompanhamento contínuo que oferecemos em serviços gerenciados de TI.

Webhook, arquivo temporário e registros de erro

A documentação permite informar uma URL de retorno (webhook) para receber o aviso de conclusão. Ela também deixa claro que essa notificação não usa autenticação adicional, assinatura digital nem cabeçalho específico de origem. As recomendações de segurança publicadas pela Receita incluem:

  • usar HTTPS no webhook, sem desabilitar a validação do certificado;
  • manter uma rota dedicada ao recebimento, sem outras funções administrativas no mesmo endereço;
  • restringir o recebimento às faixas oficiais de IP de origem, com regra no firewall ou no gateway;
  • tratar o endereço temporário do arquivo como segredo, já que ele dá acesso ao conteúdo por até 48 horas;
  • mascarar tokens, credenciais, endereços temporários e dados pessoais nos registros de erro;
  • usar a consulta de situação como contingência, caso a notificação não chegue.

Se o escritório não expõe nenhum serviço próprio na internet, a opção sem webhook, com consulta periódica de situação, é aceita pela documentação e reduz a superfície a proteger. A escolha deve ser feita com o fornecedor do sistema, não por padrão.

Checklist de controle para o escritório

Para quem já conta com suporte de TI para contadores, a lista abaixo funciona como pauta da próxima reunião com o fornecedor. Para quem mantém equipe interna, serve como ponto de partida.

  • Credencial registrada em inventário, com titular, sistemas que a usam e data da última troca.
  • Credencial guardada em cofre de senhas ou no repositório seguro do sistema, nunca em planilha ou mensagem.
  • Acesso restrito a quem administra as integrações, com contas nominais e autenticação multifator.
  • Roteiro de troca combinado com o fornecedor, testado fora da produção.
  • Alerta quando a consulta incremental falhar ou não rodar no dia previsto.
  • Registros de erro revisados para garantir que tokens e credenciais não sejam gravados.
  • Regras de firewall definidas, caso o escritório use webhook.

Esse controle complementa a preparação descrita em apuração de CBS: o que a TI do escritório contábil precisa preparar e a guarda de arquivos tratada em saldos credores na virada da CBS.

Como a Diversa apoia escritórios contábeis

O suporte de TI para contadores da Diversa Tecnologia parte da rotina do escritório: obrigações acessórias, certificados digitais, integrações com sistemas fiscais, base de dados e sigilo das informações de clientes. O escopo completo está na página de TI para contabilidade.

Nos contratos de serviços gerenciados, o trabalho inclui monitoramento contínuo, gestão de acessos, backup verificado e apoio em projetos de consultoria em segurança da informação, com SLA de 99,8% de disponibilidade e primeira resposta humana em menos de 30 minutos para incidentes críticos. A empresa atua há mais de 20 anos e acompanha mais de 2.500 dispositivos.

Conclusão

A nova credencial das APIs da CBS é uma troca pequena com uma lição maior: o escritório contábil passou a ter credenciais técnicas que falam com a Receita em nome dele e dos clientes. Elas precisam de dono, de lugar seguro, de roteiro de troca e de monitoramento.

Se o escritório ainda não sabe quais sistemas usam essa credencial ou onde ela está guardada, vale levantar isso antes das próximas funcionalidades previstas no cronograma. Fale com a equipe da Diversa para revisar o ambiente.

Perguntas frequentes sobre a credencial das APIs da CBS

Segundo a orientação divulgada, a nova credencial é necessária para acessar as funcionalidades de consulta de débitos e créditos da versão 2.0 das APIs, nos ambientes de Produção Restrita e Produção Beta. A credencial anterior precisa ser cancelada para que a nova seja gerada.

Não. São controles diferentes. O certificado digital continua sendo usado nas obrigações e nos portais. A credencial das APIs é usada por sistemas, no fluxo OAuth2 descrito na documentação da Receita, para obter o token que autoriza as consultas.

De acordo com a documentação, quando há consulta concluída nos últimos 3 meses, o retorno traz as alterações desde a última consulta concluída sem erro, limitadas aos últimos 8 dias. Por isso a rotina precisa rodar com regularidade e ter alerta de falha.

A documentação informa até 4 chamadas por dia por credencial e por API, com a cota reiniciada à meia-noite. Uma integração que repete chamadas com erro pode esgotar a cota do dia.

Quem administra as integrações, com conta nominal e autenticação multifator, e em um cofre de senhas ou repositório seguro do sistema. A credencial não deve circular em planilhas, mensagens ou arquivos de configuração copiados sem controle.

Diagnóstico de TI para Escritórios Contábeis

Revisamos credenciais, integrações, certificados e backup do seu escritório e indicamos o que precisa de atenção antes das próximas etapas da CBS.

Solicitar diagnóstico gratuito

Artigos relacionados

Sobre o autor

Equipe Técnica da Diversa Tecnologia

Time de engenharia, suporte e segurança da informação

Time multidisciplinar da Diversa Tecnologia responsável por infraestrutura, suporte, cloud, backup e segurança da informação em ambientes corporativos. Todo conteúdo publicado passa por revisão técnica interna antes da publicação.