API e MCP da Reforma Tributária

Calcule CBS, IBS e Imposto Seletivo (LC 214/2025), consulte as tabelas oficiais, gere e valide XML e DANFSe a partir do seu sistema ou do seu agente de IA.

URL base
https://rtc.pedidofacil.cloud/api/v1
Servidor MCP
https://rtc.pedidofacil.cloud/mcp
Especificação
openapi.json · referência

Os cálculos são feitos pelos motores de código aberto publicados pela Receita Federal (calculadora-rtc-regime-regular, calculadora-rtc-simples-nacional e calculadora-rtc-gerador-danfse), executados nos nossos servidores. Os formatos de entrada e saída são os mesmos das calculadoras oficiais; trocamos apenas o endereço e acrescentamos autenticação, limites e registro de uso.

Acesso à API: planos Profissional e Completo (e durante o teste grátis). MCP: plano Completo e teste grátis.

Autenticação

Crie uma chave no painel, menu API e MCP. Ela aparece uma única vez; guarde num cofre de segredos. Envie em todas as chamadas:

Authorization: Bearer rtc_1a2b3c4d_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Também aceitamos o cabeçalho X-API-Key. Chaves podem ser revogadas a qualquer momento pelo painel. Nunca use a chave em código que roda no navegador do usuário final.

Respostas e erros

Respostas de sucesso seguem o formato da calculadora oficial. Erros da plataforma vêm como {"erro": "mensagem"}; erros de validação dos motores mantêm o formato original (com códigos como REG-011 ou VSN-001).

HTTPSignificado
200Sucesso. No cálculo com observabilidade, confira o estadoItem de cada item: CALCULADO, CALCULO_SIMULADO, INCONSISTENCIA_ENTRADA, NAO_IMPLEMENTADO ou FALHA_TECNICA.
400JSON/XML malformado ou entrada recusada pelo motor.
401Chave ausente, inválida ou revogada.
402Teste grátis encerrado ou assinatura inativa.
403Recurso fora do seu plano.
404Rota inexistente.
413Corpo maior que o permitido (JSON 1 MB, XML 2 MB).
422Regra de negócio violada (ex.: modo estrito com item inválido).
429Limite por minuto ou franquia do mês atingidos (veja Retry-After).
502/503Motor de cálculo indisponível. Tente de novo em instantes.

Avisos dos motores chegam em cabeçalhos x-warning-* (ex.: x-warning-dados-simulados quando as alíquotas foram informadas por você).

Limites e franquias

  • Por chave: 60 requisições por minuto (padrão).
  • Cálculos por mês: todas as chamadas POST (painel, API e MCP somados), conforme o plano.
  • Chamadas de API/MCP por mês: conforme o plano. Consultas (GET) não consomem cálculos.

Regime geral (CBS, IBS e IS)

Prefixo /api/v1/regime + o caminho da calculadora oficial sem /calculadora.

POST /api/v1/regime/observabilidade/regime-geral

Calcula a operação item a item; itens com erro não interrompem os demais. A partir de 2027, aliquotasNominais é obrigatório em cada item; em 2026 é proibido (vale a alíquota de teste).

curl -X POST https://rtc.pedidofacil.cloud/api/v1/regime/observabilidade/regime-geral \
  -H "Authorization: Bearer $RTC_CHAVE" -H "Content-Type: application/json" \
  -d '{
  "id": "6194602e", "versao": "1.0.0",
  "dhFatoGerador": "2027-03-10T10:00:00-03:00",
  "municipio": 4314902, "uf": "RS",
  "itens": [
    { "numero": 1, "ncm": "10063021", "cst": "200", "cClassTrib": "200003",
      "baseCalculo": 100.00, "quantidade": 20, "unidade": "KG",
      "aliquotasNominais": { "cbs": 8.8, "ibsEstadual": 0.05, "ibsMunicipal": 0.05 } },
    { "numero": 2, "nbs": "122011200", "cst": "200", "cClassTrib": "200028",
      "baseCalculo": 1200.00,
      "aliquotasNominais": { "cbs": 8.8, "ibsEstadual": 0.05, "ibsMunicipal": 0.05 } }
  ]}'

Resposta (resumida):

{
  "objetos": [
    { "nObj": 2, "estadoItem": "CALCULO_SIMULADO",
      "tribCalc": { "IBSCBS": { "CST": "200", "cClassTrib": "200028", "gIBSCBS": {
        "vBC": "1200.00",
        "gIBSUF":  { "pIBSUF": "0.05", "gRed": { "pRedAliq": "60.00", "pAliqEfet": "0.02" }, "vIBSUF": "0.24" },
        "gIBSMun": { "pIBSMun": "0.05", "gRed": { "pRedAliq": "60.00", "pAliqEfet": "0.02" }, "vIBSMun": "0.24" },
        "vIBS": "0.48",
        "gCBS":    { "pCBS": "8.80", "gRed": { "pRedAliq": "60.00", "pAliqEfet": "3.52" }, "vCBS": "42.24" } },
        "memoriaCalculo": { "cbs": "Operação de consumo com enquadramento legal em Art. 129…" } } } }
  ],
  "total": { "tribCalc": { "IBSCBSTot": { "vBCIBSCBS": "1300.00", "gIBS": { "vIBS": "…" }, "gCBS": { "vCBS": "…" } } } }
}

