← HomeFleetPay / API

Remove a key from the batch

Parameters, data structure and responses from the versioned contract.

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

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

Removes a key from the batch and its payout group. The manifest is compacted: following keys shift up by one position and the group now expects N - 1 documents. The row stays in the report as removed, without sequencia, for audit trail.

  • Never-authorized key (failed, duplicated): removed immediately — 200.
  • emitted key: the counter-CT-e is cancelled at SEFAZ using justificativa (mandatory) before removal — 202. Unconfirmed SEFAZ cancellation leaves the row cancelling; reprocess the batch afterward.

In prorated batches, redistribuir: true re-splits frete_bruto across the remaining N - 1 keys (authorized ones with value changes are cancelled and reissued); false (default) preserves individual amounts and converts the batch to per-document. The last remaining key cannot be deleted (422 lote_precisa_de_uma_chave).

In batches on behalf of a subcontractor, after authorization is revoked, the batch creator may still remove a never-issued key (failed, duplicated) without redistribuir — unblocking payouts for already-issued keys. Deleting emitted/cancelling keys or passing redistribuir: true returns 403 emissao_nao_autorizada.

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

Optional

application/json

justificativastringOptional

Mandatory when the key is authorized — justification for cancellation at SEFAZ.

minLength15
maxLength255
redistribuirbooleanOptional

Prorated mode only. true re-splits frete_bruto across remaining keys; false keeps each key's value.

Responses

200 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

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": "Excluir uma chave do lote",
  "operationId": "removeContraCteBatchKey",
  "description": "Tira a chave do lote e do grupo de repasse. O manifesto é **compactado**: as chaves seguintes\nsobem uma posição e o grupo passa a esperar N − 1 documentos. A linha fica no relatório como\n`removed`, sem `sequencia`, para o histórico.\n\n- Chave que nunca foi autorizada (`failed`, `duplicated`): sai na hora — `200`.\n- Chave `emitted`: o contra-CT-e é **cancelado na SEFAZ** com a `justificativa` (obrigatória)\n  e só então sai — `202`. Cancelamento que a SEFAZ ainda não confirmou deixa a chave\n  `cancelling`; reprocesse o lote depois.\n\nNo lote em **rateio**, `redistribuir: true` redivide o `frete_bruto` pelas N − 1 restantes (as\nautorizadas cujo valor muda são canceladas e reemitidas); `false` (padrão) mantém o valor de\ncada uma e o lote passa a valer por documento. A última chave do lote não pode ser excluída\n(`422 lote_precisa_de_uma_chave`).\n\nNo lote **em nome da subcontratada**, depois de a autorização ser revogada, quem disparou o\nlote ainda exclui a chave que nunca foi emitida (`failed`, `duplicated`), sem `redistribuir` —\né o que libera o repasse das chaves já emitidas. Excluir chave `emitted` ou `cancelling` e\n`redistribuir: true` respondem `403 emissao_nao_autorizada`.\n",
  "parameters": [
    {
      "$ref": "#/components/parameters/ContraCteBatchId"
    },
    {
      "$ref": "#/components/parameters/ContraCteBatchKey"
    }
  ],
  "requestBody": {
    "required": false,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ContraCteLoteExcluirRequest"
        }
      }
    }
  },
  "responses": {
    "200": {
      "$ref": "#/components/responses/ContraCteLoteEditado"
    },
    "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": "DELETE",
  "path": "/fiscal/cte-subcontratacao/lote/{batch_id}/chaves/{chave}"
}