Criar regra de tributação

Parâmetros, estrutura de dados e respostas do contrato versionado.

POST/fiscal/regras-tributacao

createFiscalTaxRuleBase de Homologação: https://api.fleetpay.site/v1

Descrições técnicas preservadas do contrato versionado. Exemplos de dados foram omitidos da cópia pública.

Cria uma regra para a transportadora autenticada — não existe company_id no contrato; o escopo é sempre o da credencial. A regra é a autoridade em todos os caminhos de emissão: o motor resolve a regra pela rota do rascunho, calcula o ICMS, decide o CFOP e reaplica tudo na emissão. Em POST /cte e PUT /cte/{cte_uuid} a rota sem regra responde 422 regra_tributaria_ausente, e o bloco icms do payload é substituído pela regra (só sobrevivem ST retido e crédito presumido); no CT-e automático a partir da NF-e e no contra-CT-e a rota sem regra fica pendente com sem_regra_tributacao.

Não há verbo de update: para corrigir, crie a regra nova (com a vigência dela) e remova a antiga.

tp_serv (opcional) restringe a regra a um tipo de serviço (ide/tpServ: 0 normal, 1 subcontratação, 2 redespacho, 3 redespacho intermediário). Regra com tipo casado vence qualquer regra só de rota, e é por ela que a transportadora declara o regime de cada tipo (ex.: 5360 + ICMS45/CST 51 para a subcontratação, 5351 + ICMS normal para o redespacho) sem mexer nas regras de rota. Sem regra do tipo, o contra-CT-e segue o comportamento anterior (5360/6360, ou 5932/6932 quando a prestação começa em outra UF).

Os seis campos de IBS/CBS (Reforma Tributária, LC 214/2025) são opcionais, mas formam um bloco: informar qualquer uma das três alíquotas faz a regra responder pelas três, e as deixadas em branco valem zero. Em 2026, o ano-teste, a lei fixa os percentuais (IBS 0,10% e CBS 0,90%) e o CT-e já os destaca sem cadastro; a partir de 2027 a rota sem regra de IBS/CBS tem a emissão do CT-e recusada antes do envio.

Autenticação

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

A disponibilidade depende do ambiente, dos escopos habilitados e do provedor. Esta referência não executa chamadas nem recebe credenciais.

Parâmetros

Nenhum parâmetro declarado nesta operação.

Corpo da Requisição

Obrigatório

`application/json`

FiscalTaxRuleCreate ↗

origin_statestring | nullOpcional

UF de origem; null (ou omitido) = qualquer origem.

minLength2

maxLength2

destination_statestring | nullOpcional

UF de destino; null (ou omitido) = qualquer destino.

minLength2

maxLength2

tp_servinteger | nullOpcional

Tipo de serviço (ide/tpServ) a que a regra se aplica; null (ou omitido) = qualquer tipo. 0 normal, 1 subcontratação, 2 redespacho, 3 redespacho intermediário; o 4 (multimodal) não é aceito. Regra com tipo casado vence qualquer regra só de rota.

0 · 1 · 2 · 3 · null

cfopstring | nullObrigatório

Obrigatório. CFOP que o motor grava na prestação. Nos contra-CT-e com regra sem tp_serv só empresta o dígito de operação (5xxx/6xxx) e o código final vem da rota (5360/6360 ou 5932/6932); com regra do tipo, o CFOP dela é mantido quando a prestação começa na UF do emitente (o 5932/6932 de prestação iniciada em outra UF continua imposto).

pattern"^\\d{4}$"

icms_varianteobjectObrigatório

FiscalTaxRuleIcmsVariant ↗

cststring | nullOpcional

Só para ICMS45, e nela é obrigatório (40, 41 ou 51). Nas demais variantes o campo é ignorado — o CST é derivado da variante no servidor (ICMS00→00, ICMS20→20, ICMS60→60, ICMS90/ICMSOutraUF/ICMSSN→90).

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

aliquotanumber | null · doubleOpcional

Percentual do ICMS. Obrigatório em ICMS00, ICMS20, ICMS90 e ICMSOutraUF; proibido em ICMS45, ICMS60 e ICMSSN.

minimum0

maximum100

p_red_bcnumber | null · doubleOpcional

Redução da base de cálculo do ICMS, em percentual. Obrigatória em ICMS20, ICMS90 e ICMSOutraUF; proibida nas demais variantes.

minimum0

maximum100

ibs_cbs_cststring | nullOpcional

CST de IBS/CBS, com 3 dígitos — ex.: 000, tributação integral. Não confundir com o cst do ICMS, de 2 dígitos: são vocabulários diferentes.

pattern"^\\d{3}$"

ibs_cbs_class_tribstring | nullOpcional

Classificação tributária de IBS/CBS, com 6 dígitos — ex.: 000001.

pattern"^\\d{6}$"

ibs_uf_aliquotanumber | null · doubleOpcional

Alíquota do IBS estadual, em percentual, com até 4 casas decimais.

minimum0

maximum100

ibs_mun_aliquotanumber | null · doubleOpcional

Alíquota do IBS municipal, em percentual, com até 4 casas decimais.

minimum0

maximum100

cbs_aliquotanumber | null · doubleOpcional

Alíquota da CBS, em percentual, com até 4 casas decimais.

minimum0

maximum100

ibs_cbs_p_red_bcnumber | null · doubleOpcional

Redução da base de cálculo de IBS/CBS, em percentual, com até 4 casas decimais. Aplicada antes das alíquotas.

minimum0

maximum100

valid_fromstring | null · dateOpcional

valid_untilstring | null · dateOpcional

Não pode ser anterior a valid_from.

notesstring | nullOpcional

maxLength255

Respostas

201 Resposta HTTP

Regra criada para a transportadora autenticada, com o cst e o icms_variante_rotulo já derivados.

`application/json`

FiscalTaxRuleEnvelope ↗

dataobjectObrigatório

Falha interna sem detalhes de integrações operacionais.

`application/json`

ErrorEnvelope ↗

errorobjectObrigatório

ErrorBody ↗

Headers

X-Request-Id

Identificador de correlação da chamada.

Definição Completa da Operação

{
  "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": []
}