PHPackages crdesign8/laravel-rtc-calculator - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. crdesign8/laravel-rtc-calculator ActiveLibrary[Utility & Helpers](/categories/utility) crdesign8/laravel-rtc-calculator ================================ Integração Laravel com a Calculadora RTC da Receita Federal para cálculo, geração e validação de tributos da Reforma Tributária (IS, IBS e CBS). v1.1.0(3mo ago)10[8 issues](https://github.com/crdesign8/laravel-rtc-calculator/issues)[1 PRs](https://github.com/crdesign8/laravel-rtc-calculator/pulls)MITPHPPHP ^8.1 Since Apr 12Pushed 2mo agoCompare [ Source](https://github.com/crdesign8/laravel-rtc-calculator)[ Packagist](https://packagist.org/packages/crdesign8/laravel-rtc-calculator)[ Docs](https://github.com/crdesign8/laravel-rtc-calculator)[ RSS](/packages/crdesign8-laravel-rtc-calculator/feed)WikiDiscussions main Synced 3w ago READMEChangelog (1)Dependencies (6)Versions (5)Used By (0) 🧾 laravel-rtc-calculator ======================== [](#-laravel-rtc-calculator) [![Tests](https://github.com/crdesign8/laravel-rtc-calculator/actions/workflows/tests.yml/badge.svg)](https://github.com/crdesign8/laravel-rtc-calculator/actions)[![Latest Version on Packagist](https://camo.githubusercontent.com/022209ea7a3e5b204f3edd02d6605cea849eff7b9b737ad5808dbf4621bb38ed/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f637264657369676e382f6c61726176656c2d7274632d63616c63756c61746f722e737667)](https://packagist.org/packages/crdesign8/laravel-rtc-calculator)[![License](https://camo.githubusercontent.com/ba0c95497d505b613762372e0408b8e49acff80136fb104d2f260eed4e7feb0c/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f637264657369676e382f6c61726176656c2d7274632d63616c63756c61746f72)](LICENSE) Pacote Laravel para integração com a **Calculadora da Reforma Tributária do Consumo (RTC)** da Receita Federal do Brasil. Ao contrário de outros exemplos disponíveis em Python, este pacote permite que desenvolvedores **Laravel** utilizem a calculadora Java (disponibilizada pela Receita Federal) diretamente em suas aplicações PHP, com uma API fluente, tipagem forte e totalmente testável. --- ✨ Funcionalidades ----------------- [](#-funcionalidades) - ✅ Cálculo de tributos no **Regime Geral** (IS, IBS, CBS) - ✅ Geração de **XML RTC** compatível com NFe, NFCe e CTe - ✅ Validação de XML gerado - ✅ Injeção automática dos grupos RTC em NFe existentes - ✅ **Cálculo direto a partir de XML de NFe** (`calcularPorNfe`) — extrai municipio, UF e itens automaticamente - ✅ **Evento Laravel `RtcCalculated`** — permite logging, auditoria e integrações após o cálculo - ✅ API fluente e idiomática ao estilo Laravel com `addItem()` e `addItems([])` - ✅ Configuração via `.env` - ✅ Retry automático em caso de falha de conexão - ✅ Cobertura de testes com PHPUnit --- 📋 Requisitos ------------ [](#-requisitos) - PHP `^8.1` - Laravel `^10.0` ou `^11.0` - A **Calculadora RTC Java** rodando localmente (disponível em [consumo.tributos.gov.br](https://consumo.tributos.gov.br/servico/calcular-tributos-consumo/calculadora)) > 💡 A calculadora Java expõe uma API REST em `http://localhost:8080` por padrão. --- 🐳 Como rodar a Calculadora RTC (Java) da Receita Federal -------------------------------------------------------- [](#-como-rodar-a-calculadora-rtc-java-da-receita-federal) O pacote não inclui a Calculadora oficial — ela é um componente fornecido pela Receita Federal (calculadora offline). Você pode rodá-la localmente usando Docker ou diretamente com Java, conforme as instruções abaixo. ### 1. Onde baixar a Calculadora [](#1-onde-baixar-a-calculadora) Acesse o portal oficial da Receita Federal e baixe a versão mais recente da Calculadora Offline: -> [Calculadora Offline - Portal da Receita Federal](https://piloto-cbs.tributos.gov.br/servico/calculadora-consumo/calculadora/calculadora-offline) Lá você encontrará: ``` - Imagem Docker (recomendado) - Arquivo JAR (api-regime-geral.jar) ``` Consulte também: - [Instruções oficiais de instalação](https://piloto-cbs.tributos.gov.br/servico/calculadora-consumo/calculadora/calculadora-offline/calculadora-offline-instrucoes)- [Documentação da API / Swagger](https://piloto-cbs.tributos.gov.br/servico/calculadora-consumo/calculadora/documentacao) ### 2. Opção Recomendada: Docker [](#2-opção-recomendada-docker) ``` # Exemplo básico (ajuste conforme a versão baixada) docker run -d \ --name calculadora-rtc \ -p 8080:8080 \ -v $(pwd)/calculadora-data:/calculadora/data \ # opcional: persistir banco SQLite calculadora-rtc:latest # Ou, se você extraiu o pacote da Receita: docker run -d \ --name calculadora-rtc \ -p 8080:8080 \ -v ./calculadora:/calculadora \ openjdk:21-jdk-slim \ java -jar /calculadora/api-regime-geral.jar --spring.profiles.active=offline ``` Verifique se está rodando: ``` curl -s http://localhost:8080/actuator/health | jq # ou php artisan rtc:healthcheck # Esperado: { "status": "UP" } ``` ### 3. Opção sem Docker (JAR direto) [](#3-opção-sem-docker-jar-direto) ``` java -jar api-regime-geral.jar \ --spring.profiles.active=offline \ --server.port=8080 ``` Requisito: Java 21 ou superior. ### 4. Configuração no seu projeto Laravel [](#4-configuração-no-seu-projeto-laravel) No arquivo .env: ``` RTC_BASE_URL=http://localhost:8080 RTC_TIMEOUT=60 RTC_RETRY_TIMES=3 ``` depois rode o comando de healthcheck para verificar a conexão: ``` php artisan rtc:healthcheck # Esperado: Calculadora RTC disponível em http://localhost:8080 ✔ ``` --- 📦 Instalação do Pacote ---------------------- [](#-instalação-do-pacote) ``` composer require crdesign8/laravel-rtc-calculator ``` Publique o arquivo de configuração: ``` php artisan vendor:publish --tag=rtc-config ``` Configure no seu `.env`: ``` RTC_BASE_URL=http://localhost:8080 RTC_TIMEOUT=30 ``` --- 🚀 Uso Básico ------------ [](#-uso-básico) ### Via Facade (forma mais simples) [](#via-facade-forma-mais-simples) ``` use Crdesign8\LaravelRtcCalculator\Facades\Rtc; use Crdesign8\LaravelRtcCalculator\DTOs\ItemDTO; use Crdesign8\LaravelRtcCalculator\Enums\UnidadeMedida; $resultado = Rtc::make() ->paraFiscal(municipio: 4314902, uf: 'RS') ->emitidoEm('2027-01-01T03:00:00-03:00') ->addItem( ItemDTO::make(numero: 1) ->ncm('24021000') ->quantidade(222) ->unidade(UnidadeMedida::VN) ->cst('550') ->baseCalculo(1111.00) ->cClassTrib('550020') ) ->calcular(); // Acessa os totais calculados echo $resultado->getTotal()->getVIsTot(); // Imposto Seletivo total echo $resultado->getTotal()->getVBcIbsCbs(); // Base de cálculo IBS+CBS echo $resultado->getTotal()->getVCbsTot(); // CBS total // Acessa um item específico pelo número $item = $resultado->getItem(1); echo $item->getCstIs(); // CST do Imposto Seletivo echo $item->getVIs(); // Valor do IS ``` ### Adicionar múltiplos itens de uma vez [](#adicionar-múltiplos-itens-de-uma-vez) ``` $resultado = Rtc::make() ->paraFiscal(municipio: 4314902, uf: 'RS') ->emitidoEm('2027-01-01T03:00:00-03:00') ->addItems([ ItemDTO::make(1)->ncm('24021000')->quantidade(100)->unidade(UnidadeMedida::VN) ->cst('550')->baseCalculo(500.00)->cClassTrib('550020'), ItemDTO::make(2)->ncm('22030000')->quantidade(50)->unidade(UnidadeMedida::L) ->cst('200')->baseCalculo(200.00)->cClassTrib('200032'), ]) ->calcular(); ``` ### Calcular a partir do XML de uma NFe existente [](#calcular-a-partir-do-xml-de-uma-nfe-existente) Extrai municipio, UF, data de emissão e dados de produto diretamente da nota. Você só precisa informar os campos exclusivos do RTC (`cst` e `cClassTrib`) para cada `nItem` da NFe: ``` $xmlNfe = file_get_contents(storage_path('app/nfe-sem-rtc.xml')); $resultado = Rtc::make()->calcularPorNfe( xmlNfe: $xmlNfe, rtcPorItem: [ 1 => [ 'cst' => '200', 'cClassTrib' => '200032', 'tributacaoRegular' => ['cst' => '200', 'cClassTrib' => '200032'], ], 2 => [ 'cst' => '550', 'cClassTrib' => '550020', 'impostoSeletivo' => [ 'cst' => '000', 'baseCalculo' => 250.00, 'cClassTrib' => '000001', 'unidade' => 'VN', 'quantidade' => 10, 'impostoInformado' => 0, ], ], ], ); echo $resultado->getTotal()->getVBcIbsCbs(); // base total IBS+CBS echo $resultado->getTotal()->getVIsTot(); // total IS ``` > Importante: o array `rtcPorItem` deve conter todos os itens (`nItem`) existentes no XML da NFe. ### Gerar e Injetar XML na NFe [](#gerar-e-injetar-xml-na-nfe) ``` // Gera o XML com grupos RTC $xmlRtc = Rtc::make()->gerarXml($resultado); // Injeta na NFe existente $nfeComRtc = Rtc::make()->injetarNfe( xmlRtc: $xmlRtc, xmlNfe: file_get_contents('nfe-sem-rtc.xml') ); file_put_contents('nfe-com-rtc.xml', $nfeComRtc); ``` ### Reagindo ao cálculo com Eventos Laravel [](#reagindo-ao-cálculo-com-eventos-laravel) Depois de cada cálculo bem-sucedido (via `calcular()` ou `executarCalculo()`), o evento `RtcCalculated` é despachado automaticamente: ``` use Crdesign8\LaravelRtcCalculator\Events\RtcCalculated; // Em qualquer EventServiceProvider ou via closure: Event::listen(RtcCalculated::class, function (RtcCalculated $event) { Log::info('RTC calculado', [ 'municipio' => $event->dto->getMunicipio(), 'itens' => count($event->dto->getItens()), 'vIsTot' => $event->result->getTotal()->getVIsTot(), 'vCbsTot' => $event->result->getTotal()->getVCbsTot(), ]); }); ``` --- 🖥️ Comandos Artisan ------------------- [](#️-comandos-artisan) ### Calcular tributos a partir de um arquivo JSON [](#calcular-tributos-a-partir-de-um-arquivo-json) ``` php artisan rtc:calcular entrada.json # Salvar o resultado em arquivo php artisan rtc:calcular entrada.json --saida=resultado.json ``` ### Injetar grupos RTC em uma NFe existente [](#injetar-grupos-rtc-em-uma-nfe-existente) ``` php artisan rtc:injetar nfe-sem-rtc.xml resultado.json nfe-com-rtc.xml # Para CTe ou NFCe php artisan rtc:injetar nota.xml resultado.json nota-com-rtc.xml --tipo=CTe ``` ### Verificar se a calculadora Java está rodando [](#verificar-se-a-calculadora-java-está-rodando) ``` php artisan rtc:healthcheck # Testar uma URL diferente da configurada php artisan rtc:healthcheck --url=http://meu-servidor:8080 ``` --- 🔍 Como funciona por baixo dos panos ----------------------------------- [](#-como-funciona-por-baixo-dos-panos) Este pacote é um **cliente HTTP** para a Calculadora RTC Java da Receita Federal. Ele não implementa nenhuma regra tributária — toda a lógica fiscal fica na calculadora oficial. ### Endpoints consumidos [](#endpoints-consumidos) MétodoEndpointUtilizado por`POST``/api/calculadora/regime-geral``CalcularTributosAction`, `Rtc::calcular()``POST``/api/calculadora/xml/generate?tipo={NFe|NFCe|CTe}``GerarXmlRtcAction`, `Rtc::gerarXml()``POST``/api/calculadora/xml/validate``ValidarXmlRtcAction`, `Rtc::validarXml()`### Fluxo de uma requisição [](#fluxo-de-uma-requisição) ``` Facade / Builder └─ Rtc::calcular() └─ CalcularTributosAction::handle(CalculoRequestDTO) └─ RtcClient::calcularRegimeGeral() └─ POST /api/calculadora/regime-geral (JSON) └─ CalculoResult::fromArray() (resposta tipada) └─ event(RtcCalculated) (evento Laravel) ``` > A injeção na NFe (`InjetarXmlNfeAction`) é executada **localmente**, sem chamada HTTP — ela apenas combina os XMLs usando DOMDocument. ### Autenticação e ambiente de produção [](#autenticação-e-ambiente-de-produção) Atualmente a Calculadora RTC está em fase **piloto** e não exige autenticação. Quando a Receita Federal disponibilizar o ambiente de produção com autenticação, bastará adicionar headers customizados via `config/rtc.php`. --- ⚙️ Configuração --------------- [](#️-configuração) ``` // config/rtc.php return [ 'base_url' => env('RTC_BASE_URL', 'http://localhost:8080'), 'timeout' => env('RTC_TIMEOUT', 30), 'retry_times' => env('RTC_RETRY_TIMES', 2), 'retry_sleep_ms' => env('RTC_RETRY_SLEEP_MS', 500), 'default_tipo_documento'=> env('RTC_DEFAULT_TIPO_DOCUMENTO', 'NFe'), 'versao' => env('RTC_VERSAO', '1.0.0'), 'logging' => [ 'enabled' => env('RTC_LOGGING_ENABLED', false), 'channel' => env('RTC_LOGGING_CHANNEL', 'stack'), ], ]; ``` --- � Exemplos Executáveis ---------------------- [](#-exemplos-executáveis) A pasta [`examples/`](examples/) contém scripts standalone que funcionam sem uma aplicação Laravel completa — apenas `composer install` e a calculadora Java rodando: ``` # Pré-requisito: calculadora Java em http://localhost:8080 # 1. Cálculo de tributos (IS + IBS + CBS) com tabela formatada php examples/01-calcular-tributos.php # 2. Geração do XML com grupos IS/IBSCBS/ISTot/IBSCBSTot php examples/02-gerar-xml-rtc.php # 3. Fluxo completo: calcular → gerar XML → injetar em uma NFe real php examples/03-fluxo-completo-nfe.php ``` Os arquivos gerados são salvos em `examples/output/` (pasta ignorada pelo Git). > Para usar uma URL diferente: `RTC_BASE_URL=http://meu-servidor:9090 php examples/01-calcular-tributos.php` --- �🤝 Contribuindo --------------- [](#-contribuindo) Contribuições são muito bem-vindas! Se você encontrou um bug, tem uma sugestão ou quer adicionar uma funcionalidade, a forma mais simples de contribuir é **abrindo uma issue** no repositório. Para contribuições de código: 1. Fork o repositório 2. Crie sua branch: `git checkout -b feature/minha-feature` 3. Commit: `git commit -m 'feat: minha feature'` 4. Push: `git push origin feature/minha-feature` 5. Abra um Pull Request descrevendo o que foi alterado e por quê --- 📄 Licença --------- [](#-licença) MIT — veja o arquivo [LICENSE](LICENSE) para detalhes. --- 🏛️ Sobre a Reforma Tributária ----------------------------- [](#️-sobre-a-reforma-tributária) A Reforma Tributária do Consumo (EC 132/2023) institui o IBS (Imposto sobre Bens e Serviços), o CBS (Contribuição sobre Bens e Serviços) e o IS (Imposto Seletivo), em substituição ao PIS, Cofins, IPI, ICMS e ISS. A Calculadora RTC é a ferramenta oficial da Receita Federal para auxiliar na apuração desses novos tributos. ### Health Score 31 — LowBetter than 65% of packages Maintenance64 Regular maintenance activity Popularity2 Limited adoption so far Community6 Small or concentrated contributor base Maturity46 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~0 days Total 2 Last Release 102d ago ### Community Maintainers ![](https://avatars.githubusercontent.com/u/57750317?v=4)[Celio Monteiro](/maintainers/crdesign8)[@crdesign8](https://github.com/crdesign8) --- Top Contributors [![crdesign8](https://avatars.githubusercontent.com/u/57750317?v=4)](https://github.com/crdesign8 "crdesign8 (22 commits)") --- Tags laravelnfenfcectertcreceita-federalibstributoscalculadorareforma-tributariacbsimposto-seletivoimposto-consumo ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/crdesign8-laravel-rtc-calculator/health.svg) ``` [![Health](https://phpackages.com/badges/crdesign8-laravel-rtc-calculator/health.svg)](https://phpackages.com/packages/crdesign8-laravel-rtc-calculator) ``` ### Alternatives [psalm/plugin-laravel Psalm plugin for Laravel 3345.3M347](/packages/psalm-plugin-laravel)[laravel/mcp Rapidly build MCP servers for your Laravel applications. 77922.3M186](/packages/laravel-mcp)[spatie/laravel-export Create a static site bundle from a Laravel app 674146.0k6](/packages/spatie-laravel-export)[api-platform/laravel API Platform support for Laravel 58174.6k17](/packages/api-platform-laravel)[defstudio/telegraph A laravel facade to interact with Telegram Bots 813336.8k3](/packages/defstudio-telegraph)[simplestats-io/laravel-client Server-side analytics for Laravel that follows the full funnel from visit to registration to payment, attributed to the channel that drove it. Revenue, MRR, churn and ad-spend profit (ROAS/CAC) per channel. GDPR compliant, ad-blocker proof. 5022.6k](/packages/simplestats-io-laravel-client) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)