← HomeFleetPay / API

Update a key in the batch

Parameters, data structure and responses from the versioned contract.

PATCH/fiscal/cte-subcontratacao/lote/{batch_id}/chaves/{chave}
updateContraCteBatchKeySandbox Base: https://api.fleetpay.site/v1

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

Updates valor, tipo_servico, regime_tributario, tomador or route (origem/destino) for a key, preserving its exact position in the manifest and payout group.

  • failed key: reissued with updated fields (nothing to cancel).
  • emitted (authorized) key: the counter-CT-e is cancelled at SEFAZ with justificativa (mandatory, 15 to 255 characters) and a new one issues; the previous UUID moves to substituidos. If SEFAZ rejects cancellation, the key stays emitted with reason: alteracao_recusada. Once cancelled, the new document always issues: if source payout cannot materialize, the row becomes emitted with financeiro: nenhum and motivo, rather than rejected.

Changing valor on a prorated batch switches it to per-document: every key freezes its current amount and only this key changes. Types 2 and 3 require origem and destino (422 rota_obrigatoria). No effective change on an authorized key returns 422 nada_a_alterar — resolving to the same payer counts as unchanged. Unregistered or incomplete cnpj-only tomador rejects with 422 tomador_nao_cadastrado / tomador_cadastro_incompleto without modifying the key.

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"
}
chavepath · stringRequired

Access key (44 digits) of the contractor's CT-e, as listed in the batch.

Constraints
{
  "type": "string",
  "pattern": "^[0-9]{44}$"
}

Request Body

Required

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": "Alterar uma chave do lote",
  "operationId": "updateContraCteBatchKey",
  "description": "Altera `valor`, `tipo_servico`, `regime_tributario`, `tomador` ou a rota (`origem`/`destino`) de\numa chave, que continua na **mesma posição** do manifesto e do grupo de repasse.\n\n- Chave `failed`: é reemitida com os dados novos (nada a cancelar).\n- Chave `emitted` (autorizada): o contra-CT-e é **cancelado na SEFAZ** com a `justificativa`\n  (obrigatória, 15 a 255 caracteres) e um novo é emitido; o UUID antigo vai para `substituidos`.\n  Se a SEFAZ recusar o cancelamento, a chave segue `emitted` com `reason: alteracao_recusada`.\n  Cancelado o antigo, o novo **sempre** é emitido: se o repasse da origem não tem como nascer,\n  a linha sai `emitted` com `financeiro: nenhum` e o `motivo`, em vez de recusada.\n\nAlterar o `valor` num lote em **rateio** o converte em **por documento**: cada chave congela o\nvalor que declara hoje e só esta muda. Tipos 2 e 3 exigem `origem` e `destino`\n(`422 rota_obrigatoria`). Sem nenhuma mudança numa chave autorizada: `422 nada_a_alterar` — o\nmesmo tomador, vindo do cadastro ou dos dados completos, não é mudança. O `tomador` só com o\n`cnpj` sem cadastro, ou com o cadastro incompleto, responde `422 tomador_nao_cadastrado` /\n`tomador_cadastro_incompleto` e a chave não muda.\n",
  "parameters": [
    {
      "$ref": "#/components/parameters/ContraCteBatchId"
    },
    {
      "$ref": "#/components/parameters/ContraCteBatchKey"
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ContraCteLoteEditarRequest"
        }
      }
    }
  },
  "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": "PATCH",
  "path": "/fiscal/cte-subcontratacao/lote/{batch_id}/chaves/{chave}"
}