APIs do IBS e da CBS: por que integrar não é o mesmo que controlar

Para validar a Apuração Assistida, a empresa precisa antes receber os dados do Fisco de forma íntegra. E aí começa a dificuldade: CBS e IBS chegam por APIs diferentes, com lógicas diferentes.

Uma integração feita para a CBS, adaptada ao IBS trocando apenas os nomes dos campos, produz erro de cálculo e duplicidade.

Este artigo mostra o que vem em cada API, onde estão as diferenças e quais os riscos de quem trata essa integração como mais uma conexão genérica.

APIs do IBS: uma conta corrente que se constrói evento a evento

No IBS, a unidade central é a operação: um fornecimento, visto pelo fornecedor, ou uma aquisição, vista pelo adquirente. Cada operação funciona como uma conta corrente fiscal com ciclo de vida próprio.

O primeiro lançamento registra a operação. Depois vêm apropriação, utilização, pagamento, cancelamento, devolução e extinção, cada um como um novo lançamento. Lançamentos publicados não são alterados nem excluídos: correções chegam como eventos novos.

Cada lançamento traz efeitos positivos ou negativos em sete campos financeiros:

• débito em aberto e débito extinto;
• crédito a apropriar, crédito não utilizado e crédito utilizado;
• recurso financeiro a transferir e recurso disponível para transferência.

Os dados chegam em arquivos. O delta é gerado automaticamente após o processamento diário, com os eventos daquele ciclo. O arquivo manual traz os lançamentos de um período pedido, sempre dentro de uma única competência. Os dois têm o mesmo layout, e o extrato de uma operação pode vir dividido em vários arquivos.

A consequência é direta: um arquivo é um recorte, não um saldo. O saldo só existe se a empresa acumular todo o histórico, sem perder nem repetir nenhum lançamento. E a ausência de uma operação num arquivo não significa que ela foi cancelada ou zerada.

O fluxo começa com credenciais geradas no portal e o cadastro de um webhook HTTPS. O CGIBS avisa pelo webhook que há arquivos disponíveis, e o sistema da empresa precisa buscá-los e processá-los. O aviso não traz os dados fiscais.

API da CBS: consultas por serviço, acompanhadas por tíquete

Na CBS, a lógica é outra. Em vez de receber deltas diários, a empresa abre consultas específicas à Receita Federal, separadas por família: débitos, créditos, pagamentos e recolhimentos como adquirente.

A autenticação usa OAuth2. Cada consulta é aberta com um POST que retorna um tíquete, sem o arquivo. Quando o processamento termina, a Receita avisa pelo endereço de retorno informado, ou a empresa consulta a situação pelo tíquete. O download sai de uma URL assinada que vale 48 horas.

O conteúdo também é organizado de outro jeito. Os débitos trazem valor apurado, saldo devedor e situações como suspenso e inexigível. Os créditos separam apropriação e utilização, com pedido de ressarcimento. Pagamentos e recolhimentos têm estruturas próprias, com composição por DARF, split payment e recolhimento pelo adquirente.

E a semântica muda: os registros da CBS podem vir incluídos ou atualizados. Se a empresa somar tudo o que recebe, como faria no IBS, conta duas vezes o mesmo valor.

APIs do IBS e da CBS lado a lado

Os termos parecem iguais, mas quase nada se reaproveita sem adaptação.

A conclusão técnica é que fila, auditoria e armazenamento podem ser comuns. Autenticação, agendamento, recuperação e interpretação financeira precisam ser próprios de cada tributo.

Onde uma integração genérica falha

Cada diferença entre as APIs vira um risco financeiro quando é ignorada.

Há também o risco silencioso. Se o webhook do IBS não avisar, pode ser falha de entrega ou simplesmente um dia sem eventos. Sem controle de cobertura, a empresa não sabe qual dos dois aconteceu.

E a recuperação tem regra própria. Se um arquivo vier corrompido, a orientação do CGIBS é pedir o período de novo e trocar o conjunto inteiro, não só o arquivo com problema. Sem esse controle, a empresa duplica lançamentos ou mantém duas cargas ativas.

Em escala, esses erros não aparecem numa conferência por amostragem. Grandes empresas processam centenas de milhares de documentos por dia: um erro de 0,1% já significa centenas de documentos divergentes.

Um contrato que ainda está mudando

A versão 1.10 do manual da API do IBS, publicada em setembro de 2026, é a primeira oficial. Ela previa o teste da etapa 1 em homologação a partir de 28/09/2026 e deixava as etapas 2 a 4 para o futuro, sem data.

O próprio manual lista pendências. A regra de cálculo do hash do extrato não está definida, e a tabela de códigos de movimentação ainda vai ser publicada. Desenvolvedores também apontam divergências entre as tabelas e os exemplos do manual.

Por isso, a integração com as APIs da Apuração Assistida não é um projeto que se entrega uma vez. Cada nova versão pode mudar layout, rotas e regras, e alguém precisa acompanhar isso de perto.

Decision RT: da apuração oficial à decisão

Receber os dados é só o começo. Para validar a apuração do governo, a empresa precisa cruzar o que o Fisco calculou com os documentos que ela mesma emitiu e recebeu. Foi para isso que o Decision RT foi criado.

A plataforma importa os documentos fiscais da empresa e consulta a Apuração Assistida de CBS e IBS. Em seguida, cruza as duas bases automaticamente e mostra onde estão as diferenças:

• documentos que o Fisco não considerou ou que a empresa desconhece;
• diferenças de valores, de débitos, de créditos e de tributação;
• a origem de cada inconsistência e seu possível impacto financeiro.

Quando a divergência exige ajuste, o Decision RT reúne os documentos e as informações que fundamentam a correção, com rastreabilidade de todo o processo.

A solução também olha para a cadeia. No novo modelo, o aproveitamento de alguns créditos pode depender da extinção do débito na etapa anterior. O Decision RT identifica fornecedores com tributos pendentes, créditos bloqueados e parceiros de maior risco, para que a empresa aja antes de perder o crédito.

Por fim, a plataforma se integra ao ERP, aos repositórios de XML e aos sistemas fiscais e contábeis, e realiza a contabilização no ERP. Ela não substitui o ERP, o sistema fiscal nem a equipe: automatiza coleta, cruzamento e identificação das diferenças, e deixa para a equipe fiscal a análise e a decisão.

O governo realiza a apuração. O Decision RT dá à empresa as ferramentas para controlá-la.

Comece a integrar antes de 2027

Ainda em outubro, as etapas 2 a 4 da API do IBS  não têm data, e o contrato muda a cada versão do manual. Cada mudança é um ponto em que a integração pode quebrar sem aviso.

Quem começar a integrar só quando o IBS passar a ser cobrado, em 2027, vai descobrir essas falhas com tributo a pagar e crédito em jogo. Quem começar agora tem tempo para testar recepção, recuperação e conciliação com dados reais.

As primeiras apresentações do Decision RT são consultivas e voltadas a um grupo limitado de grandes empresas.