← InícioFleetPay / API

Alterar uma chave do lote

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

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

Altera valor, tipo_servico, regime_tributario, tomador ou a rota (origem/destino) de uma chave, que continua na mesma posição do manifesto e do grupo de repasse.

  • Chave failed: é reemitida com os dados novos (nada a cancelar).
  • Chave emitted (autorizada): o contra-CT-e é cancelado na SEFAZ com a justificativa (obrigatória, 15 a 255 caracteres) e um novo é emitido; o UUID antigo vai para substituidos. Se a SEFAZ recusar o cancelamento, a chave segue emitted com reason: alteracao_recusada. Cancelado o antigo, o novo sempre é emitido: se o repasse da origem não tem como nascer, a linha sai emitted com financeiro: nenhum e o motivo, em vez de recusada.

Alterar o valor num lote em rateio o converte em por documento: cada chave congela o valor que declara hoje e só esta muda. Tipos 2 e 3 exigem origem e destino (422 rota_obrigatoria). Sem nenhuma mudança numa chave autorizada: 422 nada_a_alterar — o mesmo tomador, vindo do cadastro ou dos dados completos, não é mudança. O tomador só com o cnpj sem cadastro, ou com o cadastro incompleto, responde 422 tomador_nao_cadastrado / tomador_cadastro_incompleto e a chave não muda.

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

Obrigatório

Respostas

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