← InicioFleetPay / API

Modificar una clave del lote

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

PATCH/fiscal/cte-subcontratacao/lote/{batch_id}/chaves/{chave}
updateContraCteBatchKeyBase 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.

Modifica valor, tipo_servico, regime_tributario, tomador o ruta (origem/destino) de una clave, que conserva la misma posición en el manifiesto y grupo de pago.

  • Clave failed: se reemite con los datos nuevos (nada que cancelar).
  • Clave emitted (autorizada): el contra-CT-e se cancela en SEFAZ con justificativa (obligatoria, 15 a 255 caracteres) y se emite uno nuevo; el UUID anterior pasa a substituidos. Si SEFAZ rechaza la cancelación, la clave sigue emitted con reason: alteracao_recusada. Cancelado el anterior, el nuevo siempre se emite: si el pago del origen no puede nacer, queda emitted con financeiro: nenhum y motivo.

Cambiar valor en un lote por prorrateo lo convierte a por documento. Tipos 2 y 3 exigen origem y destino (422 rota_obrigatoria). Sin cambios en clave autorizada responde 422 nada_a_alterar. tomador solo con cnpj sin registro o incompleto responde 422 tomador_nao_cadastrado / tomador_cadastro_incompleto y la clave no cambia.

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

Obligatorio

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": "Alterar uma chave do lote",
  "operationId": "updateContraCteBatchKey",
  "description": "Altera `valor`, `tipo_servico`, `regime_tributario`, `tomador` ou a rota (`origem`/`destino`) de\numa chave, que continua na **mesma posição** do manifesto e do grupo de repasse.\n\n- Chave `failed`: é reemitida com os dados novos (nada a cancelar).\n- Chave `emitted` (autorizada): o contra-CT-e é **cancelado na SEFAZ** com a `justificativa`\n  (obrigatória, 15 a 255 caracteres) e um novo é emitido; o UUID antigo vai para `substituidos`.\n  Se a SEFAZ recusar o cancelamento, a chave segue `emitted` com `reason: alteracao_recusada`.\n  Cancelado o antigo, o novo **sempre** é emitido: se o repasse da origem não tem como nascer,\n  a linha sai `emitted` com `financeiro: nenhum` e o `motivo`, em vez de recusada.\n\nAlterar o `valor` num lote em **rateio** o converte em **por documento**: cada chave congela o\nvalor que declara hoje e só esta muda. Tipos 2 e 3 exigem `origem` e `destino`\n(`422 rota_obrigatoria`). Sem nenhuma mudança numa chave autorizada: `422 nada_a_alterar` — o\nmesmo tomador, vindo do cadastro ou dos dados completos, não é mudança. O `tomador` só com o\n`cnpj` sem cadastro, ou com o cadastro incompleto, responde `422 tomador_nao_cadastrado` /\n`tomador_cadastro_incompleto` e a chave não muda.\n",
  "parameters": [
    {
      "$ref": "#/components/parameters/ContraCteBatchId"
    },
    {
      "$ref": "#/components/parameters/ContraCteBatchKey"
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ContraCteLoteEditarRequest"
        }
      }
    }
  },
  "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": "PATCH",
  "path": "/fiscal/cte-subcontratacao/lote/{batch_id}/chaves/{chave}"
}