← InícioFleetPay / API

Excluir uma chave do lote

Parâmetros, estrutura de dados e respostas do contrato versionado.

DELETE/fiscal/cte-subcontratacao/lote/{batch_id}/chaves/{chave}
removeContraCteBatchKeyBase de Homologação: https://api.fleetpay.site/v1

Descrições técnicas preservadas do contrato versionado. Exemplos de dados foram omitidos da cópia pública.

Tira a chave do lote e do grupo de repasse. O manifesto é compactado: as chaves seguintes sobem uma posição e o grupo passa a esperar N − 1 documentos. A linha fica no relatório como removed, sem sequencia, para o histórico.

  • Chave que nunca foi autorizada (failed, duplicated): sai na hora — 200.
  • Chave emitted: o contra-CT-e é cancelado na SEFAZ com a justificativa (obrigatória) e só então sai — 202. Cancelamento que a SEFAZ ainda não confirmou deixa a chave cancelling; reprocesse o lote depois.

No lote em rateio, redistribuir: true redivide o frete_bruto pelas N − 1 restantes (as autorizadas cujo valor muda são canceladas e reemitidas); false (padrão) mantém o valor de cada uma e o lote passa a valer por documento. A última chave do lote não pode ser excluída (422 lote_precisa_de_uma_chave).

No lote em nome da subcontratada, depois de a autorização ser revogada, quem disparou o lote ainda exclui a chave que nunca foi emitida (failed, duplicated), sem redistribuir — é o que libera o repasse das chaves já emitidas. Excluir chave emitted ou cancelling e redistribuir: true respondem 403 emissao_nao_autorizada.

Autenticação

Escopo Necessário
fiscal — Fiscal
Módulo
Subcontratação
Perfis Aplicáveis
Transportador Frotista
Mecanismos
OAuth2 client_credentials (POST /oauth/token) ou API Key em Authorization: Bearer / X-Api-Key
[
  {
    "oauth2": []
  },
  {
    "chaveApi": []
  }
]
A disponibilidade depende do ambiente, dos escopos habilitados e do provedor. Esta referência não executa chamadas nem recebe credenciais.

Parâmetros

batch_idpath · stringObrigatório

UUID do lote devolvido pelo POST /fiscal/cte-subcontratacao/lote.

Restrições
{
  "type": "string",
  "format": "uuid"
}
chavepath · stringObrigatório

Chave de acesso (44 dígitos) do CT-e da contratante, como está no lote.

Restrições
{
  "type": "string",
  "pattern": "^[0-9]{44}$"
}

Corpo da Requisição

Opcional

application/json

justificativastringOpcional

Obrigatória quando a chave está autorizada — justificativa do cancelamento na SEFAZ.

minLength15
maxLength255
redistribuirbooleanOpcional

Só no rateio. true redivide o frete_bruto pelas restantes; false mantém o valor de cada uma.

Respostas

200 Resposta HTTP

O lote depois da alteração, no mesmo formato de GET /fiscal/cte-subcontratacao/lote/{batch_id}. 202 quando há trabalho na SEFAZ em curso (status: processing — acompanhe pelo GET); 200 quando a alteração terminou na hora.

application/json

202 Resposta HTTP

O lote depois da alteração, no mesmo formato de GET /fiscal/cte-subcontratacao/lote/{batch_id}. 202 quando há trabalho na SEFAZ em curso (status: processing — acompanhe pelo GET); 200 quando a alteração terminou na hora.

application/json

403 Resposta HTTP

lote_de_outra_transportadora (só quem criou o lote altera) ou emissao_nao_autorizada (a subcontratada revogou a autorização da contratante). Revogada a autorização, só a exclusão de chave que nunca foi emitida continua aberta.

application/json

404 Resposta HTTP

lote_nao_encontrado ou chave_nao_encontrada (a chave não faz parte do lote).

application/json

409 Resposta HTTP

lote_em_processamento (aguarde o status sair de processing), grupo_repasse_com_parcelas (o repasse do lote já gerou parcela — houve bipagem — e o lote não muda mais), cancelamento_em_andamento ou chave_duplicada (contra-CT-e emitido fora do lote: exclua, não altere).

application/json

422 Resposta HTTP

Payload inválido.

application/json

Headers

X-Request-Id

Identificador de correlação da chamada.

Definição Completa da Operação
{
  "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}"
}