🧾 laravel-rtc-calculator

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

• ✅ 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

• PHP ^8.1
• Laravel ^10.0 ou ^11.0
• A Calculadora RTC Java rodando localmente (disponível em consumo.tributos.gov.br)

💡 A calculadora Java expõe uma API REST em http://localhost:8080 por padrão.

🐳 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

Acesse o portal oficial da Receita Federal e baixe a versão mais recente da Calculadora Offline: -> Calculadora Offline - Portal da Receita Federal

Lá você encontrará:

- Imagem Docker (recomendado)
- Arquivo JAR (api-regime-geral.jar)

Consulte também: - Instruções oficiais de instalação - Documentação da API / Swagger

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)

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

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

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

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

$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

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

// 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

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

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

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

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

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

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

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

// 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

A pasta 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

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

MIT — veja o arquivo LICENSE para detalhes.

🏛️ 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.