Ir para o conteúdo

Calculadora de Tributos da Receita no GitHub: como integrar IBS e CBS ao ERP

Receita Federal liberou três projetos no GitHub. Entenda APIs locais para o regime regular, Simples Nacional e DANFSe e um roteiro para integrar ao ERP com segurança.

Notebook exibindo código sobre mesa de madeira, com plantas ao redor; imagem ilustrativa de desenvolvimento de software.

A Receita Federal publicou em 16 de novembro de 2026 os repositórios da sua Calculadora de Tributos no GitHub, sob licença MIT. Para quem desenvolve ERP, emissor de nota fiscal ou software contábil, o principal benefício é poder estudar e integrar uma implementação pública das regras tributárias em vez de reproduzir as fórmulas sem referência ao código oficial. Isso não significa que qualquer sistema esteja automaticamente adequado à Reforma Tributária: integrar a ferramenta exige escolher o projeto correto, manter tabelas e versões atualizadas e testar documentos fiscais antes de entrar em produção.

Em resumo:

  • A Receita abriu três repositórios técnicos sob licença MIT, cada um com função distinta.
  • Há APIs locais para cálculos do regime regular e do Simples, além de um serviço de geração de DANFSe.
  • A integração exige ambiente de testes, rastreabilidade de versões e revisão fiscal antes de uso real.

Há três repositórios, mas não são três versões equivalentes da mesma API. Um atende ao regime geral, outro ao Simples Nacional e o terceiro gera o documento auxiliar da NFS-e. Confundir essas funções é uma forma de iniciar uma integração pelo componente errado.

O que a Receita liberou, exatamente?

A publicação foi autorizada pela Portaria Cotec nº 342, de 12 de novembro de 2026, divulgada no Diário Oficial da União de 13 de novembro. Segundo a Receita, o código já podia ser baixado pela Plataforma CBS desde 2025; a novidade é sua publicação oficial no GitHub, com repositórios públicos, histórico de alterações e referência a hashes das versões iniciais.

A licença MIT permite ampla reutilização conforme suas condições. Isso não dispensa validação fiscal, manutenção de versões, consulta à legislação e análise das responsabilidades de quem emite os documentos.

Qual repositório usar no seu sistema?

Repositório oficial Função principal Tecnologia e porta documentadas Para quem faz sentido
calculadora-rtc-regime-regular Calcular CBS, IBS e Imposto Seletivo, consultar tabelas e gerar/validar grupos XML fiscais Java 21+, Spring Boot, API local na porta 8080 ERP e emissor fiscal com operações do regime geral
calculadora-rtc-simples-nacional Calcular CBS e IBS nas operações do Simples, consultar atividades e observar erros por item Java 21+, Spring Boot, API local na porta 8082 Sistemas que atendem empresas do Simples Nacional
calculadora-rtc-gerador-danfse Gerar DANFSe em PDF a partir de XML da NFS-e Go 1.27+, serviço HTTP na porta 8080 por padrão Sistemas que precisam gerar o documento auxiliar da NFS-e

As portas indicadas referem-se às configurações locais descritas nos README, não a uma API pública remota da Receita à qual qualquer ERP possa enviar dados pela internet. O gerador DANFSe tampouco substitui o cálculo de tributos.

O que a API do regime geral disponibiliza?

A documentação oficial informa uma base local de rotas em http://localhost:8080/api/calculadora. Entre as operações publicadas estão:

  • POST /regime-geral: cálculo de uma operação, com falha da operação ao encontrar o primeiro erro.
  • POST /observabilidade/regime-geral: processamento que permite analisar erros por item sem interromper todos os demais.
  • POST /xml/generate?tipo=nfe: geração do XML tributário com base no cálculo.
  • POST /xml/validate?tipo=nfe&subtipo=grupo: validação contra o esquema XSD correspondente.
  • Rotas de dados abertos para CST, cClassTrib, NCM, NBS, alíquotas e fundamentações legais.

É importante distinguir cálculo tributário de emissão de documento fiscal. Um emissor completo também tem de controlar dados cadastrais, regras de autorização, assinatura, transmissão e retorno das administrações tributárias. Não basta obter um XML calculado para considerar a nota emitida.

Um ERP que precise processar dezenas de itens deve decidir explicitamente como tratar erros parciais. O caminho de observabilidade pode ajudar a mostrar quais itens precisam de correção, mas o sistema não deve transmitir documentos incompletos por isso.

E no Simples Nacional?

Na tabela de endpoints do repositório, a segunda API tem base http://localhost:8082/api e foi desenhada para operações do Simples Nacional. Seu README documenta POST /calculadora/observabilidade/simples-nacional, a consulta de códigos de erro que começam em VSN- e rotas de atividades vigentes em uma data.

O campo da data da operação importa: consultar uma atividade sem considerar sua vigência pode levar um ERP a usar classificação incompatível com o período fiscal. É uma boa prática registrar, junto ao cálculo, a data informada, a versão da aplicação, o conjunto de parâmetros usado e o resultado retornado.

