← HomeFleetPay / API

Contract transport request

Parameters, data structure and responses from the versioned contract.

POST/embarcador/solicitacoes-transporte/{id}/contratar
contratarSolicitacaoTransporteEmbarcadorSandbox Base: https://api.fleetpay.site/v1

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

Executes contracting of a transport request from a valid, formally accepted commercial version (ShipperContractAcceptance), inside a transaction with lockForUpdate.

  • Under period contract (period_contract), requires a unique (or explicitly selected) link and negotiation within effective dates and operation scope, persisting an immutable snapshot of version and calculation breakdown onto the order. Subsequent table updates do not alter already-contracted requests.
  • Under Spot (spot), requires that the manager's proposal already holds a valid formal acceptance term (ShipperContractAcceptance). Passing only accepted=true via API without formal acceptance evidence returns 422 (spot_formal_acceptance_required) and leaves the request awaiting formal acceptance in the dashboard.
  • If multiple applicable contracts/links exist without explicit choice, returns 422 (ambiguous_contract_selection_required) listing authorized candidates.
  • After contracting, fulfillment (attendance_status) transitions to awaiting_confirmation, without faking operational confirmation, CT-e issuance or payment release. If aggregated_carrier_company_id is supplied on contracting, only the indication is recorded (indicated_aggregated_carrier_company_id), keeping attendance_status = awaiting_confirmation until explicit confirmation by the authorized Transport Manager at POST /embarcador/solicitacoes-transporte/{id}/confirmar-atendimento.

Authentication

Required Scope
operacao — Operations
Module
Direct Contracting (Shipper)
Target Profiles
Shipper · Transport Manager · Dedicated Fleet Contractor
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

idpath · stringRequired
Constraints
{
  "type": "string"
}
Idempotency-Keyheader · stringOptional
Constraints
{
  "type": "string",
  "maxLength": 191
}

Request Body

Optional

application/json

carrier_shipper_idinteger | nullOptional
shipper_negotiation_idinteger | nullOptional
requested_versioninteger | nullOptional
contract_acceptance_idinteger | nullOptional
acceptedboolean | nullOptional

Does not replace the formal acceptance term (ShipperContractAcceptance). If sent as true without formal acceptance evidence for the commercial version, the API rejects with 422 spot_formal_acceptance_required.

confirm_uncertaintiesboolean | nullOptional
expected_amount_centsinteger | nullOptional

Expected total amount in cents (optional). If provided and differs from the canonical server calculation for the accepted commercial version, the API responds 409 price_mismatch_with_server_calculation.

aggregated_carrier_company_idinteger | nullOptional

Optional ID of the indicated Aggregated Carrier (indicated_aggregated_carrier_company_id). Does not confirm operational fulfillment by itself; attendance_status stays awaiting_confirmation until confirmation by the authorized Transport Manager.

Responses

200 HTTP Response

Contracting recorded with immutable commercial snapshot

application/json

successbooleanOptional
messagestringOptional
404 HTTP Response

Request not found

application/json

errorobjectOptional
409 HTTP Response

Request already contracted with diverging parameters or idempotency conflict

application/json

errorobjectOptional
422 HTTP Response

Pending data, contract/link ambiguity, out-of-scope service or missing Spot formal acceptance

application/json

errorobjectOptional
Complete Operation Definition
{
  "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"
}