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}/chavesTechnical 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.
fiscal — Tax & Fiscal[
{
"oauth2": []
},
{
"chaveApi": []
}
]batch_idpath · stringRequiredBatch UUID returned by POST /fiscal/cte-subcontratacao/lote.
{
"type": "string",
"format": "uuid"
}Required
application/jsonctesarrayRequiredminItems1redistribuirbooleanOptionalProrated mode only. true re-splits frete_bruto by N; false keeps each key's value.
justificativastringOptionalMandatory with redistribuir: true when there is an authorized key (those whose value changes are cancelled and reissued).
minLength15maxLength255202 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": "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"
}