idpath · stringRequiredConstraints
{
"type": "string"
}Parameters, data structure and responses from the versioned contract.
/embarcador/solicitacoes-transporte/{id}/contratarTechnical 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.
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.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.422 (ambiguous_contract_selection_required) listing authorized candidates.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.operacao — Operations[
{
"oauth2": []
},
{
"chaveApi": []
}
]idpath · stringRequired{
"type": "string"
}Idempotency-Keyheader · stringOptional{
"type": "string",
"maxLength": 191
}Optional
application/jsoncarrier_shipper_idinteger | nullOptionalshipper_negotiation_idinteger | nullOptionalrequested_versioninteger | nullOptionalcontract_acceptance_idinteger | nullOptionalacceptedboolean | nullOptionalDoes 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 | nullOptionalexpected_amount_centsinteger | nullOptionalExpected 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 | nullOptionalOptional 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.
200 HTTP ResponseContracting recorded with immutable commercial snapshot
application/json409 HTTP ResponseRequest already contracted with diverging parameters or idempotency conflict
422 HTTP ResponsePending data, contract/link ambiguity, out-of-scope service or missing Spot formal acceptance
{
"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"
}