← InicioFleetPay / API

Agregar claves al lote

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

POST/fiscal/cte-subcontratacao/lote/{batch_id}/chaves
addContraCteBatchKeysBase 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.

Incluye claves de CT-e de la contratante en el lote ya procesado. Entran al final del manifiesto (siguientes posiciones) y en el mismo grupo de pago, que pasa a esperar N + k documentos.

Valor. En lotes por documento, cada clave trae su valor. En lotes en prorrateo (frete_bruto), elija con redistribuir:

  • false (predeterminado): las claves ya emitidas mantienen el valor declarado; la nueva clave trae su valor; el lote pasa a ser por documento.
  • true: mantiene frete_bruto y redivide por N. Las nuevas claves vienen sin valor; cada contra-CT-e autorizado cuyo valor cambió se cancela en SEFAZ y se reemite — por ello justificativa (15 a 255 caracteres) es obligatoria si hay claves emitidas.

Con cuota de pago ya generada por el grupo (hubo escaneo), responde 409 grupo_repasse_com_parcelas. La clave debe ser de la misma contratante (422 contratante_diferente) y, en lote a nombre de la subcontratada, emitida por quien dispara (422 chave_de_outro_emitente).

Pagador. La clave incluida trae su tomador (solo cnpj o todos los datos); sin él, es el emisor del CT-e de la contratante — el tomador informado en la creación del lote no se hereda. cnpj sin registro o incompleto responde 422 tomador_nao_cadastrado / tomador_cadastro_incompleto sin incluir nada.

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"
}

Cuerpo de la Solicitud

Obligatorio

application/json

redistribuirbooleanOpcional

Solo en prorrateo. true redivide el frete_bruto por N; false mantiene el valor de cada clave.

justificativastringOpcional

Obligatoria con redistribuir: true cuando hay clave autorizada (las que cambian de valor se cancelan y se reemiten).

minLength15
maxLength255

Respuestas

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": "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"
}