Documentação da API
Referência técnica da API REST v1 da MeuTributo.App. Base URL: https://api.meutributo.app/v1
Introdução
A API MeuTributo.App permite consultar, calcular e simular tributos da Reforma Tributária (IBS, CBS e Imposto Seletivo) de forma programática. Todos os endpoints retornam JSON e utilizam versionamento por data de vigência.
Autenticação
Inclua sua API Key no header Authorization de todas as requisições. Obtenha sua chave no dashboard em Configurações → API.
Authorization: Bearer sk_live_abc123def456
Content-Type: application/jsonGET /v1/health
Verifica a saúde dos serviços e retorna latência por componente.
curl -X GET https://api.meutributo.app/v1/health \
-H "Authorization: Bearer sk_live_..."{
"status": "healthy",
"version": "1.4.0",
"timestamp": "2026-08-24T22:29:00Z",
"services": {
"api": { "status": "up", "latency_ms": 42 },
"ncm_engine": { "status": "up", "latency_ms": 78 },
"cclasstrib_engine": { "status": "up", "latency_ms": 56 },
"simulator": { "status": "up", "latency_ms": 35 },
"webhooks": { "status": "up", "latency_ms": 120, "queue_depth": 0 },
"database": { "status": "up", "latency_ms": 8 }
},
"uptime_30d": 99.92
}POST /v1/tax/calculate
Calcula a carga tributária total (IBS + CBS + Imposto Seletivo) para uma operação informada. Suporta versionamento por data de vigência.
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| ncm | string | Sim | Código NCM (8 dígitos) ou NBS |
| uf | string | Sim | Sigla da UF de destino (ex: SP, MG) |
| data | string (ISO 8601) | Sim | Data de vigência desejada (ex: 2027-01-01) |
| regime | string | Não | Regime diferenciado: padrao, reduzida, zero, isenta |
| valor | number | Não | Valor da operação para cálculo do tributo devido |
curl -X POST https://api.meutributo.app/v1/tax/calculate \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{"ncm": "2202.10.00", "uf": "SP", "data": "2027-01-01", "valor": 15000.00}'{
"cClassTrib": "000001",
"ibs": {
"aliquota": 0.1005,
"valor": 1507.50
},
"cbs": {
"aliquota": 0.0865,
"valor": 1297.50
},
"seletivo": {
"incide": true,
"aliquota": 0.02,
"valor": 300.00
},
"total": 3105.00,
"confidence": 0.98,
"sources": ["LC 214/2025, art. 12", "NT 2025.002 v1.10"]
}GET /v1/ncm/{code}
Retorna o tratamento tributário de um código NCM ou NBS, incluindo alíquotas de IBS e CBS, regime e fundamentação legal.
curl -X GET https://api.meutributo.app/v1/ncm/2202.10.00 \
-H "Authorization: Bearer sk_live_..."{
"ncm": "2202.10.00",
"descricao": "Águas, incluindo água mineral...",
"cClassTrib": "000001",
"ibs": { "aliquota": 0.1005, "regime": "padrao" },
"cbs": { "aliquota": 0.0865, "regime": "padrao" },
"seletivo": { "incide": false },
"fundamento": "LC 214/2025, Anexo I, cClassTrib 000001"
}GET /v1/cclasstrib/{code}
Consulta um código de classificação tributária (cClassTrib) e retorna alíquotas efetivas, CSTs compatíveis e regimes aplicáveis.
curl -X GET https://api.meutributo.app/v1/cclasstrib/000001 \
-H "Authorization: Bearer sk_live_..."{
"cClassTrib": "000001",
"descricao": "Operação padrão — bens e serviços comuns",
"ibs": { "aliquota": 0.1005, "regime": "padrao" },
"cbs": { "aliquota": 0.0865, "regime": "padrao" },
"csts": ["00", "01"],
"fundamento": "LC 214/2025, art. 12, I"
}POST /v1/simulate
Simula a carga tributária total ao longo da transição (2026–2033), considerando IBS, CBS, Imposto Seletivo e tributos legados.
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| base | number | Sim | Valor da base de cálculo |
| regime | string | Não | padrao, reduzida, cesta_basica, isenta |
| seletivo_categoria | string | Não | bebidas, fumo, veiculos, combustiveis, etc. |
| ano | integer | Sim | Ano de vigência entre 2026 e 2033 |
curl -X POST https://api.meutributo.app/v1/simulate \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{"base": 10000, "regime": "padrao", "seletivo_categoria": "nenhum", "ano": 2027}'{
"ano": 2027,
"fase": "transicao_2",
"ibs": {
"aliquota": 0.0565,
"valor": 565.00
},
"cbs": {
"aliquota": 0.0865,
"valor": 865.00
},
"seletivo": {
"incide": false,
"aliquota": 0,
"valor": 0
},
"legado": {
"icms": 440.00,
"iss": 0
},
"total": 1870.00
}Códigos de Erro
A API utiliza códigos HTTP padrão. Todos os erros retornam um objeto JSON com error e message.
| Código | Significado | Cenário típico |
|---|---|---|
| 400 | Bad Request | Parâmetro ausente ou formato inválido |
| 401 | Unauthorized | API Key ausente, inválida ou expirada |
| 404 | Not Found | NCM ou cClassTrib não encontrado |
| 422 | Unprocessable | Data de vigência fora do intervalo suportado |
| 429 | Too Many Requests | Limite de requisições excedido |
| 500 | Internal Server Error | Erro inesperado — notifique o suporte |
{
"error": "ncm_not_found",
"message": "NCM 9999.99.99 não encontrado na base vigente.",
"code": 404,
"request_id": "req_abc123"
}Webhooks
Configure webhooks no dashboard para receber eventos em tempo real. A MeuTributo.App envia POSTs para sua URL com um header X-Tributo-Signature para verificação de autenticidade.
{
"event": "norma.publicada",
"timestamp": "2026-08-24T18:00:00Z",
"data": {
"tipo": "NT",
"numero": "2025.002",
"versao": "v1.12",
"impacto_ncms": ["2202.10.00", "8711.20.00"],
"url": "https://meutributo.app/normas/nt-2025-002-v1-12"
}
}const crypto = require("crypto");
function verifySignature(payload, signature, secret) {
const expected = crypto
.createHmac("sha256", secret)
.update(payload)
.digest("hex");
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(expected)
);
}Rate Limits
Os limites de requisição variam por plano. Headers de rate limit são incluídos em todas as respostas:
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 842
X-RateLimit-Reset: "2026-08-25T00:00:00Z"| Plano | Requisições / mês | Burst / min |
|---|---|---|
| Starter | 10.000 | 120 |
| Pro | 50.000 | 300 |
| Business | 250.000 | 600 |
| Enterprise | Sob consulta | Sob consulta |
Precisa de ajuda?
Não encontrou o que procurava? Entre em contato com o suporte técnico ou consulte o changelog da API.