← HomeFleetPay / API

Reprocess failed batch access keys

Parameters, data structure and responses from the versioned contract.

POST/fiscal/cte-subcontratacao/lote/{batch_id}/reprocessamento
reprocessContraCteBatchSandbox Base: https://api.fleetpay.site/v1

Technical descriptions are translated from the versioned contract. Original identifiers and JSON are preserved; data examples are omitted.

Reissues, in the same batch and same payout group, keys marked failed, awaiting SEFAZ cancellation (cancelling), or stuck pending if processing stopped mid-way. With no body, reprocesses all pending keys; with chaves, only those listed (listing a non-pending key returns 422 chave_sem_pendencia).

An emitted key with financeiro: failed is also pending and is not reissued: the existing counter-CT-e stays (returning outcome: adotado and the same counter_cte_id) and only the payout step is retried.

Fix the root cause first (submit original CT-e XML at POST /fiscal/cte-subcontratacao, register the tax rule...). To change key value, type or route, use PATCH on the key.

Only 1:1 batches with repasse (422 lote_sem_repasse / lote_de_pernas), only the batch creator (the contractor triggering on behalf of the subcontractor — with active authorization — or the issuer itself) and never while still processing (409 lote_em_processamento).

Authentication

Required Scope
fiscal — Tax & Fiscal
Module
Subcontracting
Target Profiles
Fleet Carrier
Schemes
OAuth2 client_credentials (POST /oauth/token) or API Key via Authorization: Bearer / X-Api-Key
[
  {
    "oauth2": []
  },
  {
    "chaveApi": []
  }
]
Availability depends on the environment, enabled scopes and provider. This reference does not execute requests or collect credentials.

Parameters

batch_idpath · stringRequired

Batch UUID returned by POST /fiscal/cte-subcontratacao/lote.

Constraints
{
  "type": "string",
  "format": "uuid"
}

Request Body

Optional

application/json

chavesarrayOptional

Only these keys (44 digits, with or without punctuation). Omitted = all pending.

minItems1

Responses

202 HTTP Response

The batch after the update, in the same format as GET /fiscal/cte-subcontratacao/lote/{batch_id}. 202 when SEFAZ work is in progress (status: processing — track via GET); 200 when the update finished immediately.

application/json

403 HTTP Response

lote_de_outra_transportadora (only the batch creator may edit) or emissao_nao_autorizada (the subcontractor revoked the contractor's authorization). Once authorization is revoked, only deleting a key that was never issued remains open.

application/json

404 HTTP Response

lote_nao_encontrado or chave_nao_encontrada (the key is not part of the batch).

application/json

409 HTTP Response

lote_em_processamento (wait for status to leave processing), grupo_repasse_com_parcelas (the batch payout group already generated an installment — there was a scan — and the batch can no longer change), cancelamento_em_andamento or chave_duplicada (counter-CT-e issued outside the batch: remove, do not update).

application/json

422 HTTP Response

Invalid payload.

application/json

Headers

X-Request-Id

Call correlation identifier.

Complete Operation Definition
{
  "tags": [
    "CT-e de subcontratação"
  ],
  "summary": "Reprocessar as chaves do lote que falharam",
  "operationId": "reprocessContraCteBatch",
  "description": "Reemite, **no mesmo lote e no mesmo grupo de repasse**, as chaves `failed`, as que aguardam o\ncancelamento na SEFAZ (`cancelling`) e as que ficaram `pending` porque o processamento caiu no\nmeio. Sem corpo, reprocessa todas; com `chaves`, só as listadas (uma chave listada que não está\npendente responde `422 chave_sem_pendencia`).\n\nA chave `emitted` com `financeiro: failed` também é pendente, e **não é reemitida**: o\ncontra-CT-e que já saiu é mantido (a linha volta com `outcome: adotado` e o mesmo\n`counter_cte_id`) e só o repasse é refeito.\n\nCorrija a causa antes (entregue o XML do CT-e original em `POST /fiscal/cte-subcontratacao`,\ncadastre a regra de tributação…). Para mudar valor, tipo ou rota da chave, use o `PATCH` da chave.\n\n**Só lote 1:1 com `repasse`** (`422 lote_sem_repasse` / `lote_de_pernas`), **só quem criou o\nlote** (a contratante que o disparou em nome da subcontratada — com a autorização ainda ativa —\nou a própria emitente) e nunca durante o processamento (`409 lote_em_processamento`).\n",
  "parameters": [
    {
      "$ref": "#/components/parameters/ContraCteBatchId"
    }
  ],
  "requestBody": {
    "required": false,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ContraCteLoteReprocessarRequest"
        }
      }
    }
  },
  "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}/reprocessamento"
}