IBPT API / Alíquotas

Endpoints da API

Base URL:

Arquivos de dados usam extensão .json.gz (gzip). Índices usam .json (sem compressão).

• GET
  /api/meta.json

  Metadados: anos disponíveis, versões/tabelas, tipos e UFs.
• GET
  /api/{ano}/index.json

  Índice do ano com todas as versões. Ex: /api/2026/index.json
• GET
  /api/{ano}/{tabela}/index.json

  Índice de uma versão/tabela. Ex: /api/2026/26.1.F/index.json
• GET
  /api/{ano}/{tabela}/{tipo}/index.json

  Índice por tipo com contagem por UF. Ex: /api/2026/26.1.F/ncm/index.json
• GET
  /api/{ano}/{tabela}/{tipo}/{uf}.json.gz

  Dados completos (gzip). Ex: /api/2026/26.1.F/ncm/SP.json.gz
• GET
  /api/todos.csv.gz

  CSV consolidado com todos os registros (gzip). Usado para consultas amplas.

Formato de Resposta

{
  "tabela": "26.1.F",
  "dados": [
    {
      "codigo": "01012100",
      "excecao": "",
      "descricao": "Cavalos reprodutores,de raca pura",
      "aliquotaNacionalFederal": 13.45,
      "aliquotaImportadosFederal": 15.45,
      "aliquotaEstadual": 18.00,
      "aliquotaMunicipal": 0.00,
      "vigenciaInicio": "20/02/2026",
      "vigenciaFim": "31/03/2026"
    }
  ]
}

Descompressão

// JavaScript
const resp = await fetch('/api/2026/26.1.F/ncm/SP.json.gz');
const fluxo = resp.body.pipeThrough(new DecompressionStream('gzip'));
const dados = JSON.parse(await new Response(fluxo).text());
dados.dados.forEach(item =>
  console.log(`${item.codigo}: ${item.aliquotaNacionalFederal}%`)
);

# cURL
curl -s URL/api/2026/26.1.F/ncm/SP.json.gz | gunzip | jq '.dados | length'

# Python
import requests, gzip, json
resp = requests.get('URL/api/2026/26.1.F/nbs/MG.json.gz')
dados = json.loads(gzip.decompress(resp.content))
for item in dados['dados']:
    print(f'{item["codigo"]}: {item["aliquotaNacionalFederal"]}%')

Informações

Como Funciona

• Construção: Script TypeScript extrai ZIPs, lê CSVs via streaming, agrupa por ano/versão/tipo/UF, gera JSON descritivo e comprime com gzip nível 9.
• Publicação: GitHub Actions executa o build a cada push e publica no GitHub Pages.
• Consulta: Página interativa (client-side) ou acesso direto aos endpoints via fetch/cURL/Python.

Compressão

Dados originais: ~1.7 GB. Após gzip nível 9: ~314 MB (82% de redução).

• Dados: .json.gz (comprimidos)
• Índices: .json (sem compressão)
• Browser: DecompressionStream('gzip') — nativo (Chrome 80+, Firefox 113+, Safari 16.4+)

Pesquisa Client-Side

1. Metadados carregados ao abrir a página (anos, versões, UFs, tipos).
2. 8 filtros disponíveis: ano, versão, UF, tipo, código, descrição, vigência início e vigência fim.
3. Filtros de vigência permitem buscar registros válidos em um período específico.
4. Arquivos buscados em lotes paralelos de 8, descomprimidos com DecompressionStream.
5. Consultas amplas (>50 arquivos) usam o CSV consolidado todos.csv.gz via streaming.
6. Resultados em tabela com 12 colunas (incluindo vigência), paginados (100/página), ordenáveis, exportáveis como CSV.

Tipos de Dados

• NCM Nomenclatura Comum do Mercosul — Produtos, 8 dígitos, ~11.000/UF
• NBS Nomenclatura Brasileira de Serviços — Serviços, 9 dígitos, ~860/UF
• LC116 Lei Complementar 116 — Serviços municipais, 4 dígitos, ~200/UF

Claude Code

Este projeto inclui arquivos de configuração para o Claude Code:

• CLAUDE.md — Guia com estrutura, convenções e comandos do projeto
• .claude/rules/ — Regras automáticas de nomenclatura e padrões
• .claude/skills/ — Skills personalizadas (ex: VALRAW UI)

Licença

Código fonte de uso livre (Apache 2.0). Qualquer pessoa pode baixar, modificar, distribuir e comercializar sem restrições.

Dados: IBPT / empresometro.com.br