Há uma diferença na documentação: a tabela dos endpoints menciona a porta 8082, mas a instrução para executar o perfil offline aponta 8080. Confira a configuração da instalação e abra o Swagger local antes de integrar; não presuma que as portas sejam iguais em todos os perfis.

O projeto também expõe GET /versao e GET /versao/status para o perfil offline. Antes de integrar, confirme quais dados e perfis estão disponíveis na versão que foi baixada. O README descreve dependência de um banco SQLite local gerado previamente; sem esse banco, o perfil offline não inicia.

Como testar a instalação sem modificar o ERP de produção

O roteiro indicado pela documentação do projeto do regime geral pode ser reproduzido em ambiente isolado de desenvolvimento:

  1. Instale Java 21 ou superior e Git. Confirme a versão com java -version.
  2. Clone https://github.com/ReceitaFederal/calculadora-rtc-regime-regular.git e entre na pasta.
  3. Gere o banco de dados local com as instruções Flyway do README, usando o Maven Wrapper que acompanha o projeto.
  4. Execute os testes antes de iniciar o serviço. A documentação utiliza ./mvnw clean test jacoco:report.
  5. Inicie com o perfil offline conforme o README e consulte o Swagger local em http://localhost:8080/api/swagger-ui.html.
  6. Teste casos representativos de produtos e serviços: classificações comuns, campos ausentes, arredondamentos, códigos inválidos e períodos diferentes.
  7. Guarde registros de resultados e compare-os com a legislação e documentação fiscal aplicável antes de conectar o ambiente de produção.

Este é um roteiro de verificação da documentação; não é um teste de execução feito pelo TEG6. A documentação pode mudar, e a instalação precisa ser validada no sistema operacional e na versão efetivamente utilizados.

Arquitetura de integração: como evitar um ponto único de falha

Para aplicações empresariais, é mais seguro separar o fluxo do ERP em etapas: receber o pedido de cálculo, validar os dados de entrada, chamar a instância local da calculadora, guardar o resultado e a versão, gerar ou validar o grupo XML e só então seguir para as etapas fiscais do emissor. A versão da regra aplicada deve acompanhar o documento para permitir auditoria posterior.

Uma integração instalada em rede requer cuidados de roteamento, autenticação e tolerância a falhas. Isso é diferente de simplesmente colocar a API em uma porta pública. Nosso guia sobre DNS, proxy reverso e failover ajuda a distinguir conceitos de disponibilidade sem confundir uma API local com um endpoint de internet.

Não exponha serviços de cálculo com dados fiscais sem controles de acesso, criptografia quando aplicável e monitoramento. Também é prudente limitar requisições e examinar dependências: práticas de proteção de APIs discutidas no nosso material sobre ataques a serviços de IA são uma referência geral de superfície de ataque, embora as ameaças específicas sejam diferentes.

Cinco verificações antes de ativar para clientes

1. Identificar o regime tributário. Um fluxo de Simples Nacional não deve ser enviado por engano à API do regime geral.

2. Registrar versões. O repositório pode evoluir, e o conjunto de tabelas precisa ser rastreável. A portaria registra hashes iniciais; confira-os nas fontes oficiais e mantenha registro da versão instalada.

3. Montar testes de regressão. Separe casos de referência aprovados pela equipe fiscal e reproduza-os quando atualizar código, tabelas ou dependências.

4. Evitar dependência de endpoint externo não documentado. O README mostra APIs locais; não baseie a arquitetura em um serviço público de cálculo cuja disponibilidade e política não foram confirmadas.

5. Definir responsabilidade fiscal e operacional. A adoção do código oficial não elimina as verificações do contribuinte, do contador e da software house nem substitui as exigências de autorização e transmissão dos documentos.

O código da Receita já está pronto para produção?

A publicação oficial indica um projeto aberto para integração, mas não constitui, isoladamente, certificação do seu ERP. A resposta depende do cenário de implantação, das versões, das operações suportadas, dos testes, das regras fiscais vigentes e dos controles de segurança. Antes de ativar, consulte a documentação atual de cada repositório e valide com a equipe responsável pelo cumprimento fiscal.

O ponto de partida mais útil não é baixar os três projetos indiscriminadamente: é mapear quais operações e documentos sua empresa precisa suportar, selecionar o componente correspondente e preparar um processo de atualização e rastreabilidade.

Fontes oficiais consultadas em 18/11/2026

Sobre o autor: Elton Ciatto acompanha software, inteligência artificial, infraestrutura e aplicações digitais no TEG6. Este guia compara documentação oficial; não relata uma homologação técnica própria.

Imagem ilustrativa: Nathan da Silva, Unsplash, sob licença Unsplash. Não representa os sistemas da Receita Federal nem testes realizados pelo TEG6.

Inscreva-se