calculadora-rtc-simples-nacional README

The project's README from github.com/ReceitaFederal/calculadora-rtc-simples-nacional. As one markdown file: README.md.

Calculadora de Tributos - Simples Nacional

Descrição do Projeto

API REST que realiza o cálculo da CBS e do IBS (Reforma Tributária do Consumo — LC 214/2025) nas operações do regime do simples nacional.


Público-Alvo


Funcionalidades

Todos os caminhos começam com http://localhost:8082/api. A lista completa, com esquemas e exemplos, está no Swagger (http://localhost:8082/api/swagger-ui.html).

Funcionalidade Endpoint
Cálculo do Simples Nacional com observabilidade (erros por item, sem interromper os demais) POST /calculadora/observabilidade/simples-nacional
Descrição de um código de erro VSN- GET /calculadora/observabilidade/simples-nacional/erros?codigo=VSN-001
Atividades do Simples Nacional vigentes em uma data, com filtros por anexo, tipo de documento e cClassTrib GET /calculadora/simples-nacional/atividades?data=AAAA-MM-DD
Consulta de uma atividade pelo código, vigente na data GET /calculadora/simples-nacional/atividades/{codigo}?data=AAAA-MM-DD
Informações de versão da aplicação, da base de dados e do ambiente GET /versao
Status da versão no perfil offline, comparado à instalação online GET /versao/status (somente perfil offline)

Requisitos

Requisitos do Sistema

Dependências Principais

O projeto utiliza as seguintes tecnologias:


Instruções de Instalação

1. Pré-requisitos

Certifique-se de ter instalado o Java 21 ou superior e verifique as versões:

# Verificar versão do Java
java -version

2. Clonar o Repositório

git clone https://github.com/ReceitaFederal/calculadora-rtc-simples-nacional.git
cd calculadora-rtc-simples-nacional

3. Gerar o Banco de Dados (obrigatório)

O perfil offline lê o banco ./calculadora/db/calculadora-pro.db, definido por application.db.filename em application-offline.yml. O caminho é relativo à raiz do projeto e o banco é aberto em modo somente leitura.

Atenção: use os scripts SQL para gerar o arquivo do Banco de Dados localizados no repositório https://github.com/ReceitaFederal/calculadora-rtc-simples-nacional.git

Atenção: a aplicação só funciona se o banco estiver gerado. Sem ele, o perfil offline não inicia.

Copie para a raiz deste projeto a pasta flyway/ presente no repositório https://github.com/ReceitaFederal/calculadora-rtc-simples-nacional.git

Linux/macOS:

mkdir -p ./calculadora/db
./mvnw flyway:migrate -Dflyway.configFiles=./flyway/flyway-pro.conf --batch-mode --errors

Windows:

mkdir calculadora\db
mvnw.cmd flyway:migrate -Dflyway.configFiles=flyway\flyway-pro.conf --batch-mode --errors

Confirme que o arquivo foi criado com ls -lah ./calculadora/db/calculadora-pro.db (Linux/macOS) ou dir calculadora\db\calculadora-pro.db (Windows).

4. Compilar e Executar os Testes

Os testes exigem o banco gerado no passo 3, pois a maioria são testes de integração com o perfil testes.

Executar todos os testes com relatório de cobertura (JaCoCo):

Linux/macOS:

./mvnw clean test jacoco:report

Windows:

mvnw.cmd clean test jacoco:report

O relatório de cobertura fica em target/site/jacoco/index.html.

5. Executar a Aplicação com perfil Offline (spring-boot:run)

Linux/macOS:

./mvnw spring-boot:run -Dspring-boot.run.profiles=offline

Windows:

mvnw.cmd spring-boot:run "-Dspring-boot.run.profiles=offline"

A aplicação estará disponível em http://localhost:8080/api.

6. Gerar o JAR e Executar com java -jar (perfil offline)

Linux/macOS:

./mvnw clean package
java -Dspring.profiles.active=offline -jar target/api-regime-geral.jar

Windows:

mvnw.cmd clean package
java "-Dspring.profiles.active=offline" -jar target\api-regime-geral.jar

Execute o JAR a partir da raiz do projeto, para que ./calculadora/db seja encontrado.


Referências

Licença

Este projeto é distribuído sob a licença especificada no arquivo LICENSE.

calculadora-rtc-simples-nacional (ReceitaFederal/calculadora-rtc-simples-nacional)

database-migrations
Searching Database…

What is this?It is a REST API that calculates CBS and IBS, the consumption taxes from Brazil's tax reform (LC 214/2025), for Simples Nacional operations.
Is there a UI, or is it only an API?It is only an API; no UI is mentioned. The full endpoint list with schemas and examples is in Swagger (OpenAPI).
How do I get it running?Clone the repo, copy the flyway/ folder and run the repo's SQL scripts to generate ./calculadora/db/calculadora-pro.db. Then start it with spring-boot:run on the offline profile, or build a JAR and run java -jar from the project root.
What do I need installed first?Java 21 or newer and Git. Maven does not need to be installed, because the Maven Wrapper downloads it on the first run, which requires internet.
Does it start without the database file?No. The offline profile opens the SQLite file read-only and will not start if the database has not been generated.
Does it need internet while running?Not after setup, since the offline profile reads a local SQLite file. Internet is only needed for the first Maven Wrapper download.
What are CBS and IBS?CBS and IBS are the new consumption taxes introduced by Brazil's tax reform (LC 214/2025). This API calculates them for Simples Nacional operations.
What happens when one item in a calculation fails?The observability endpoint reports errors per item and keeps processing the others. Error codes such as VSN-001 can be looked up through the /erros endpoint.
What is the tech stack?Spring Boot 3.5.16 on Java 21+, SQLite for storage, Flyway for database migrations, and Springdoc 2.8.9 for OpenAPI docs.
Size
0.7 MB
Stars
503
Age
1mo
Commits · 90 Days