Sugestão de Tributação por IA e Tax Preview

Visão Geral

O módulo tax-engine oferece dois recursos de apoio fiscal:

1. Tax Preview Batch — endpoint público sem autenticação para cálculo de IBS/CBS por lote, destinado a ferramentas fiscais e contadores externos.
2. Tax Determine — endpoint autenticado que aplica o motor de regras completo (ICMS + PIS/COFINS + IBS/CBS) a itens do cardápio.

A sugestão de NCM/CST baseada em IA está integrada ao assistente de configuração de Grupos Fiscais — o motor sugere automaticamente o regime e a alíquota com base no NCM e tipo de operação.

---

Endpoint Público: Tax Preview Batch

POST /api/tax-preview/batch
Content-Type: application/json

Este endpoint não requer autenticação. É protegido por rate limit de 30 requisições / 60s por IP.

Parâmetros

{
  "tenantSlug": "demo",
  "items": [
    {
      "year": 2027,
      "unitPrice": 4500,
      "ncm": "2202.10.00"
    }
  ]
}

Campo	Tipo	Descrição
tenantSlug	string	Slug do tenant ativo (retorna 404 se inativo ou inexistente)
items	array (máx. 50)	Itens para cálculo — limitado por @ArrayMaxSize(50)
items[].year	number	Ano-calendário (define a fase IBS/CBS pela EC 132/2023)
items[].unitPrice	number	Preço unitário em centavos
items[].ncm	string	NCM do produto (8 dígitos)

Resposta

[
  {
    "year": 2027,
    "unitPrice": 4500,
    "ncm": "2202.10.00",
    "ibs": { "aliquot": 0.0012, "base": 4500, "value": 5 },
    "cbs": { "aliquot": 0.0108, "base": 4500, "value": 49 },
    "totalTaxValue": 54,
    "effectiveRate": 0.012,
    "foodserviceReductionApplied": true
  }
]

Controles de segurança

Controle	Valor	Mecanismo
Rate limit	30 req / 60s por IP	@Throttle do NestJS Throttler
Tamanho do lote	máx. 50 itens	@ArrayMaxSize(50) no DTO
Tenant válido	Deve estar ativo	TenantsService.findBySlug() + verificação tenant.active

Arquivos

• backend/src/tax-engine/tax-preview.controller.ts
• backend/src/tax-engine/tax-preview.dto.ts

---

Endpoint Autenticado: Tax Determine

POST /t/:slug/admin/tax/determine

Requer JwtAuthGuard + TenantGuard. Aplica o cálculo completo para um item com contexto fiscal completo (regime tributário, CFOP, origem/destino UF, etc.).

Resultado

{
  icms: { aliquot, base, value, cstOrCsosn },
  ibs:  { aliquot, base, value },
  cbs:  { aliquot, base, value },
  pis:  { aliquot, base, value },
  cofins: { aliquot, base, value },
  totalTax: number,
  effectiveRate: number,
  metadata: {
    ncm, cest?, origemUf, destinoUf, operacao, regime,
    reformaInVigor: boolean,
    warnings: string[]
  }
}

---

Cronograma IBS/CBS — EC 132/2023

O serviço usa a tabela TAX_PERIODS em backend/src/tax-engine/rules/tax-period.config.ts para determinar as alíquotas por ano:

Ano	CBS	IBS	Período-teste
≤ 2025	0%	0%	—
2026	0,9%	0,1%	Sim
2027	1,8%	0,2%	Não
2029	7,9%	5,0%	Não
2030	7,9%	10,0%	Não
2031	7,9%	15,0%	Não
2032	7,9%	19,2%	Não
2033+	8,8%	19,2%	Não

Redução foodservice: fator 0.60 (40% de redução) aplicado em todos os anos com reforma ativa, conforme LC 214/2024, Art. 9º, para restaurantes e serviços de alimentação.

---

Validador cClassTrib

O endpoint GET /t/:slug/admin/tax/cclass-trib/:code?docType=nfe valida e descreve um código de Classificação Tributária NT 2025.002.

Serviço: TaxEngineService.validateCClassTrib(code, docType) via backend/src/tax-engine/rules/cclass-trib-validator.ts

Tabela de dados: backend/src/tax-engine/data/cclass-trib-table.json

---

Relacionados

• Fiscal / NF-e — Módulo fiscal, grupos fiscais, NT 2025.002
• Reforma Tributária IBS/CBS — Tabela completa de alíquotas
• Guia: Inutilização