← InicioFleetPay / API

Contratar solicitud de transporte

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

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

Efectúa la contratación de una solicitud de transporte a partir de una versión comercial válida y formalmente aceptada (ShipperContractAcceptance), bajo transacción con lockForUpdate.

  • En contrato por período (period_contract), exige vínculo y negociación únicos (o seleccionados explícitamente), dentro de la vigencia y alcance operacional, y graba un snapshot inmutable de versión y memoria de cálculo en el pedido. Cambios posteriores en la tabla del contrato no alteran pedidos ya contratados.
  • En Spot (spot), exige que la propuesta del gestor ya posea término de aceptación formal válido (ShipperContractAcceptance). Enviar solo accepted=true vía API sin evidencia formal responde 422 (spot_formal_acceptance_required) y mantiene la solicitud esperando aceptación formal en el panel.
  • Si existe más de un contrato/vínculo aplicable sin elección explícita, responde 422 (ambiguous_contract_selection_required) listando los candidatos autorizados.
  • Tras contratar, la atención (attendance_status) pasa a awaiting_confirmation, sin simular confirmación operacional, emisión de CT-e ni liberación de pago. Si se informa aggregated_carrier_company_id, solo se registra la indicación (indicated_aggregated_carrier_company_id), permaneciendo attendance_status = awaiting_confirmation hasta confirmación explícita por el Gestor de Transporte autorizado en POST /embarcador/solicitacoes-transporte/{id}/confirmar-atendimento.

Autenticación

Permiso Requerido
operacao — Operación
Módulo
Contratación Directa (Embarcador)
Perfiles Aplicables
Embarcador · Gestor de Transporte · Agregado Empresarial
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

idpath · stringObligatorio
Restricciones
{
  "type": "string"
}
Idempotency-Keyheader · stringOpcional
Restricciones
{
  "type": "string",
  "maxLength": 191
}

Cuerpo de la Solicitud

Opcional

application/json

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

No sustituye al término de aceptación formal (ShipperContractAcceptance). Si se envía como true sin evidencia formal de aceptación para la versión comercial, la API rechaza con 422 spot_formal_acceptance_required.

confirm_uncertaintiesboolean | nullOpcional
expected_amount_centsinteger | nullOpcional

Valor total esperado en centavos (opcional). Si se informa y diverge del cálculo canónico del servidor para la versión comercial aceptada, la API responde 409 price_mismatch_with_server_calculation.

aggregated_carrier_company_idinteger | nullOpcional

ID opcional del Transportador Agregado indicado (indicated_aggregated_carrier_company_id). No confirma la atención operacional por sí solo; attendance_status permanece awaiting_confirmation hasta confirmación por el Gestor de Transporte autorizado.

Respuestas

200 Respuesta HTTP

Contratación registrada con snapshot comercial inmutable

application/json

successbooleanOpcional
messagestringOpcional
404 Respuesta HTTP

Solicitud no encontrada

application/json

errorobjectOpcional
409 Respuesta HTTP

Solicitud ya contratada con parámetros divergentes o conflicto de idempotencia

application/json

errorobjectOpcional
422 Respuesta HTTP

Pendencia de datos, ambigüedad de contrato/vínculo, servicio fuera del alcance o falta de aceptación formal Spot

application/json

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