RTC/Gov calculator

✅ Available in development and UAT. Production is still pending the pre-production security review (DFE-2796, in progress) and the cut of the release-proxy-vX.Y.Z tag.

Exposes the government's RTC Calculator (Reforma Tributária sobre o Consumo, the Brazilian consumption tax reform — IBS, CBS and IS) to external customers, through an integration application that talks to the official calculator. The calculation is passed through byte for byte; the service adds authentication, product control, caching and limits.

Base URLCopy Anchor Link

API ReferenceCopy Anchor Link

Full interactive reference (Scalar): API reference.

AuthenticationCopy Anchor Link

OAuth2 JWT token obtained via client_credentials (application token), in the Authorization: Bearer {token} header. See Authentication and Authorization.

Access requirements, in addition to a valid token:

• Realm role RTC_INTEGRATION_API granted to the client.
• RTC Calculator product enabled for the customer.
• The customer is resolved from the token's customer-id claim — do not send the X-Customer-ID header.
• The companyId in the body must belong to the authenticated customer.

Content-type: application/vnd.materimperium.api.v1+json (standard envelope — see REST APIs).

EndpointsCopy Anchor Link

Prefix: /api/integration/dfe/rtc/calculadora. The {model} path variable is 55 (NF-e) or 65 (NFC-e).

POST /{model}/regime-geralCopy Anchor Link

Calculates the RTC taxes (general regime) for a set of items.

Interactive reference: API reference

Query params

Body (request)

⚠️ Although cst and cClassTrib are marked as optional in the schema, the government calculator currently rejects (400 TAX_CALCULATION_ERROR) requests without both filled in. Always send both.

Response 200 — standard envelope with data:

Example (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"
    }
  ]
}

Example (response), with calculo captured live:

{
  "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" }
          }
        }
      }
    }
  }
}

The IBS/CBS rates in the example above (0.10% / 0.90%) reflect the 2026 test period of the Brazilian tax reform (LC 214/2025) — they are not the full reference rates, which increase gradually until 2033.

GET /{model}/versaoCopy Anchor Link

Returns the current calculator version (served from cache). Same authentication, same product gate, and it counts toward the customer's quota.

Interactive reference: API reference

Query params: versao (optional, same as the endpoint above).

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

Version, cache and quota semanticsCopy Anchor Link

• Version selection: ?versao= is optional (default latest); it allows calculating against older databases. A version outside the configured whitelist → 400 INVALID_CALCULATOR_VERSION. Currently the whitelist only has latest deployed in all three environments.
• Response cache: identical responses (same customer, model, target version and payload) are served from cache for up to 60s. The cache is internal to the application and cannot be controlled by the customer (no status header or bypass). If dataHoraEmissao is omitted, "now" may reflect up to one TTL ago — anyone who needs determinism should provide the date explicitly.
• Quota / limits: per-customer quota (429 RATE_LIMITED, with Retry-After) — every request counts, including GET /versao and responses served from cache. There is also upstream concurrency protection (429 CONCURRENCY_LIMITED).

Message languageCopy Anchor Link

Resolved via Accept-Language: pt-BR (default), en-US, es-ES.

Error CodesCopy Anchor Link

Errors follow the standard ApiError envelope (see REST APIs); the code field is the stable identifier for the integrator to branch on. Authentication codes (401, and the 403 for insufficient scope) arrive in the same envelope, but are emitted by the security layer before the controller — which is why they do not appear in the declared responses of the OpenAPI spec.

ChangelogCopy Anchor Link

[1.0.0] — 2026-09-02Copy Anchor Link

Added

• POST /{model}/regime-geral — calculation of RTC taxes (general regime).
• GET /{model}/versao — current calculator version.

Available in development and UAT; production expected after DFE-2796 is closed and the release-proxy-v* tag is cut.

[Unreleased]Copy Anchor Link

Added

• Real example of calculo (pass-through payload from the government Calculator, engine v0043) in the endpoints section, and a note that cst/cClassTrib are required in practice by the government engine despite being optional in the schema.

Reconciled with the service in development and UAT. Last review: 2026-09-08 (mi-dev-portal-doc — DFE-2852).