Crear una regla tributaria

Parámetros, estructura de datos y respuestas del contrato versionado.

POST/fiscal/regras-tributacao

createFiscalTaxRuleBase de Pruebas: https://api.fleetpay.site/v1

Las descripciones técnicas se traducen del contrato versionado. Se conservan los identificadores y el JSON originales; se omiten los ejemplos de datos.

Crea una regla para la transportista autenticada: no existe company_id en el contrato; el alcance siempre corresponde a la credencial. La regla prevalece en todas las vías de emisión: el motor la determina según la ruta del borrador, calcula ICMS, decide CFOP y vuelve a aplicarlo todo al emitir. En POST /cte y PUT /cte/{cte_uuid}, una ruta sin regla devuelve 422 regra_tributaria_ausente y la regla sustituye el bloque icms del payload (solo se conservan la sustitución tributaria retenida y el crédito presunto). En el CT-e automático a partir de NF-e y en el contra-CT-e, una ruta sin regla queda pendiente con sem_regra_tributacao.

No hay un método de actualización: para corregir una regla, cree otra con su vigencia y elimine la anterior.

El campo opcional tp_serv limita la regla a un tipo de servicio (ide/tpServ: 0 normal, 1 subcontratación, 2 redespacho, 3 redespacho intermedio). Una regla cuyo tipo coincide prevalece sobre cualquier regla basada solo en la ruta. Permite declarar el régimen de cada tipo (por ejemplo, 5360 + ICMS45/CST 51 para subcontratación, 5351 + ICMS normal para redespacho) sin modificar las reglas de ruta. Sin una regla específica del tipo, el contra-CT-e mantiene el comportamiento anterior (5360/6360, o 5932/6932 cuando el servicio comienza en otro estado).

Los seis campos de IBS/CBS (Reforma Tributaria, LC 214/2025) son opcionales, pero forman un bloque: informar cualquiera de las tres tasas hace que la regla determine las tres y que las omitidas se consideren cero. En 2026, el año de prueba, la ley fija los porcentajes (IBS 0,10% y CBS 0,90%) y el CT-e ya los muestra sin configuración; a partir de 2027, se rechaza antes del envío la emisión de CT-e para una ruta sin regla de IBS/CBS.

Autenticación

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

La disponibilidad depende del entorno, los permisos habilitados y el proveedor. Esta referencia no ejecuta solicitudes ni recibe credenciales.

Parámetros

No hay parámetros declarados para esta operación.

Cuerpo de la Solicitud

Obligatorio

`application/json`

FiscalTaxRuleCreate ↗

origin_statestring | nullOpcional

Estado de origen; null (u omitido) significa cualquier origen.

minLength2

maxLength2

destination_statestring | nullOpcional

Estado de destino; null (u omitido) significa cualquier destino.

minLength2

maxLength2

tp_servinteger | nullOpcional

Tipo de servicio (ide/tpServ) al que se aplica la regla; null (u omitido) = cualquier tipo. 0 normal, 1 subcontratación, 2 redespacho, 3 redespacho intermedio; no se acepta 4 (multimodal). Una regla que coincide con el tipo tiene prioridad sobre cualquier regla basada únicamente en el recorrido.

0 · 1 · 2 · 3 · null

cfopstring | nullObligatorio

Obligatorio. CFOP que el motor registra para el servicio. En los contra-CT-e con una regla sin tp_serv, solo se toma el dígito de operación (5xxx/6xxx); el código final se determina por el recorrido (5360/6360 o 5932/6932). Con una regla específica del tipo, se mantiene su CFOP cuando el servicio comienza en el estado del emisor (se sigue imponiendo 5932/6932 cuando comienza en otro estado).

pattern"^\\d{4}$"

icms_varianteobjectObligatorio

FiscalTaxRuleIcmsVariant ↗

cststring | nullOpcional

Solo para ICMS45, donde es obligatorio (40, 41 o 51). En las demás variantes, se ignora el campo: el servidor deriva el CST de la variante (ICMS00→00, ICMS20→20, ICMS60→60, ICMS90/ICMSOutraUF/ICMSSN→90).

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

aliquotanumber | null · doubleOpcional

Porcentaje de ICMS. Obligatorio en ICMS00, ICMS20, ICMS90 e ICMSOutraUF; prohibido en ICMS45, ICMS60 e ICMSSN.

minimum0

maximum100

p_red_bcnumber | null · doubleOpcional

Reducción porcentual de la base imponible del ICMS. Obligatoria en ICMS20, ICMS90 e ICMSOutraUF; prohibida en las demás variantes.

minimum0

maximum100

ibs_cbs_cststring | nullOpcional

CST de IBS/CBS con 3 dígitos, p. ej. 000 para tributación integral. No debe confundirse con el cst del ICMS de 2 dígitos: son vocabularios distintos.

pattern"^\\d{3}$"

ibs_cbs_class_tribstring | nullOpcional

Clasificación tributaria de IBS/CBS, con 6 dígitos — p. ej. 000001.

pattern"^\\d{6}$"

ibs_uf_aliquotanumber | null · doubleOpcional

Tasa estatal de IBS, en porcentaje, con hasta 4 decimales.

minimum0

maximum100

ibs_mun_aliquotanumber | null · doubleOpcional

Tasa municipal de IBS, en porcentaje, con hasta 4 decimales.

minimum0

maximum100

cbs_aliquotanumber | null · doubleOpcional

Tasa de CBS, en porcentaje, con hasta 4 decimales.

minimum0

maximum100

ibs_cbs_p_red_bcnumber | null · doubleOpcional

Reducción porcentual de la base imponible de IBS/CBS, con hasta 4 decimales. Se aplica antes de las alícuotas.

minimum0

maximum100

valid_fromstring | null · dateOpcional

valid_untilstring | null · dateOpcional

No puede ser anterior a valid_from.

notesstring | nullOpcional

maxLength255

Respuestas

201 Respuesta HTTP

Regla creada para el transportista autenticado, con cst e icms_variante_rotulo ya derivados.

`application/json`

FiscalTaxRuleEnvelope ↗

dataobjectObligatorio

Fallo interno sin detalles de las integraciones operativas.

`application/json`

ErrorEnvelope ↗

errorobjectObligatorio

ErrorBody ↗

Headers

X-Request-Id

Identificador de correlación de la llamada.

Definición Completa de la Operación

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