← InícioFleetPay / API

Incluir chaves no lote

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

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

Inclui chaves de CT-e da contratante no lote já processado. Elas entram no fim do manifesto (as próximas posições) e no mesmo grupo de repasse, que passa a esperar N + k documentos.

Valor. No lote por documento, cada chave traz o seu valor. No lote em rateio (frete_bruto), escolha com redistribuir:

  • false (padrão): as chaves já emitidas mantêm o valor que declararam; a chave nova traz o valor dela; o lote passa a valer por documento (o total é a soma).
  • true: mantém o frete_bruto e redivide por N. As chaves novas vêm sem valor; cada contra-CT-e já autorizado cujo valor mudou é cancelado na SEFAZ e reemitido — por isso a justificativa (15 a 255 caracteres) é obrigatória quando há chave emitida.

Com parcela de repasse já gerada pelo grupo (houve bipagem), responde 409 grupo_repasse_com_parcelas. A chave precisa ser da mesma contratante do lote (422 contratante_diferente) e, no lote em nome da subcontratada, de CT-e emitido por quem o disparou (422 chave_de_outro_emitente).

Tomador. A chave incluída traz o tomador dela, nas duas formas do lote (só o cnpj, ou todos os dados); sem ele, o tomador é o emitente do CT-e da contratante — o tomador informado na criação do lote não é herdado. Só o cnpj sem cadastro, ou com o cadastro incompleto, responde 422 tomador_nao_cadastrado / tomador_cadastro_incompleto e nada é incluído.

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

Corpo da Requisição

Obrigatório

application/json

redistribuirbooleanOpcional

Só no rateio. true redivide o frete_bruto por N; false mantém o valor de cada chave.

justificativastringOpcional

Obrigatória com redistribuir: true quando há chave autorizada (as que mudam de valor são canceladas e reemitidas).

minLength15
maxLength255

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