Calculadora RTC/Gov

✅ Disponível em desenvolvimento e UAT. A produção segue pendente da revisão de segurança pré-produção (DFE-2796, em andamento) e do corte da tag release-proxy-vX.Y.Z.

Expõe a Calculadora RTC (Reforma Tributária sobre o Consumo — IBS, CBS e IS) do governo a clientes externos, por uma aplicação de integração que fala com a calculadora oficial. O cálculo é repassado byte a byte; o serviço adiciona autenticação, controle de produto, cache e limites.

Base URLCopiar link da seção

API ReferenceCopiar link da seção

Referência interativa completa (Scalar): referência de API.

AutenticaçãoCopiar link da seção

Token JWT OAuth2 obtido por client_credentials (token de aplicação), no header Authorization: Bearer {token}. Ver Autenticação e Autorização.

Requisitos de acesso, além do token válido:

• Role de realm RTC_INTEGRATION_API concedida ao client.
• Produto Calculadora RTC habilitado para o customer.
• O customer é resolvido pelo claim customer-id do token — não enviar header X-Customer-ID.
• A companyId do corpo deve pertencer ao customer autenticado.

Content-type: application/vnd.materimperium.api.v1+json (envelope padrão — ver APIs Rest).

EndpointsCopiar link da seção

Prefixo: /api/integration/dfe/rtc/calculadora. O path variable {model} é 55 (NF-e) ou 65 (NFC-e).

POST /{model}/regime-geralCopiar link da seção

Calcula os tributos RTC (regime geral) de um conjunto de itens.

Referência interativa: referência de API

Query params

Corpo (request)

⚠️ Embora cst e cClassTrib estejam marcados como opcionais no schema, a calculadora do governo hoje rejeita (400 TAX_CALCULATION_ERROR) requisições sem os dois preenchidos. Envie sempre ambos.

Resposta 200 — envelope padrão com data:

Exemplo (request):

POST /api/integration/dfe/rtc/calculadora/55/regime-geral?versao=latest
Content-Type: application/json
Authorization: Bearer $TOKEN

{
  "companyId": "6f1c1a3e-2d5b-4f0a-9c0d-8b4f2a1c9e77",
  "dataHoraEmissao": "2026-05-10T08:15:30-03:00",
  "municipio": 3550308,
  "uf": "SP",
  "itens": [
    {
      "numero": 1,
      "ncm": "84713012",
      "cst": "000",
      "baseCalculo": 1000.00,
      "quantidade": 1.0,
      "unidade": "UN",
      "cClassTrib": "000001"
    }
  ]
}

Exemplo (resposta), com calculo capturado ao vivo:

{
  "code": "0",
  "message": "",
  "success": true,
  "data": {
    "versaoApp": "1.0.18",
    "versaoDb": "v0041",
    "descricaoVersaoDb": "Base de alíquotas 2026",
    "dataVersaoDb": "2026-01-15",
    "ambiente": "PRODUCAO",
    "calculo": {
      "objetos": [
        {
          "nObj": 1,
          "tribCalc": {
            "IBSCBS": {
              "CST": "000",
              "cClassTrib": "000001",
              "gIBSCBS": {
                "vBC": "1000.00",
                "gIBSUF": { "pIBSUF": "0.10", "vIBSUF": "1.00", "memoriaCalculo": "Operação de consumo com enquadramento legal em LC 214/2025, tributada conforme Tributação integral. A base de cálculo utilizada é de R$ 1000.00000000, com alíquota de 0.100000%." },
                "gIBSMun": { "pIBSMun": "0.00", "vIBSMun": "0.00", "memoriaCalculo": "Operação de consumo com enquadramento legal em LC 214/2025, tributada conforme Tributação integral. A base de cálculo utilizada é de R$ 1000.00000000, com alíquota de 0.000000%." },
                "vIBS": "1.00",
                "gCBS": { "pCBS": "0.90", "vCBS": "9.00", "memoriaCalculo": "Operação de consumo com enquadramento legal em LC 214/2025, tributada conforme Tributação integral. A base de cálculo utilizada é de R$ 1000.00000000, com alíquota de 0.900000%." }
              }
            }
          }
        }
      ],
      "total": {
        "tribCalc": {
          "IBSCBSTot": {
            "vBCIBSCBS": "1000.00",
            "gIBS": {
              "gIBSUF": { "vDif": "0.00", "vDevTrib": "0.00", "vIBSUF": "1.00" },
              "gIBSMun": { "vDif": "0.00", "vDevTrib": "0.00", "vIBSMun": "0.00" },
              "vIBS": "1.00",
              "vCredPres": "0.00",
              "vCredPresCondSus": "0.00"
            },
            "gCBS": { "vDif": "0.00", "vDevTrib": "0.00", "vCBS": "9.00", "vCredPres": "0.00", "vCredPresCondSus": "0.00" },
            "gMono": { "vIBSMono": "0.00", "vCBSMono": "0.00", "vIBSMonoReten": "0.00", "vCBSMonoReten": "0.00", "vIBSMonoRet": "0.00", "vCBSMonoRet": "0.00" }
          }
        }
      }
    }
  }
}

