Solicitar demo Demo

Marketplace externo

Cotización de reparto externo

OperioHub solicita una propuesta y la flota responde en la misma llamada con precio, ETAs y rider previsto.

Ver referencia Todos los endpoints
Volver a todos los endpoints

Marketplace externo

Cotización de reparto externo

La URL, Bearer opcional y timeout se configuran en la interfaz de OperioHub. Esta ficha documenta el intercambio una vez activada la flota externa; no documenta APIs de configuración.

POST quoteEndpointUrl configurado en la interfaz 200-299 con propuesta JSON
Sin auth Perfil: Bearer opcional configurado en la interfaz

Requisitos para solicitud y respuesta síncronas

  • Responder con HTTP 2xx y un body JSON completo.
  • Devolver los mismos marketplaceOrderRequestId y orderId recibidos.
  • No incluir campos adicionales fuera del contrato.
  • Una respuesta no válida, tardía o no 2xx se descarta como propuesta inválida.

Campos principales

Resumen de los campos relevantes para este endpoint.

Campo Tipo Uso Descripción
protocolVersion literal 1 Solicitud Versión fija del contrato.
marketplaceOrderRequestId uuid Solicitud y respuesta Correlaciona la propuesta con la solicitud de Marketplace.
order MarketplaceOperationalOrder Solicitud Pedido operativo con recogida, entrega, notas de entrega y pago; no contiene customerInfo, límites de selección, asignación ni liquidaciones.
externalQuoteId string Respuesta opcional Referencia de la propuesta en el sistema de la flota.
priceAmount / currency decimal / EUR Respuesta Coste propuesto y moneda, que actualmente debe ser EUR.
pickupEtaAt / deliveryEtaAt / validUntil ISO 8601 Respuesta ETAs y caducidad de la oferta. La recogida no puede ser posterior a la entrega y la oferta debe seguir vigente.
rider object Respuesta externalRiderId obligatorio y, opcionalmente, nombre, teléfono y vehículo.

Respuesta de propuesta

La respuesta se entrega en la misma conexión HTTP; no se envía a un endpoint de OperioHub separado.

  • OperioHub solo compara propuestas que cumplan sus límites internos de precio y ETA.
  • La cotización no declara ningún webhook de chat.
  • La flota ganadora declara el webhook para recibir mensajes de OperioHub en el ACK de adjudicación.

Respuesta 200

{
  "marketplaceOrderRequestId": "22222222-2222-4222-8222-222222222222",
  "orderId": "11111111-1111-4111-8111-111111111111",
  "externalQuoteId": "FLEET-QUOTE-42",
  "priceAmount": "7.50",
  "currency": "EUR",
  "pickupEtaAt": "2026-07-15T10:20:00.000Z",
  "deliveryEtaAt": "2026-07-15T10:45:00.000Z",
  "validUntil": "2026-07-15T10:10:00.000Z",
  "rider": { "externalRiderId": "rider-42", "displayName": "Rider externo", "phone": null, "vehicleType": "motorcycle" }
}

Request JSON

{
  "protocolVersion": 1,
  "marketplaceOrderRequestId": "22222222-2222-4222-8222-222222222222",
  "order": {
    "orderId": "11111111-1111-4111-8111-111111111111",
    "dispatchOrderId": "POS-93442",
    "currentStatus": "pending_approval",
    "createdAt": "2026-07-15T10:00:00.000Z",
    "updatedAt": "2026-07-15T10:00:00.000Z",
    "deliveryInfo": {
      "pickupAddress": "Calle Recogida 1, Alicante",
      "pickupLat": 38.344498,
      "pickupLng": -0.509259,
      "deliveryAddress": "Calle Entrega 2, Alicante",
      "deliveryLat": 38.346158,
      "deliveryLng": -0.510089,
      "deliveryNotes": "Portal B"
    },
    "paymentInfo": {
      "method": "cash",
      "status": "pending",
      "totalAmount": "18.50",
      "currency": "EUR",
      "cashExpectedAmount": "20.00"
    }
  }
}

Errores esperados

Respuestas habituales que debe contemplar la integración.

400

Propuesta inválida

Faltan campos, los IDs no coinciden, la moneda no es EUR o las fechas no son válidas.

408

Timeout

La flota no respondió dentro del timeout configurado; OperioHub descarta la propuesta.

502

Respuesta no aceptada

La flota respondió con un estado no 2xx o con JSON no interpretable.