batch_idpath · stringRequiredBatch UUID returned by POST /fiscal/cte-subcontratacao/lote.
Constraints
{
"type": "string",
"format": "uuid"
}Parameters, data structure and responses from the versioned contract.
/fiscal/cte-subcontratacao/lote/{batch_id}/chaves/{chave}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.
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.
fiscal — Tax & Fiscal[
{
"oauth2": []
},
{
"chaveApi": []
}
]batch_idpath · stringRequiredBatch UUID returned by POST /fiscal/cte-subcontratacao/lote.
{
"type": "string",
"format": "uuid"
}chavepath · stringRequiredAccess key (44 digits) of the contractor's CT-e, as listed in the batch.
{
"type": "string",
"pattern": "^[0-9]{44}$"
}Optional
application/jsonjustificativastringOptionalMandatory when the key is authorized — justification for cancellation at SEFAZ.
minLength15maxLength255redistribuirbooleanOptionalProrated mode only. true re-splits frete_bruto across remaining keys; false keeps each key's value.
200 HTTP ResponseThe 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/jsondataobjectRequiredenvironmentobjectOptional202 HTTP ResponseThe 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/jsondataobjectRequiredenvironmentobjectOptional403 HTTP Responselote_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.
404 HTTP Responselote_nao_encontrado or chave_nao_encontrada (the key is not part of the batch).
409 HTTP Responselote_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).
422 HTTP ResponseInvalid payload.
X-Request-IdCall correlation identifier.
{
"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}"
}