YOM Docs

Untitled

Preço de entrega

A YOM pode delegar ao sistema do cliente o cálculo do custo de entrega de um pedido. Quando um comércio ou um vendedor cota ou confirma um pedido, a YOM envia uma requisição HTTP POST ao endpoint do cliente com o detalhe do Order. O cliente responde com o custo líquido da entrega, ou indica que não pode cotá-la.

<aside> 📝

O cliente só precisa expor o endpoint e informar à YOM sua URL. Nenhuma outra configuração é necessária.

</aside>

Quando a YOM o chama

A consulta ocorre em quatro momentos, sempre de forma síncrona:

• Cotação prévia a partir do tomador de pedidos do vendedor.
• Cotação prévia a partir da plataforma B2B web.
• Ao criar o pedido a partir da plataforma B2B web.
• Ao criar o pedido a partir do tomador de pedidos do vendedor.

Um mesmo pedido gera, portanto, mais de uma chamada: pelo menos uma ao cotar na tela e outra ao confirmá-lo.

<aside> ⚠️

A consulta é totalmente omitida quando o comércio não tem código no sistema do cliente. Sem order.externalId não há cotação e o pedido é criado com entrega em 0.

</aside>

Endpoint

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

Corpo da requisição

{
  "order": { ... }
}

Campos

Order

A entidade order, dentro da chave order do corpo.

ShippingAddress

O objeto order.shippingAddress, com o destino da entrega.

<aside> ℹ️

Nas cotações prévias o pedido ainda não existe: é um rascunho montado com o que está na tela. Apenas os campos marcados como obrigatórios estão garantidos; o restante pode chegar vazio ou ausente.

</aside>

Resposta esperada

O endpoint deve responder 200 com Content-Type: application/json.

<aside> 🚨

O campo netValue deve vir sempre. A YOM valida transportationCost, mas guarda netValue: uma resposta que traz o primeiro e omite o segundo é aceita como cotação válida e deixa o pedido com entrega em 0, sem nenhum erro visível. É a falha mais frequente ao conectar uma integração nova.

</aside>

Entrega cotada

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

Entrega grátis

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

Sem cotação

Uma resposta 200 que não inclua transportationCost é interpretada como se não tivesse havido cotação. O pedido é criado da mesma forma, com entrega em 0, salvo se o cliente tiver ativada a exigência de cotação.

{}

Rejeição com motivo

Quando a entrega não pode ser cotada por uma razão de negócio — comuna fora de cobertura, peso máximo excedido, janela de entrega indisponível —, o endpoint deve responder um status 4xx com a explicação no corpo. A YOM a captura e a exibe ao usuário tal como está.

O texto é buscado, nesta ordem, em errors.message, detail ou message; se o corpo for texto simples, é usado por completo.

HTTP/1.1 422
Content-Type: application/json

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

O usuário vê esse mesmo texto na tela e o pedido não avança.

<aside> 🛑

Um 5xx nunca é interpretado como rejeição. Um erro de servidor é uma falha de infraestrutura, não uma decisão de negócio: é traduzido para um erro genérico que o comprador não consegue resolver. Para comunicar um motivo é preciso responder 4xx.

</aside>

Exemplo

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": { ... }}'

Considerações

<aside> ⏱️

O endpoint deve responder em menos de 30 segundos. Passados 60 segundos a conexão é cortada e a cotação se perde.

</aside>

• Não há retentativas. Cada cotação é uma única chamada.
• O endpoint deve ser somente de leitura e idempotente. Um mesmo pedido gera várias chamadas.
• Os valores vão na moeda do cliente. O contrato não inclui nenhum campo de moeda: assume-se a mesma do restante do pedido. Convém devolver os três valores já arredondados para a precisão dessa moeda.
• O custo de entrega não é somado ao total do pedido. Viaja como um valor à parte, e assim chega também ao sistema do cliente.
• Uma cotação falha não impede criar o pedido. Por padrão o pedido é criado com entrega em 0. Se o cliente preferir que um pedido sem cotação não possa ser criado, a YOM pode ativar essa exigência; nesse caso o comprador vê o motivo da rejeição.
• O objeto order inclui campos adicionais aos descritos neste documento. Recomenda-se usar apenas os campos necessários e tolerar o surgimento de novos campos.