← HomeFleetPay / API

Scan documents of a counter-CT-e batch (trip start)

Parameters, data structure and responses from the versioned contract.

POST/carriers/parcelas-repasse/bipar-por-lote
biparPorLoteSandbox Base: https://api.fleetpay.site/v1

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

Batch scan: at trip start, provide the counter-CT-e batch batch_id and FleetPay scans every key's document with the batch driver, one by one, matching driver app scanning. Scanning creates the delivery, service and payout installments following the driver's rule so liberar-por-mdfe and pagar-por-mdfe can act on them.

Rules:

  • Only the batch creator may call. On subcontractor-behalf batches, that is the contractor with active subcontractor authorization.
  • Only keys with authorized counter-CT-e. Others return pendente_fiscal / contra_cte_nao_autorizado; re-call after reprocessing.
  • Idempotent. Already-scanned documents return ja_bipado without duplicating deliveries.
  • Prior driver binding. Bound to another driver returns recusada / documento_vinculado_a_outro_motorista.
  • Caller company only (ignorado / documento_de_outra_empresa), same as MDF-e routes.
  • While a key stays pending, the batch payout group is held: the scan is recorded and installments materialize once the group closes. After the first scan, values and key counts cannot change (409 grupo_repasse_com_parcelas on edit).

Legs batches (per-leg driver) and fiscal-only batches return 422; batches still processing return 409.

Authentication

Required Scope
operacao — Operations
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

No parameters declared for this operation.

Request Body

Required

application/json

batch_idstringRequired

The batch_id returned when creating the counter-CT-e batch.

maxLength64

Responses

200 HTTP Response

The batch was processed; read resumo and documentos[].resultado.

application/json

401 HTTP Response

Unauthenticated (autenticacao): missing, invalid or expired credentials, including an API key used in the wrong environment. A sandbox key is not valid in production, nor a production key in the sandbox; the error message indicates the expected environment.

application/json

errorobjectOptional
403 HTTP Response

Credential without operacao scope; batch created by another carrier (lote_de_outra_transportadora); or subcontractor authorization revoked (emissao_nao_autorizada).

application/json

errorobjectOptional
404 HTTP Response

Batch not found, or owned by another carrier (lote_nao_encontrado).

application/json

errorobjectOptional
409 HTTP Response

Batch still processing (lote_em_processamento).

application/json

errorobjectOptional
422 HTTP Response

Legs batch (lote_de_pernas), tax-only batch (lote_sem_repasse), batch without driver (lote_sem_motorista) or invalid payload.

application/json

errorobjectOptional
Complete Operation Definition
{
  "tags": [
    "Parcelas"
  ],
  "summary": "Bipar os documentos de um lote de contra-CT-e (início da viagem)",
  "operationId": "biparPorLote",
  "description": "A **bipagem em lote**: no início da viagem, informe o `batch_id` do lote de contra-CT-e e a\nFleetPay bipa o documento de cada chave, com o motorista do lote, como o motorista faria no\napp, um a um. É a bipagem que cria a entrega, o serviço e as **parcelas do repasse**: a\nparcela de bipagem inicial segue a regra do motorista. Depois dela, as rotas\n`liberar-por-mdfe` e `pagar-por-mdfe` já encontram as parcelas.\n\nRegras:\n\n- **Só quem criou o lote chama.** No lote disparado em nome da subcontratada, é a\n  contratante, com a autorização da subcontratada ainda ativa.\n- **Só chave com contra-CT-e autorizado.** As outras voltam\n  `pendente_fiscal / contra_cte_nao_autorizado`; chame de novo depois do reprocessamento.\n- **Idempotente.** Documento já bipado volta `ja_bipado`, sem entrega nova.\n- **Vínculo prévio do motorista.** Documento vinculado a outro motorista volta\n  `recusada / documento_vinculado_a_outro_motorista`.\n- **Só o documento da empresa que chamou** (`ignorado / documento_de_outra_empresa`), como nas\n  rotas do MDF-e.\n- Com chave ainda pendente, o grupo de repasse do lote fica retido: a bipagem é registrada e\n  as parcelas nascem quando o grupo fechar. Depois da primeira bipagem, o lote não aceita\n  mais mudança de valores nem de quantidade de chaves (`409 grupo_repasse_com_parcelas` na\n  edição).\n\nLote de pernas (um motorista por perna) e lote só fiscal respondem `422`; lote ainda em\nprocessamento, `409`.\n",
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/BiparPorLote"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "O lote foi processado; leia `resumo` e `documentos[].resultado`.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/RespostaBipagemPorLote"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Erro401"
    },
    "403": {
      "description": "Credencial sem o escopo `operacao`; lote criado por outra transportadora\n(`lote_de_outra_transportadora`); ou autorização da subcontratada revogada\n(`emissao_nao_autorizada`).\n",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Erro"
          }
        }
      }
    },
    "404": {
      "description": "Lote não encontrado, ou de outra transportadora (`lote_nao_encontrado`).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Erro"
          }
        }
      }
    },
    "409": {
      "description": "Lote ainda em processamento (`lote_em_processamento`).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Erro"
          }
        }
      }
    },
    "422": {
      "description": "Lote de pernas (`lote_de_pernas`), lote só fiscal (`lote_sem_repasse`), lote sem\nmotorista (`lote_sem_motorista`) ou payload inválido.\n",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Erro"
          }
        }
      }
    }
  },
  "x-fleetpay-scope": "operacao",
  "x-fleetpay-module": "subcontratacao",
  "x-fleetpay-profiles": [
    "transportador_frotista"
  ],
  "method": "POST",
  "path": "/carriers/parcelas-repasse/bipar-por-lote",
  "parameters": []
}