← HomeFleetPay / API

Create a tax rule

Parameters, data structure and responses from the versioned contract.

POST/fiscal/regras-tributacao

createFiscalTaxRuleSandbox Base: https://api.fleetpay.site/v1

Technical descriptions are translated from the versioned contract. Original identifiers and JSON are preserved; data examples are omitted.

Creates a rule for the authenticated carrier — there is no company_id in the contract; scope always comes from the credential. The rule is authoritative across all issuance paths: the engine resolves it from the draft route, calculates ICMS, determines CFOP and reapplies everything at issuance. In POST /cte and PUT /cte/{cte_uuid}, a route without a rule returns 422 regra_tributaria_ausente, and the payload's icms block is replaced by the rule (only withheld tax substitution and presumed credit survive). For automatic CT-e issuance from NF-e and for counter-CT-e issuance, a route without a rule remains pending with sem_regra_tributacao.

There is no update method: to correct a rule, create a new one with its validity period and delete the old one.

Optional tp_serv restricts the rule to a service type (ide/tpServ: 0 normal, 1 subcontracting, 2 onward carriage, 3 intermediate onward carriage). A matching service-type rule takes precedence over any route-only rule. It lets the carrier declare each type's tax treatment (for example, 5360 + ICMS45/CST 51 for subcontracting, 5351 + normal ICMS for onward carriage) without changing route rules. Without a type-specific rule, counter-CT-e follows the previous behavior (5360/6360, or 5932/6932 when the service starts in another state).

The six IBS/CBS fields (Tax Reform, LC 214/2025) are optional but form a block: supplying any of the three rates makes the rule govern all three, with omitted rates treated as zero. In 2026, the test year, the law fixes the rates (IBS 0,10% and CBS 0,90%), and CT-e already displays them without configuration; from 2027, a route without an IBS/CBS rule has CT-e issuance rejected before submission.

Authentication

[
  {
    "oauth2": []
  },
  {
    "chaveApi": []
  }
]

Availability depends on the environment, enabled scopes and provider. This reference does not execute requests or collect credentials.

Parameters

No parameters declared for this operation.

Request Body

Required

`application/json`

FiscalTaxRuleCreate ↗

origin_statestring | nullOptional

Origin state; null (or omitted) means any origin.

minLength2

maxLength2

destination_statestring | nullOptional

Destination state; null (or omitted) means any destination.

minLength2

maxLength2

tp_servinteger | nullOptional

Service type (ide/tpServ) to which the rule applies; null (or omitted) = any type. 0 normal, 1 subcontracting, 2 onward carriage, 3 intermediate onward carriage; 4 (multimodal) is not accepted. A rule matching the service type takes precedence over any route-only rule.

0 · 1 · 2 · 3 · null

cfopstring | nullRequired

Required. CFOP recorded by the engine for the service. For counter-CT-e documents using a rule without tp_serv, only the operation digit (5xxx/6xxx) is taken from it; the final code comes from the route (5360/6360 or 5932/6932). With a type-specific rule, its CFOP is retained when the service starts in the issuer's state (the mandatory 5932/6932 still applies when the service starts in another state).

pattern"^\\d{4}$"

icms_varianteobjectRequired

FiscalTaxRuleIcmsVariant ↗

cststring | nullOptional

Only for ICMS45, where it is required (40, 41 or 51). For other variants, this field is ignored — the server derives the CST from the variant (ICMS00→00, ICMS20→20, ICMS60→60, ICMS90/ICMSOutraUF/ICMSSN→90).

"40" · "41" · "51" · null

aliquotanumber | null · doubleOptional

ICMS rate. Required for ICMS00, ICMS20, ICMS90 and ICMSOutraUF; prohibited for ICMS45, ICMS60 and ICMSSN.

minimum0

maximum100

p_red_bcnumber | null · doubleOptional

ICMS tax-base reduction percentage. Required for ICMS20, ICMS90 and ICMSOutraUF; prohibited for other variants.

minimum0

maximum100

ibs_cbs_cststring | nullOptional