POST /api/v1/regime/regime-geral

Modo estrito: a operação inteira falha (HTTP 422) no primeiro erro. É a resposta usada para gerar o XML.

GET /api/v1/regime/observabilidade/erros?codigo=REG-011

Descrição de um código de erro.

Outras operações

  • POST /api/v1/regime/pedagio — cálculo de pedágio.
  • POST /api/v1/regime/base-calculo/cbs-ibs-mercadorias e /is-mercadorias.
  • GET /api/v1/regime/nfse/... — indicador de operação, locais de incidência e fornecimento, classificações por NBS.

Simples Nacional

POST /api/v1/simples/observabilidade/simples-nacional/nao-assistido

Cálculo para todos os documentos (NT 2026.005), a partir da linha de alíquotas efetivas do contribuinte.

curl -X POST https://rtc.pedidofacil.cloud/api/v1/simples/observabilidade/simples-nacional/nao-assistido \
  -H "Authorization: Bearer $RTC_CHAVE" -H "Content-Type: application/json" \
  -d '{
  "id": "op-2", "versao": "3.0.0", "data": "2027-03-15", "tpDoc": "55", "CRT": "1",
  "aliquotasEfetivas": { "fatorR": true, "impedimentoSublimite": false,
                         "anexoI": { "pCBSSN": "1.1612", "pIBSSN": "0.0129" } },
  "itens": [{ "numero": 1, "cAtivSN": "01", "cClassTrib": "000001",
              "baseCalculo": "1000.00", "valorImpostoSeletivo": "0.00" }]
}'
  • GET /api/v1/simples/simples-nacional/atividades?data=2027-01-01&anexos=I,III — atividades vigentes.
  • GET /api/v1/simples/simples-nacional/atividades/{codigo}?data=… — uma atividade.
  • GET /api/v1/simples/observabilidade/simples-nacional/erros?codigo=VSN-001 — descrição de erro.
  • GET /api/v1/simples/versao — versão do motor e da base.

Base de cálculo unificada

POST /api/v1/regime/base-calculo/base-calculo-unificada

{ "anoFatoGerador": 2027, "tipoDocumento": 55, "natureza": "bem",
  "vProd": 1000.00, "vFrete": 50.00, "vSeg": 20.00, "vOutro": 10.00, "vDesc": 50.00,
  "vIS": 30.00, "vPIS": 9.25, "vCOFINS": 46.25, "vICMS": 180.00, "vFCP": 10.00 }
→ { "baseRG": 870.00, "baseIS": 840.00, "baseSN": 1060.00, "avisos": ["Campo vPIS não compõe as bases para o ano 2027…"] }

NFS-e (experimental): POST /api/v1/regime/base-calculo/base-calculo-unificada-nfse.

Tabelas oficiais (dados abertos)

Todas em GET /api/v1/regime/dados-abertos/…. As datas seguem AAAA-MM-DD e definem a vigência consultada.

/situacoes-tributarias/cbs-ibs?data=CSTs com suas classificações (cClassTrib)
/classificacoes-tributarias/cbs-ibs/class-trib/{cClassTrib}?data=Detalhe de uma classificação
/classificacoes-tributarias/ncm-aplicavel?ncm=&cClassTrib=&data=NCM pode usar o cClassTrib?
/classificacoes-tributarias/nbs-aplicavel?nbs=&cClassTrib=&data=NBS pode usar o cClassTrib?
/ncm?ncm=&data= · /nbs?nbs=&data=Descrição de NCM e NBS
/fundamentacoes-legais?data=Fundamentação legal
/aliquota-uniao · /aliquota-uf?codigoUf= · /aliquota-municipio?codigoMunicipio=Alíquotas de referência (cadastradas para 2026)
/ufs · /ufs/municipios?siglaUf=UFs e municípios (códigos IBGE)
/versaoVersão do aplicativo e da base oficial

XML

POST /api/v1/regime/xml/generate?tipo=nfe

Corpo: a resposta de POST /api/v1/regime/regime-geral (modo estrito). Tipos: nfe, nfce, nfse, cte, cte-simplificado, bpe, bpe-tm, nf3e.

POST /api/v1/regime/xml/validate?tipo=nfe&subtipo=grupo

Corpo XML (Content-Type: application/xml). Retorna true ou HTTP 422 com linha e coluna do erro. subtipo: grupo ou nota. XML com DOCTYPE/entidades é recusado.

