← InícioFleetPay / API

Bipar os documentos de um lote de contra-CT-e (início da viagem)

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

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

A bipagem em lote: no início da viagem, informe o batch_id do lote de contra-CT-e e a FleetPay bipa o documento de cada chave, com o motorista do lote, como o motorista faria no app, um a um. É a bipagem que cria a entrega, o serviço e as parcelas do repasse: a parcela de bipagem inicial segue a regra do motorista. Depois dela, as rotas liberar-por-mdfe e pagar-por-mdfe já encontram as parcelas.

Regras:

  • Só quem criou o lote chama. No lote disparado em nome da subcontratada, é a contratante, com a autorização da subcontratada ainda ativa.
  • Só chave com contra-CT-e autorizado. As outras voltam pendente_fiscal / contra_cte_nao_autorizado; chame de novo depois do reprocessamento.
  • Idempotente. Documento já bipado volta ja_bipado, sem entrega nova.
  • Vínculo prévio do motorista. Documento vinculado a outro motorista volta recusada / documento_vinculado_a_outro_motorista.
  • Só o documento da empresa que chamou (ignorado / documento_de_outra_empresa), como nas rotas do MDF-e.
  • Com chave ainda pendente, o grupo de repasse do lote fica retido: a bipagem é registrada e as parcelas nascem quando o grupo fechar. Depois da primeira bipagem, o lote não aceita mais mudança de valores nem de quantidade de chaves (409 grupo_repasse_com_parcelas na edição).

Lote de pernas (um motorista por perna) e lote só fiscal respondem 422; lote ainda em processamento, 409.

Autenticação

Escopo Necessário
operacao — Operação
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

Nenhum parâmetro declarado nesta operação.

Corpo da Requisição

Obrigatório

application/json

batch_idstringObrigatório

O batch_id devolvido na criação do lote de contra-CT-e.

maxLength64

Respostas

200 Resposta HTTP

O lote foi processado; leia resumo e documentos[].resultado.

application/json

401 Resposta HTTP

Não autenticado (autenticacao): credencial ausente, inválida ou expirada — inclusive chave de API usada no ambiente errado. A chave de homologação não vale em produção, nem a de produção em homologação; a mensagem do erro indica o ambiente esperado.

application/json

errorobjectOpcional
403 Resposta HTTP

Credencial sem o escopo operacao; lote criado por outra transportadora (lote_de_outra_transportadora); ou autorização da subcontratada revogada (emissao_nao_autorizada).

application/json

errorobjectOpcional
404 Resposta HTTP

Lote não encontrado, ou de outra transportadora (lote_nao_encontrado).

application/json

errorobjectOpcional
409 Resposta HTTP

Lote ainda em processamento (lote_em_processamento).

application/json

errorobjectOpcional
422 Resposta HTTP

Lote de pernas (lote_de_pernas), lote só fiscal (lote_sem_repasse), lote sem motorista (lote_sem_motorista) ou payload inválido.

application/json

errorobjectOpcional
Definição Completa da Operação
{
  "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": []
}