← HomeFleetPay / API

Add access keys to the batch

Parameters, data structure and responses from the versioned contract.

POST/fiscal/cte-subcontratacao/lote/{batch_id}/chaves
addContraCteBatchKeysSandbox Base: https://api.fleetpay.site/v1

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

Appends contractor CT-e keys to an already-processed batch. They enter at the end of the manifest (next sequence positions) and in the same payout group, which now expects N + k documents.

Value. In per-document batches each new key supplies its valor. In prorated batches (frete_bruto), pick redistribuir:

  • false (default): already-issued keys keep their declared values; each new key supplies its valor; the batch becomes per-document (total equals the sum).
  • true: preserves frete_bruto and re-splits across N. New keys carry no valor; each already-authorized counter-CT-e whose value changes is cancelled at SEFAZ and reissued — hence justificativa (15 to 255 characters) is required whenever any key was already issued.

If the payout group already generated an installment (scanning occurred), responds 409 grupo_repasse_com_parcelas. Keys must belong to the batch's contractor (422 contratante_diferente) and, for batches on behalf of a subcontractor, be issued by the caller (422 chave_de_outro_emitente).

Payer. Added keys may bring their own tomador in either batch format (cnpj-only or full details); omitted, payer defaults to the contractor CT-e's issuer — batch creation's tomador is not inherited. Unregistered or incomplete cnpj-only rejects with 422 tomador_nao_cadastrado / tomador_cadastro_incompleto and adds nothing.

Authentication

Required Scope
fiscal — Tax & Fiscal
Module
Subcontracting
Target Profiles
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

batch_idpath · stringRequired

Batch UUID returned by POST /fiscal/cte-subcontratacao/lote.

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

Request Body

Required

application/json

redistribuirbooleanOptional

Prorated mode only. true re-splits frete_bruto by N; false keeps each key's value.

justificativastringOptional

Mandatory with redistribuir: true when there is an authorized key (those whose value changes are cancelled and reissued).

minLength15
maxLength255

Responses

202 HTTP Response

The batch after the update, in the same format as GET /fiscal/cte-subcontratacao/lote/{batch_id}. 202 when SEFAZ work is in progress (status: processing — track via GET); 200 when the update finished immediately.

application/json

403 HTTP Response

lote_de_outra_transportadora (only the batch creator may edit) or emissao_nao_autorizada (the subcontractor revoked the contractor's authorization). Once authorization is revoked, only deleting a key that was never issued remains open.

application/json

404 HTTP Response

lote_nao_encontrado or chave_nao_encontrada (the key is not part of the batch).

application/json

409 HTTP Response

lote_em_processamento (wait for status to leave processing), grupo_repasse_com_parcelas (the batch payout group already generated an installment — there was a scan — and the batch can no longer change), cancelamento_em_andamento or chave_duplicada (counter-CT-e issued outside the batch: remove, do not update).

application/json

422 HTTP Response

Invalid payload.

application/json

Headers

X-Request-Id

Call correlation identifier.

Complete Operation Definition
{
  "tags": [
    "CT-e de subcontratação"
  ],
  "summary": "Incluir chaves no lote",
  "operationId": "addContraCteBatchKeys",
  "description": "Inclui chaves de CT-e da contratante no lote já processado. Elas entram no fim do manifesto (as\npróximas posições) e no mesmo grupo de repasse, que passa a esperar N + k documentos.\n\n**Valor.** No lote **por documento**, cada chave traz o seu `valor`. No lote em **rateio**\n(`frete_bruto`), escolha com `redistribuir`:\n- `false` (padrão): as chaves já emitidas **mantêm** o valor que declararam; a chave nova traz o\n  `valor` dela; o lote passa a valer **por documento** (o total é a soma).\n- `true`: mantém o `frete_bruto` e redivide por N. As chaves novas vêm **sem** `valor`; cada\n  contra-CT-e já autorizado cujo valor mudou é **cancelado na SEFAZ e reemitido** — por isso a\n  `justificativa` (15 a 255 caracteres) é obrigatória quando há chave emitida.\n\nCom parcela de repasse já gerada pelo grupo (houve bipagem), responde\n`409 grupo_repasse_com_parcelas`. A chave precisa ser da mesma contratante do lote\n(`422 contratante_diferente`) e, no lote em nome da subcontratada, de CT-e emitido por quem\no disparou (`422 chave_de_outro_emitente`).\n\n**Tomador.** A chave incluída traz o `tomador` dela, nas duas formas do lote (só o `cnpj`, ou\ntodos os dados); sem ele, o tomador é o emitente do CT-e da contratante — o `tomador` informado\nna criação do lote não é herdado. Só o `cnpj` sem cadastro, ou com o cadastro incompleto,\nresponde `422 tomador_nao_cadastrado` / `tomador_cadastro_incompleto` e nada é incluído.\n",
  "parameters": [
    {
      "$ref": "#/components/parameters/ContraCteBatchId"
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ContraCteLoteIncluirRequest"
        }
      }
    }
  },
  "responses": {
    "202": {
      "$ref": "#/components/responses/ContraCteLoteEditado"
    },
    "403": {
      "$ref": "#/components/responses/ContraCteLoteEdicaoProibida"
    },
    "404": {
      "$ref": "#/components/responses/ContraCteLoteEdicaoNaoEncontrado"
    },
    "409": {
      "$ref": "#/components/responses/ContraCteLoteEdicaoConflito"
    },
    "422": {
      "$ref": "#/components/responses/ValidationFailed"
    }
  },
  "x-fleetpay-scope": "fiscal",
  "x-fleetpay-module": "subcontratacao",
  "x-fleetpay-profiles": [
    "transportador_frotista"
  ],
  "method": "POST",
  "path": "/fiscal/cte-subcontratacao/lote/{batch_id}/chaves"
}