← InícioFleetPay / API

Contratar solicitação de transporte

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

POST/embarcador/solicitacoes-transporte/{id}/contratar
contratarSolicitacaoTransporteEmbarcadorBase 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.

Efetiva a contratação de uma solicitação de transporte a partir de uma versão comercial válida e formalmente aceita (ShipperContractAcceptance), sob transação com lockForUpdate.

  • Em contrato por período (period_contract), exige vínculo e negociação únicos (ou explicitamente selecionados), dentro da vigência e do escopo da operação, e grava um snapshot imutável da versão e da memória de cálculo no pedido. Alterações posteriores na tabela do contrato não alteram pedidos já contratados.
  • Em Spot (spot), exige que a proposta do gestor já possua termo de aceite formal válido (ShipperContractAcceptance). Enviar apenas accepted=true pela API sem evidência formal de aceite responde 422 (spot_formal_acceptance_required) e preserva a solicitação aguardando aceite formal no painel.
  • Se houver mais de um contrato/vínculo aplicável sem escolha explícita, responde 422 (ambiguous_contract_selection_required) listando os candidatos autorizados.
  • Após a contratação, o atendimento (attendance_status) passa para awaiting_confirmation, sem fingir confirmação operacional, emissão de CT-e ou liberação de pagamento. Caso aggregated_carrier_company_id seja informado na contratação, registra-se apenas a indicação (indicated_aggregated_carrier_company_id), permanecendo attendance_status = awaiting_confirmation até confirmação explícita pelo Gestor de Transporte autorizado em POST /embarcador/solicitacoes-transporte/{id}/confirmar-atendimento.

Autenticação

Escopo Necessário
operacao — Operação
Módulo
Contratação Direta (Embarcador)
Perfis Aplicáveis
Embarcador · Gestor de Transporte · Agregado Empresarial
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

idpath · stringObrigatório
Restrições
{
  "type": "string"
}
Idempotency-Keyheader · stringOpcional
Restrições
{
  "type": "string",
  "maxLength": 191
}

Corpo da Requisição

Opcional

application/json

carrier_shipper_idinteger | nullOpcional
shipper_negotiation_idinteger | nullOpcional
requested_versioninteger | nullOpcional
contract_acceptance_idinteger | nullOpcional
acceptedboolean | nullOpcional

Não substitui o termo de aceite formal (ShipperContractAcceptance). Se enviado como true sem evidência formal de aceite para a versão comercial, a API recusa com 422 spot_formal_acceptance_required.

confirm_uncertaintiesboolean | nullOpcional
expected_amount_centsinteger | nullOpcional

Valor total esperado em centavos (opcional). Se informado e divergir do cálculo canônico do servidor para a versão comercial aceita, a API responde 409 price_mismatch_with_server_calculation.

aggregated_carrier_company_idinteger | nullOpcional

ID opcional do Transportador Agregado indicado (indicated_aggregated_carrier_company_id). Não confirma o atendimento operacional por si só; attendance_status permanece awaiting_confirmation até confirmação pelo Gestor de Transporte autorizado.

Respostas

200 Resposta HTTP

Contratação registrada com snapshot comercial imutável

application/json

successbooleanOpcional
messagestringOpcional
404 Resposta HTTP

Solicitação não encontrada

application/json

errorobjectOpcional
409 Resposta HTTP

Solicitação já contratada com parâmetros divergentes ou conflito de idempotência

application/json

errorobjectOpcional
422 Resposta HTTP

Pendência de dados, ambiguidade de contrato/vínculo, serviço fora do escopo ou ausência de aceite formal Spot

application/json

errorobjectOpcional
Definição Completa da Operação
{
  "tags": [
    "Solicitações e Contratação de Transporte (Embarcador)"
  ],
  "summary": "Contratar solicitação de transporte",
  "description": "Efetiva a contratação de uma solicitação de transporte a partir de uma versão comercial válida e formalmente aceita (`ShipperContractAcceptance`), sob transação com `lockForUpdate`.\n\n- Em **contrato por período** (`period_contract`), exige vínculo e negociação únicos (ou explicitamente selecionados), dentro da vigência e do escopo da operação, e grava um snapshot imutável da versão e da memória de cálculo no pedido. Alterações posteriores na tabela do contrato não alteram pedidos já contratados.\n- Em **Spot** (`spot`), exige que a proposta do gestor já possua termo de aceite formal válido (`ShipperContractAcceptance`). Enviar apenas `accepted=true` pela API sem evidência formal de aceite responde `422` (`spot_formal_acceptance_required`) e preserva a solicitação aguardando aceite formal no painel.\n- Se houver mais de um contrato/vínculo aplicável sem escolha explícita, responde `422` (`ambiguous_contract_selection_required`) listando os candidatos autorizados.\n- Após a contratação, o atendimento (`attendance_status`) passa para `awaiting_confirmation`, sem fingir confirmação operacional, emissão de CT-e ou liberação de pagamento. Caso `aggregated_carrier_company_id` seja informado na contratação, registra-se apenas a indicação (`indicated_aggregated_carrier_company_id`), permanecendo `attendance_status = awaiting_confirmation` até confirmação explícita pelo Gestor de Transporte autorizado em `POST /embarcador/solicitacoes-transporte/{id}/confirmar-atendimento`.\n",
  "operationId": "contratarSolicitacaoTransporteEmbarcador",
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      }
    },
    {
      "name": "Idempotency-Key",
      "in": "header",
      "required": false,
      "schema": {
        "type": "string",
        "maxLength": 191
      }
    }
  ],
  "requestBody": {
    "required": false,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ContratarSolicitacaoTransporteRequest"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Contratação registrada com snapshot comercial imutável",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ContratarSolicitacaoTransporteResponse"
          }
        }
      }
    },
    "404": {
      "description": "Solicitação não encontrada",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Erro"
          }
        }
      }
    },
    "409": {
      "description": "Solicitação já contratada com parâmetros divergentes ou conflito de idempotência",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Erro"
          }
        }
      }
    },
    "422": {
      "description": "Pendência de dados, ambiguidade de contrato/vínculo, serviço fora do escopo ou ausência de aceite formal Spot",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Erro"
          }
        }
      }
    }
  },
  "x-fleetpay-scope": "operacao",
  "x-fleetpay-module": "contratacao-direta",
  "x-fleetpay-profiles": [
    "embarcador",
    "gestor",
    "agregado_empresarial"
  ],
  "method": "POST",
  "path": "/embarcador/solicitacoes-transporte/{id}/contratar"
}