← InicioFleetPay / API

Escanear documentos de un lote de contra-CT-e (inicio del viaje)

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

POST/carriers/parcelas-repasse/bipar-por-lote
biparPorLoteBase 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.

Escaneo en lote: al inicio del viaje, informe el batch_id del lote de contra-CT-e y FleetPay escanea el documento de cada clave con el conductor del lote, uno a uno, igual que en la app. El escaneo crea la entrega, el servicio y las cuotas del pago al conductor, habilitando liberar-por-mdfe y pagar-por-mdfe.

Reglas:

  • Solo quien creó el lote llama. En lote a nombre de subcontratada, es la contratante con autorización vigente.
  • Solo clave con contra-CT-e autorizado. Las demás vuelven pendente_fiscal / contra_cte_nao_autorizado; llame tras reprocesar.
  • Idempotente. Documento ya escaneado vuelve ja_bipado sin duplicar entrega.
  • Vínculo previo. Vinculado a otro conductor vuelve recusada / documento_vinculado_a_outro_motorista.
  • Solo de la empresa que llama (ignorado / documento_de_outra_empresa).
  • Con clave pendiente, el grupo queda retenido hasta cerrarse. Tras el primer escaneo, el lote no acepta cambios de valor ni cantidad (409 grupo_repasse_com_parcelas).

Lote por tramos y lote solo fiscal responden 422; en procesamiento, 409.

Autenticación

Permiso Requerido
operacao — Operación
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

No hay parámetros declarados para esta operación.

Cuerpo de la Solicitud

Obligatorio

application/json

batch_idstringObligatorio

El batch_id devuelto al crear el lote de contra-CT-e.

maxLength64

Respuestas

200 Respuesta HTTP

El lote fue procesado; consulta resumo y documentos[].resultado.

application/json

401 Respuesta HTTP

Sin autenticación (autenticacao): credencial ausente, inválida o vencida, incluida una clave API utilizada en el entorno incorrecto. La clave de homologación no es válida en producción, ni la de producción en homologación; el mensaje de error indica el entorno esperado.

application/json

errorobjectOpcional
403 Respuesta HTTP

Credencial sin permiso operacao; lote creado por otro transportista (lote_de_outra_transportadora); o autorización de la subcontratada revocada (emissao_nao_autorizada).

application/json

errorobjectOpcional
404 Respuesta HTTP

Lote no encontrado o de otro transportista (lote_nao_encontrado).

application/json

errorobjectOpcional
409 Respuesta HTTP

Lote aún en procesamiento (lote_em_processamento).

application/json

errorobjectOpcional
422 Respuesta HTTP

Lote por tramos (lote_de_pernas), lote solo fiscal (lote_sem_repasse), lote sin conductor (lote_sem_motorista) o payload inválido.

application/json

errorobjectOpcional
Definición Completa de la Operación
{
  "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": []
}