As alíquotas de IBS/CBS no exemplo acima (0,10% / 0,90%) refletem o período de teste de 2026 da Reforma Tributária (LC 214/2025) — não são as alíquotas de referência plena, que sobem gradualmente até 2033.

GET /{model}/versaoCopiar link da seção

Retorna a versão vigente da calculadora (servida de cache). Mesma autenticação, mesmo gate de produto, e conta na cota do cliente.

Referência interativa: referência de API

Query params: versao (opcional, igual ao endpoint acima).

Resposta 200 — data: versaoApp, versaoDb, descricaoVersaoDb, dataVersaoDb, ambiente.

Semântica de versão, cache e cotaCopiar link da seção

• Seleção de versão: ?versao= é opcional (default latest); permite calcular contra bases antigas. Versão fora da whitelist configurada → 400 INVALID_CALCULATOR_VERSION. Hoje a whitelist só tem latest deployada nos três ambientes.
• Cache de resposta: respostas idênticas (mesmo cliente, modelo, versão-alvo e payload) são servidas de cache por até 60s. O cache é interno à aplicação e não é controlável pelo cliente (sem header de status nem bypass). Omitindo dataHoraEmissao, o "agora" pode refletir até um TTL atrás — quem precisa de determinismo informa a data explicitamente.
• Cota / limites: cota por customer (429 RATE_LIMITED, com Retry-After) — toda requisição conta, inclusive GET /versao e respostas servidas do cache. Há também proteção de concorrência do upstream (429 CONCURRENCY_LIMITED).

Idioma das mensagensCopiar link da seção

Resolução por Accept-Language: pt-BR (default), en-US, es-ES.

Error CodesCopiar link da seção

Erros seguem o envelope ApiError padrão (ver APIs Rest); o campo code é o identificador estável para o integrador ramificar. Os códigos de autenticação (401, e o 403 de escopo insuficiente) chegam no mesmo envelope, mas são emitidos pela camada de segurança antes do controller — por isso não aparecem nas responses declaradas do spec OpenAPI.

ChangelogCopiar link da seção

[1.0.0] — 2026-09-02Copiar link da seção

Added

• POST /{model}/regime-geral — cálculo de tributos RTC (regime geral).
• GET /{model}/versao — versão vigente da calculadora.

Disponível em desenvolvimento e UAT; produção prevista após o fechamento de DFE-2796 e o corte da tag release-proxy-v*.

[Unreleased]Copiar link da seção

Added

• Exemplo real de calculo (payload pass-through da Calculadora do governo, motor v0043) na seção de endpoints, e nota sobre cst/cClassTrib serem exigidos na prática pelo motor do governo apesar de opcionais no schema.

Reconciliado com o serviço em desenvolvimento e UAT. Última revisão: 2026-09-08 (mi-dev-portal-doc — DFE-2852).