YOM Docs

Untitled

Precio de despacho

YOM puede delegar en el sistema del cliente el cálculo del costo de despacho de un pedido. Cuando un comercio o un vendedor cotiza o confirma un pedido, YOM envía una solicitud HTTP POST al endpoint del cliente con el detalle del Order. El cliente responde con el costo neto del despacho, o indica que no puede cotizarlo.

<aside> 📝

El cliente solo debe exponer el endpoint e informar a YOM su URL. No se requiere ninguna otra configuración.

</aside>

Cuándo lo llama YOM

La consulta ocurre en cuatro momentos, siempre de forma sincrónica:

• Cotización previa desde el tomador de pedidos del vendedor.
• Cotización previa desde la plataforma B2B web.
• Al crear el pedido desde la plataforma B2B web.
• Al crear el pedido desde el tomador de pedidos del vendedor.

Un mismo pedido genera por lo tanto más de una llamada: al menos una al cotizar en pantalla y otra al confirmarlo.

<aside> ⚠️

La consulta se omite por completo cuando el comercio no tiene código en el sistema del cliente. Sin order.externalId no hay cotización y el pedido se crea con despacho en 0.

</aside>

Endpoint

POST <tu_dominio>/webhooks/yom/order/delivery-price

Cuerpo de la solicitud

{
  "order": { ... }
}

Campos

Order

La entidad order, dentro de la clave order del cuerpo.

ShippingAddress

El objeto order.shippingAddress, con el destino del despacho.

<aside> ℹ️

En las cotizaciones previas el pedido todavía no existe: es un borrador armado con lo que hay en pantalla. Solo los campos marcados como requeridos están garantizados; el resto puede llegar vacío o ausente.

</aside>

Respuesta esperada

El endpoint debe responder 200 con Content-Type: application/json.

<aside> 🚨

El campo netValue debe venir siempre. YOM valida transportationCost, pero guarda netValue: una respuesta que trae el primero y omite el segundo se acepta como cotización válida y deja el pedido con despacho en 0, sin ningún error visible. Es la falla más frecuente al conectar una integración nueva.

</aside>

Despacho cotizado

{
  "transportationCost": 1500,
  "netValue": 1500,
  "netTaxedValue": 1785,
  "taxesApplied": {"code": 14, "value": 0.19}
}

Despacho gratis

{
  "transportationCost": 0,
  "netValue": 0,
  "netTaxedValue": 0,
  "taxesApplied": {"code": 14, "value": 0.19}
}

Sin cotización

Una respuesta 200 que no incluya transportationCost se interpreta como que no hubo cotización. El pedido se crea igual, con despacho en 0, salvo que el cliente tenga activada la exigencia de cotización.

{}

Rechazo con motivo

Cuando el despacho no se puede cotizar por una razón de negocio — comuna fuera de cobertura, peso máximo excedido, ventana de entrega no disponible —, el endpoint debe responder un status 4xx con la explicación en el cuerpo. YOM la toma y la muestra al usuario tal cual.

El texto se busca, en este orden, en errors.message, detail o message; si el cuerpo es texto plano, se usa completo.

HTTP/1.1 422
Content-Type: application/json

{
  "message": "No existen parámetros de despacho hacia la comuna de destino."
}

El usuario ve ese mismo texto en pantalla y el pedido no avanza.

<aside> 🛑

Un 5xx nunca se interpreta como rechazo. Un error de servidor es una falla de infraestructura, no una decisión de negocio: se traduce a un error genérico que el comprador no puede resolver. Para comunicar un motivo hay que responder 4xx.

</aside>

Ejemplo

POST <https://api.cliente.com/webhooks/yom/order/delivery-price>
Content-Type: application/json
Accept: application/json
x-auth-token: 6a5a8ee27726337b51c72405
origin: legacy.youorder.me

{
  "order": {
    "externalId": "10023456",
    "domain": "cliente.youorder.me",
    "commerceId": "6412f0a1b2c3d4e5f6a7b8c9",
    "commerceName": "Minimarket Los Aromos",
    "distributionCenterId": "64aa11bb22cc33dd44ee55ff",
    "estimatedDeliverAt": "2026-09-18T00:00:00.000Z",
    "type": "order",
    "status": "pending",
    "shippingAddress": {
      "name": "Bodega central",
      "address": "Av. Siempre Viva 742",
      "commune": "Maipú",
      "city": "Santiago",
      "metadata": {
        "coordinates": {"latitude": -33.5110, "longitude": -70.7580},
        "administrativeAreaLevel1": {"longName": "Región Metropolitana"},
        "country": {"longName": "Chile"}
      }
    },
    "products": [
      {"sku": "SKU-001", "quantity": 12, "pricing": {"totalPrice": 35880}}
    ],
    "pricing": {
      "totalPrice": 35880,
      "netTotalPrice": 30151,
      "finalTotalPrice": 35880,
      "shipping": {"netValue": 0, "netTaxedValue": 0}
    }
  }
}

curl -X POST \
  '<https://api.cliente.com/webhooks/yom/order/delivery-price>' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'x-auth-token: 6a5a8ee27726337b51c72405' \
  -d '{"order": { ... }}'

Consideraciones

<aside> ⏱️

El endpoint debe responder en menos de 30 segundos. Pasados los 60 segundos la conexión se corta y la cotización se pierde.

</aside>

• No hay reintentos. Cada cotización es una única llamada.
• El endpoint debe ser de solo lectura e idempotente. Un mismo pedido genera varias llamadas.
• Los montos van en la moneda del cliente. El contrato no incluye ningún campo de moneda: se asume la misma del resto del pedido. Conviene devolver los tres montos ya redondeados a la precisión de esa moneda.
• El costo de despacho no se suma al total del pedido. Viaja como un monto aparte, y así llega también al sistema del cliente.
• Una cotización fallida no impide crear el pedido. Por defecto el pedido se crea con despacho en 0. Si el cliente prefiere que un pedido sin cotizar no pueda crearse, YOM puede activar esa exigencia; en ese caso el comprador ve el motivo del rechazo.
• El objeto order incluye campos adicionales a los descritos en este documento. Se recomienda usar solo los campos necesarios y tolerar la aparición de campos nuevos.