← InicioFleetPay / API

Eliminar una clave del lote

Parámetros, estructura de datos y respuestas del contrato versionado.

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

Las descripciones técnicas se traducen del contrato versionado. Se conservan los identificadores y el JSON originales; se omiten los ejemplos de datos.

Retira la clave del lote y del grupo de pago. El manifiesto se compacta: las claves siguientes suben una posición y el grupo pasa a esperar N - 1 documentos. La línea queda en el informe como removed, sin sequencia, para historial.

  • Clave nunca autorizada (failed, duplicated): sale al instante — 200.
  • Clave emitted: el contra-CT-e se cancela en SEFAZ con justificativa (obligatoria) y recién entonces sale — 202. Cancelación aún no confirmada por SEFAZ deja la clave en cancelling; reprocese el lote después.

En lote en prorrateo, redistribuir: true redivide frete_bruto entre las N - 1 restantes (autorizadas cuyo valor cambia se cancelan y reemiten); false (predeterminado) conserva el valor de cada una y pasa a por documento. La última clave no puede eliminarse (422 lote_precisa_de_uma_chave).

En lote a nombre de la subcontratada, tras revocarse la autorización, quien lo disparó aún elimina clave nunca emitida (failed, duplicated) sin redistribuir — liberando el pago de las ya emitidas. Eliminar clave emitted/cancelling o usar redistribuir: true responde 403 emissao_nao_autorizada.

Autenticación

Permiso Requerido
fiscal — Fiscal
Módulo
Subcontratación
Perfiles Aplicables
Transportista Flotista
Mecanismos
OAuth2 client_credentials (POST /oauth/token) o API Key vía Authorization: Bearer / X-Api-Key
[
  {
    "oauth2": []
  },
  {
    "chaveApi": []
  }
]
La disponibilidad depende del entorno, los permisos habilitados y el proveedor. Esta referencia no ejecuta solicitudes ni recibe credenciales.

Parámetros

batch_idpath · stringObligatorio

UUID del lote devuelto por POST /fiscal/cte-subcontratacao/lote.

Restricciones
{
  "type": "string",
  "format": "uuid"
}
chavepath · stringObligatorio

Clave de acceso (44 dígitos) del CT-e de la contratante, tal como figura en el lote.

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

Cuerpo de la Solicitud

Opcional

application/json

justificativastringOpcional

Obligatoria cuando la clave está autorizada — justificación de la cancelación ante SEFAZ.

minLength15
maxLength255
redistribuirbooleanOpcional

Solo en prorrateo. true redivide el frete_bruto entre las restantes; false mantiene el valor de cada una.

Respuestas

200 Respuesta HTTP

El lote después de la modificación, en el mismo formato que GET /fiscal/cte-subcontratacao/lote/{batch_id}. 202 cuando hay trabajo en curso en SEFAZ (status: processing — siga vía GET); 200 cuando la modificación terminó al instante.

application/json

202 Respuesta HTTP

El lote después de la modificación, en el mismo formato que GET /fiscal/cte-subcontratacao/lote/{batch_id}. 202 cuando hay trabajo en curso en SEFAZ (status: processing — siga vía GET); 200 cuando la modificación terminó al instante.

application/json

403 Respuesta HTTP

lote_de_outra_transportadora (solo quien creó el lote modifica) o emissao_nao_autorizada (la subcontratada revocó la autorización de la contratante). Revocada la autorización, solo sigue abierta la eliminación de una clave que nunca fue emitida.

application/json

404 Respuesta HTTP

lote_nao_encontrado o chave_nao_encontrada (la clave no forma parte del lote).

application/json

409 Respuesta HTTP

lote_em_processamento (espere a que status salga de processing), grupo_repasse_com_parcelas (el grupo de pago al conductor del lote ya generó cuota — hubo escaneo — y el lote ya no cambia), cancelamento_em_andamento o chave_duplicada (contra-CT-e emitido fuera del lote: elimine, no modifique).

application/json

422 Respuesta HTTP

Payload inválido.

application/json

Headers

X-Request-Id

Identificador de correlación de la llamada.

Definición Completa de la Operación
{
  "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}"
}