cbenef-sp

Fills the Brazilian ICMS tax-benefit code (cBenef) on product records for São Paulo state, inferring values from an existing tax master sheet — with a full audit trail and explicit uncertainty flags.

Preenche automaticamente o campo cBenef (Código de Benefício Fiscal do ICMS-SP) em cadastros de produto, cruzando um relatório de itens pendentes contra uma planilha-mestre de tributação.

---

O problema

Desde 06/04/2026 o campo cBenef é obrigatório na NF-e para os CSTs 20, 30, 40, 41, 50, 51, 53 e 70. Em 01/07/2026 o literal "Sem cBenef" foi desativado.

Resultado prático: produto novo cadastrado sem cBenef gera Rejeição 930 e trava a emissão da nota. Num supermercado que cadastra dezenas de itens por semana, isso é uma parada de operação por semana.

Preencher à mão é inviável e arriscado — errar o código para menos gera imposto a menor, com multa.

---

Como funciona

O script recebe duas planilhas e devolve a primeira preenchida, mais um laudo.

relatório "Sem cBenef" (PDV)  ─┐
                               ├─→  cbenef.py  ─→  planilha preenchida
planilha-mestre de tributação ─┘                +  laudo de decisões

Hierarquia de inferência

Cada item vazio passa por quatro tentativas, da evidência mais forte para a mais fraca:

Nível	Critério	Confiança
1	Código exato do produto na planilha-mestre	Alta
2	Descrição-base normalizada — remove 1KG, 500G, acentos e ruído para casar produtos quase idênticos	Alta
3	cBenef majoritário do mesmo NCM na base	Média
4	Fallback por CST	⚠️ Marcado como INCERTO

Três regras de segurança

1. Nunca sobrescreve cBenef já preenchido. Só age em célula vazia. Um valor existente foi decidido por alguém — o script não tem autoridade para revogá-lo.
2. Nenhuma tabela hardcoded. O script aprende o padrão da própria planilha-mestre a cada execução. Quando a legislação muda, atualiza-se a planilha, não o código — então a ferramenta não apodrece.
3. Laudo obrigatório. Toda decisão sai registrada com o nível de inferência que a originou, e os casos do nível 4 vêm com flag ⚠️ para conferência humana.

---

Uso

pip install openpyxl

python cbenef.py \
  --entrada  "Relatorio-Sem-cBenef.xlsx" \
  --mestre   "tributacao-mestre.xlsx" \
  --saida    "tributacao-mestre-preenchida.xlsx" \
  --laudo    "laudo.md"

O cabeçalho da planilha é detectado automaticamente, com aliases tolerantes (cst_icms, cst icms, CST ICMS s, cst…) — planilha de PDV real raramente vem com o nome de coluna que a documentação promete.

--entrada aceita .xlsx (o relatório exportado do PDV) ou um .txt/.csv com um item por linha, no formato codigo;ncm;cst — útil para cadastrar produto novo que ainda nem existe na planilha-mestre.

Teste em 1 minuto

O repositório traz duas planilhas sintéticas (nenhum dado de cliente): 41 produtos na mestre e um relatório de 11 itens que exercita os quatro níveis de inferência.

python cbenef.py \
  --entrada relatorio-exemplo.xlsx \
  --mestre  exemplo-mestre.xlsx \
  --saida   mestre-preenchida.xlsx \
  --laudo   laudo.md

Saída esperada: OK — 10 preenchidos, 2 incertos, 0 não encontrados. O laudo resultante está versionado em laudo-exemplo.md para conferência.

As planilhas são reprodutíveis a partir de scripts/gerar_exemplos.py — os códigos de barras são fictícios (prefixo 7890000…); NCM, CST e cBenef são valores públicos de legislação.

Testes

pip install pytest
python -m pytest -v

Cinco testes: um por nível da hierarquia de inferência, mais um que tenta deliberadamente sobrescrever um cBenef já preenchido e falha se o script deixar.

---

Estudo de caso: quando o script encontra um erro de cadastro

Durante uma execução, o item PALMITO EM CONSERVA aparecia cadastrado com CST 020 (tributado com redução de base de cálculo).

O produto não consta na lista taxativa do Art. 3º do Anexo II do RICMS-SP, que define os itens com redução de base para produtos alimentícios. A Resposta à Consulta 20213/2019 da SEFAZ-SP confirma o entendimento.

Correção aplicada: CST 020 → 000 (tributado integralmente).

O raciocínio para aceitar a correção automaticamente é o de conservadorismo fiscal: a mudança aumenta a base tributável, então nunca resulta em imposto a menor. Correções no sentido oposto — que reduziriam imposto — não são aplicadas automaticamente; o script as marca para decisão humana.

Essa assimetria é intencional. Um erro para mais custa dinheiro; um erro para menos custa multa, juros e autuação.

---

Limitações conhecidas

• O significado exato do código SP099090 ainda não foi confirmado junto à SEFAZ-SP. Itens que caem nele são marcados como incertos.
• A inferência de nível 3 (NCM majoritário) assume que a base existente está correta. Se a planilha-mestre tiver erro sistemático num NCM, o script o propaga — por isso o laudo existe.
• Escopo: operação interna no Estado de São Paulo. Operação interestadual e Simples Nacional não estão cobertos.
• Esta é uma ferramenta auxiliar de cadastro. Não substitui a análise de um profissional habilitado e não constitui garantia de conformidade fiscal.

---

Referência legal

• RICMS-SP — Decreto 45.490/2000, Anexo II, Art. 3º
• Portaria CAT que instituiu a obrigatoriedade do cBenef
• Resposta à Consulta 20213/2019 — SEFAZ-SP
• Tabela 5.2 da NF-e — Código de Benefício Fiscal na UF

Detalhamento em REFERENCIA_LEGAL.md.

---

Licença

MIT