IBS/CBS CST with 3 digits, e.g. 000 for full taxation. Do not confuse it with the 2-digit ICMS cst: they use different vocabularies.

pattern"^\\d{3}$"

ibs_cbs_class_tribstring | nullOptional

IBS/CBS tax classification, with 6 digits — e.g. 000001.

pattern"^\\d{6}$"

ibs_uf_aliquotanumber | null · doubleOptional

State IBS tax rate, as a percentage, with up to 4 decimal places.

minimum0

maximum100

ibs_mun_aliquotanumber | null · doubleOptional

Municipal IBS tax rate, as a percentage, with up to 4 decimal places.

minimum0

maximum100

cbs_aliquotanumber | null · doubleOptional

CBS tax rate, as a percentage, with up to 4 decimal places.

minimum0

maximum100

ibs_cbs_p_red_bcnumber | null · doubleOptional

IBS/CBS tax-base reduction percentage, with up to 4 decimal places. Applied before tax rates.

minimum0

maximum100

valid_fromstring | null · dateOptional

valid_untilstring | null · dateOptional

Cannot be earlier than valid_from.

notesstring | nullOptional

maxLength255

Responses

201 HTTP Response

Rule created for the authenticated carrier, with cst and icms_variante_rotulo already derived.

`application/json`

FiscalTaxRuleEnvelope ↗

dataobjectRequired

Internal failure without operational integration details.

`application/json`

ErrorEnvelope ↗

errorobjectRequired

ErrorBody ↗

Headers

X-Request-Id

Call correlation identifier.

Complete Operation Definition

{
  "tags": [
    "Regras de tributação"
  ],
  "summary": "Criar regra de tributação",
  "operationId": "createFiscalTaxRule",
  "description": "Cria uma regra para a transportadora autenticada — não existe `company_id` no contrato;\no escopo é sempre o da credencial. A regra é a autoridade em todos os caminhos de\nemissão: o motor resolve a regra pela rota do rascunho, calcula o ICMS, decide o CFOP\ne reaplica tudo na emissão. Em `POST /cte` e `PUT /cte/{cte_uuid}` a rota sem regra\nresponde `422` `regra_tributaria_ausente`, e o bloco `icms` do payload é substituído\npela regra (só sobrevivem ST retido e crédito presumido); no CT-e automático a partir\nda NF-e e no contra-CT-e a rota sem regra fica pendente com `sem_regra_tributacao`.\n\nNão há verbo de update: para corrigir, crie a regra nova (com a vigência dela) e remova\na antiga.\n\n`tp_serv` (opcional) restringe a regra a um tipo de serviço (`ide/tpServ`: 0 normal,\n1 subcontratação, 2 redespacho, 3 redespacho intermediário). Regra com tipo casado vence\nqualquer regra só de rota, e é por ela que a transportadora declara o regime de cada tipo\n(ex.: `5360` + `ICMS45`/CST `51` para a subcontratação, `5351` + ICMS normal para o\nredespacho) sem mexer nas regras de rota. Sem regra do tipo, o contra-CT-e segue o\ncomportamento anterior (`5360`/`6360`, ou `5932`/`6932` quando a prestação começa em\noutra UF).\n\nOs seis campos de IBS/CBS (Reforma Tributária, LC 214/2025) são opcionais, mas formam um\nbloco: informar qualquer uma das três alíquotas faz a regra responder pelas três, e as\ndeixadas em branco valem zero. Em 2026, o ano-teste, a lei fixa os percentuais (IBS\n0,10% e CBS 0,90%) e o CT-e já os destaca sem cadastro; a partir de 2027 a rota sem\nregra de IBS/CBS tem a emissão do CT-e recusada antes do envio.\n",
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/FiscalTaxRuleCreate"
        }
      }
    }
  },
  "responses": {
    "201": {
      "$ref": "#/components/responses/FiscalTaxRuleCreated"
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "422": {
      "$ref": "#/components/responses/ValidationFailed"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    },
    "500": {
      "$ref": "#/components/responses/InternalError"
    }
  },
  "method": "POST",
  "path": "/fiscal/regras-tributacao",
  "parameters": []
}