DANFSe

POST /api/v1/danfse?stc=0&canhoto=true

curl -X POST "https://rtc.pedidofacil.cloud/api/v1/danfse?stc=0&canhoto=true" \
  -H "Authorization: Bearer $RTC_CHAVE" -H "Content-Type: application/xml" \
  --data-binary @nfse.xml -o danfse.pdf

stc: 0 válida, 1 substituída, 2 cancelada. Disponível no plano Completo.

Conta e status

  • GET /api/v1/conta — plano, recursos liberados, franquia e uso do mês.
  • GET /api/v1/status — situação dos motores (sem autenticação, útil para monitoramento).

Servidor MCP: conectar um agente

Endereço https://rtc.pedidofacil.cloud/mcp (transporte Streamable HTTP), autenticado com a mesma chave da API.

Claude Desktop, Cursor, VS Code e outros (JSON)

{
  "mcpServers": {
    "rtc-pro": {
      "type": "http",
      "url": "https://rtc.pedidofacil.cloud/mcp",
      "headers": { "Authorization": "Bearer rtc_SUA_CHAVE" }
    }
  }
}

Claude Code

claude mcp add --transport http rtc-pro https://rtc.pedidofacil.cloud/mcp --header "Authorization: Bearer rtc_SUA_CHAVE"

Clientes que só falam stdio

npx -y mcp-remote https://rtc.pedidofacil.cloud/mcp --header "Authorization: Bearer rtc_SUA_CHAVE"

Ferramentas MCP

calcular_regime_geralCBS, IBS e IS de uma operação (modo observabilidade ou estrito)
calcular_simples_nacionalCBS e IBS no Simples Nacional (não assistido)
calcular_base_unificadaBases RG, IS e SN de NF-e/NFC-e ou NFS-e
consultar_tabelaQualquer tabela de dados abertos (CST, cClassTrib, NCM, NBS, alíquotas…)
atividades_simples_nacionalAtividades do Simples vigentes ou por código
explicar_erroSignificado de REG-xxx / VSN-xxx
gerar_xml / validar_xmlGrupos de tributação e validação XSD
gerar_danfsePDF do DANFSe (retornado como recurso base64)
consultar_contaPlano, franquia e uso

Exemplo de pedido ao agente: “Qual a CBS e o IBS de uma venda de 20 kg de arroz (NCM 10063021) por R$ 100 em Porto Alegre em março de 2027, com alíquotas de 8,8% e 0,05%?”

Protocolo

JSON-RPC 2.0 sobre POST /mcp, respostas em application/json (sem SSE e sem sessão). Versões aceitas: 2025-11-25, 2025-06-18, 2025-03-26 e 2024-11-05. Métodos: initialize, ping, tools/list, tools/call. Requisições do navegador só são aceitas com Origin do próprio domínio.

curl -X POST https://rtc.pedidofacil.cloud/mcp -H "Authorization: Bearer $RTC_CHAVE" -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Exemplos de código

PHP

$ch = curl_init('https://rtc.pedidofacil.cloud/api/v1/regime/observabilidade/regime-geral');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('RTC_CHAVE'), 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode($operacao),
]);
$resultado = json_decode(curl_exec($ch), true);
foreach ($resultado['objetos'] as $item) {
    echo $item['nObj'], ': ', $item['estadoItem'], PHP_EOL;
}

Python

import os, requests
r = requests.post("https://rtc.pedidofacil.cloud/api/v1/regime/observabilidade/regime-geral",
                  headers={"Authorization": f"Bearer {os.environ['RTC_CHAVE']}"},
                  json=operacao, timeout=60)
r.raise_for_status()
total = r.json()["total"]["tribCalc"]["IBSCBSTot"]
print("CBS:", total["gCBS"]["vCBS"], "IBS:", total["gIBS"]["vIBS"])

JavaScript (Node.js)

const r = await fetch("https://rtc.pedidofacil.cloud/api/v1/regime/observabilidade/regime-geral", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.RTC_CHAVE}`, "Content-Type": "application/json" },
  body: JSON.stringify(operacao),
});
if (!r.ok) throw new Error((await r.json()).erro);
const dados = await r.json();

Boas práticas

  • Uma chave por sistema/ambiente; revogue as que não usa.
  • Guarde a chave em variável de ambiente ou cofre; nunca em repositório ou no front-end.
  • Trate HTTP 429 com espera exponencial e respeite Retry-After.
  • No modo observabilidade, sempre verifique o estadoItem: a resposta é 200 mesmo com itens inválidos.
  • O conteúdo das operações não é armazenado; guarde no seu sistema o que precisar para auditoria.

Ferramenta de apoio baseada nas calculadoras oficiais da Receita Federal (licença MIT). Não substitui a orientação de um profissional de contabilidade.