← HomeFleetPay / API

Create or issue complementary value CT-e

Parameters, data structure and responses from the versioned contract.

POST/fiscal/cte/{cte_uuid}/complementar
createComplementaryCteSandbox Base: https://api.fleetpay.site/v1

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

Generates a Value Complement CT-e (ide/tpCTe = 1, group <infCteComp>) from an own CT-e already authorized by SEFAZ (cStat = 100).

  • The original CT-e stays valid and unaltered (neither cancelled nor replaced).
  • The complementary document receives its own number, series, access key and protocol.
  • Automatically preserves sender, recipient, payer, route, tpServ and tax rule from the original operation, without linking new NF-e or generating a new MDF-e.
  • Supply only the incremental difference (valor_frete > 0 and/or icms.v_icms > 0). Reducing values via complementary CT-e is not allowed.
  • With emitir: false (default), returns 201 with the draft ready for preview or later issuance at POST /fiscal/cte/{cte_uuid}/emissao. With emitir: true, starts transmission immediately and returns 202.

Authentication

Required Scope
fiscal — Tax & Fiscal
Module
Tax, CT-e, MDF-e & CIOT
Target Profiles
Transport Manager · Dedicated Fleet Contractor · Fleet Carrier
Schemes
OAuth2 client_credentials (POST /oauth/token) or API Key via Authorization: Bearer / X-Api-Key
[
  {
    "oauth2": []
  },
  {
    "chaveApi": []
  }
]
Availability depends on the environment, enabled scopes and provider. This reference does not execute requests or collect credentials.

Parameters

cte_uuidpath · stringRequired

Public CT-e UUID.

Constraints
{
  "type": "string",
  "format": "uuid"
}

Request Body

Required

application/json

valor_fretenumber | nullOptional

Freight value to add (vTPrest). Cannot be negative.

minimum0
maximum999999.99
valor_recebernumber | nullOptional

Complementary receivable value (vRec). If omitted, defaults to valor_frete.

minimum0
maximum999999.99
componentesarray | nullOptional
maxItems20
icmsobject | nullOptional

Transactional ICMS fields for pure tax complement or CST 60/90.

natureza_operacaostring | nullOptional

Defaults to COMPLEMENTO DE VALORES DE TRANSPORTE.

maxLength60
observacoesstring | nullOptional

Free-form notes text; the mandatory payment notice is automatically kept.

maxLength2000
emitirboolean | nullOptional

When true, reserves and immediately initiates issuance with the fiscal provider (202).

Responses

201 HTTP Response

Complementary CT-e draft created (emitir = false).

application/json

Headers

X-Request-Id

Call correlation identifier.

202 HTTP Response

Complementary CT-e issuance started (emitir = true).

application/json

Headers

X-Request-Id

Call correlation identifier.

401 HTTP Response

FleetPay API key missing or invalid.

application/json

Headers

X-Request-Id

Call correlation identifier.

403 HTTP Response

Fiscal scope disabled for the key, or no active carrier associated with the key.

application/json

Headers

X-Request-Id

Call correlation identifier.

404 HTTP Response

Resource not found in the authenticated tenant.

application/json

Headers

X-Request-Id

Call correlation identifier.

422 HTTP Response

Invalid payload, outstanding requirement or business rule.

application/json

Headers

X-Request-Id

Call correlation identifier.

429 HTTP Response

Per-carrier limit exceeded.

application/json

Headers

X-Request-Id

Call correlation identifier.

Retry-After

Seconds until another attempt.

500 HTTP Response

Internal failure without operational integration details.

application/json

Headers

X-Request-Id

Call correlation identifier.

Complete Operation Definition
{
  "tags": [
    "CT-e"
  ],
  "summary": "Criar ou emitir CT-e complementar de valores",
  "description": "Gera um **CT-e Complementar de Valores** (`ide/tpCTe = 1`, grupo `<infCteComp>`) a partir de\num CT-e próprio já autorizado pela SEFAZ (`cStat = 100`).\n\n- O CT-e original permanece válido e inalterado (não é cancelado nem substituído).\n- O documento complementar recebe número, série, chave de acesso e protocolo próprios.\n- Mantém automaticamente remetente, destinatário, tomador, rota, `tpServ` e regra tributária\n  da prestação original, sem vincular novas NF-es nem gerar novo MDF-e.\n- Informe somente a diferença a acrescentar (`valor_frete > 0` e/ou `icms.v_icms > 0`). Não é\n  permitido reduzir valores por CT-e complementar.\n- Com `emitir: false` (padrão), responde `201` com o rascunho pronto para prévia ou emissão\n  posterior em `POST /fiscal/cte/{cte_uuid}/emissao`. Com `emitir: true`, inicia a transmissão\n  imediatamente e responde `202`.\n",
  "operationId": "createComplementaryCte",
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/CreateComplementaryCteInput"
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Rascunho de CT-e complementar criado (`emitir = false`).",
      "headers": {
        "X-Request-Id": {
          "$ref": "#/components/headers/RequestId"
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/CteEnvelope"
          }
        }
      }
    },
    "202": {
      "description": "Emissão do CT-e complementar iniciada (`emitir = true`).",
      "headers": {
        "X-Request-Id": {
          "$ref": "#/components/headers/RequestId"
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/CteIssueEnvelope"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "422": {
      "$ref": "#/components/responses/ValidationOrBusinessRuleFailed"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    },
    "500": {
      "$ref": "#/components/responses/InternalError"
    }
  },
  "x-fleetpay-scope": "fiscal",
  "x-fleetpay-module": "fiscal-ciot",
  "x-fleetpay-profiles": [
    "gestor",
    "agregado_empresarial",
    "transportador_frotista"
  ],
  "method": "POST",
  "path": "/fiscal/cte/{cte_uuid}/complementar",
  "parameters": [
    {
      "$ref": "#/components/parameters/CteUuid"
    }
  ]
}