DEV Community

Fabio Nobre
Fabio Nobre

Posted on

Transparência de Tributos dos Combustíveis: do PDF da Fecombustíveis ao XML do PDV, sem servidor

#devchallenge #hf26challenge #githubactions #javascript

Hacktoberfest Open-Source AI Challenge Week 2: Side Hustle Submission 💸

This is a submission for the Hacktoberfest Open-Source AI Challenge Week 2: Side Hustle

O que eu construí

Todo posto de combustível no Brasil precisa mostrar na nota/cupom quanto do preço é imposto (Lei 12.741/2012, a "Lei da Transparência"). Para combustíveis, os valores de ICMS, PMPF e PIS/COFINS mudam por estado e por mês, e a referência que todo mundo usa é o PDF "Carga tributária estadual" publicado pela Fecombustíveis.

O problema: alguém precisa abrir esse PDF todo mês, conferir 27 UFs × 6 combustíveis e redigitar tudo no arquivo TransparenciaTributos.xml que o sistema de PDV lê. É trabalho chato, manual e fácil de errar.

O Transparência de Tributos – Combustíveis automatiza isso:

  • a cada 8 horas um workflow do GitHub Actions procura o PDF novo no site da Fecombustíveis;
  • uma IA lê o PDF e devolve os valores por combustível e UF;
  • o sistema compara com o XML do mês anterior, destaca o que mudou e confere as contas (PMPF × alíquota = ICMS; PMPF × 9,25% = PIS/COFINS no GNV);
  • gera o XML novo — fechando o bloco antigo no dia anterior e abrindo um bloco novo de vigência só para os combustíveis que mudaram;
  • publica tudo e avisa por e-mail e Discord.

Quem pagaria por isso? Software houses de automação comercial que atendem postos (como a Imex Tecnologia, onde isso nasceu) e redes de postos que hoje fazem essa atualização na mão. É um nicho pequeno, específico e com uma dor recorrente todo mês — exatamente o tipo de "side hustle" que vira serviço por assinatura.

Demo

Código

GitHub logo imextecnologia / tributacao

tributacao

Transparência de Tributos – Combustíveis

Site estático (GitHub Pages) que gera todo mês o XML TransparenciaTributos a partir do PDF "Carga tributária estadual" da Fecombustíveis.

Site: https://imextecnologia.github.io/tributacao/ · Tributos por estado: https://imextecnologia.github.io/tributacao/tributos.html

Como funciona

  1. Busca do PDF – a cada 8 horas um workflow procura o PDF novo na página da Fecombustíveis, salva em pdf/ e já gera o XML do mês em xml/ (veja Busca automática do PDF).
  2. Leitura com IA – o site envia o PDF ao Google Gemini, que devolve os valores por combustível e UF.
  3. Comparação – os valores são comparados com o XML do mês anterior (em xml/) e o que mudou fica destacado.
  4. Geração – para cada combustível que mudou, o bloco antigo termina no dia anterior (ex.: 30/09/2026) e é criado um bloco novo (ex.: 01/10/2026 até 01/01/2050). Combustíveis sem mudança ficam como estão Também é possível baixar uma planilha…
View on GitHub

Como eu construí

  • Site 100% estático no GitHub Pages — HTML + JS puro, sem framework e sem servidor próprio. Tudo roda no navegador.
  • GitHub Actions — buscar-pdf.yml roda às 00:00, 08:00 e 16:00 UTC, baixa o PDF, gera o XML com scripts/gerar-xml.js (mesmas regras do site) e faz commit; pages.yml publica a cada push.
  • Leitura do PDF com IA — hoje o projeto usa o Google Gemini (plano gratuito), com fallback entre gemini-flash-latest, gemini-flash-lite-latest, gemini-2.5-flash e gemini-2.5-flash-lite.
  • Validação antes de confiar na IA — se algum valor não fecha a conta, o XML não é gravado automaticamente; ele fica para revisão humana no site (amarelo = mudou, borda vermelha = conta não fecha). O resultado da IA fica em cache no navegador e, se o XML do mês já existe, a IA nem é chamada.

O que fiz nesta semana (12 a 18 de outubro)

A Fecombustíveis publicou uma atualização no meio do mês (10/10), além do PDF de 01/10. Isso expôs um bug: a página inicial só procurava o XML com a data exata do PDF (20261001) e ignorava o 20261010.

  • 13/10 — corrigi index.html para usar o XML mais recente a partir da data do PDF, comparando-o com o XML anterior a ele, sem chamar a IA de novo. Em tributos.html, o link do PDF passou a apontar para o PDF mais recente até a data do XML (já que uma atualização no meio do mês pode não ter PDF próprio).
  • 13/10 — subi os PDFs/XMLs novos e ajustei o TransparenciaTributos_20261001.xml.
  • 15/10 — revisei e atualizei o TransparenciaTributos_20261010.xml.

Pequeno no diff (+11/−8 linhas), mas é o tipo de caso real que só aparece quando o sistema está rodando em produção.

Por que inovação aberta importa?

Vou ser transparente (o projeto se chama assim, afinal): o modelo que uso hoje não é open-weight — é o Gemini via API. O que é aberto aqui é todo o resto: o código, as regras de geração do XML, os workflows e o histórico de cada XML mensal, públicos no GitHub, para qualquer posto ou software house auditar ou reaproveitar.

E justamente por estar tudo aberto e desacoplado, a IA é uma peça trocável: a extração é uma única chamada que devolve JSON, e a validação das contas é feita fora do modelo. O próximo passo natural é testar um modelo open-weight (como o Gemma) nessa etapa, para não depender do plano gratuito de um provedor e poder rodar localmente. Como o PDF da Fecombustíveis é público, privacidade não é o problema — custo e independência de fornecedor são.

Top comments (0)