Simulation API

POST /v1/orders-api/vtex/cart/simulation/

Simula um carrinho VTEX e executa o motor de roteamento de pedidos. Retorna a resposta original da simulação VTEX junto com as opções de frete geradas pelo router, mantendo ambos os resultados separados.

Headers

Request Body

{
  "cartSimulation": {
    "items": [
      { "id": "1234", "quantity": "1", "seller": "1" },
      { "id": "5678", "quantity": "2", "seller": "1" }
    ],
    "postalCode": "22071060",
    "country": "BRA",
    "clientProfileData": {
      "email": "cliente@example.com"
    }
  },
  "leanShipping": false
}

Identidade do cliente

Este endpoint chama a simulação stateless da VTEX (/api/checkout/pub/orderForms/simulation), que não tem contexto de sessão de checkout. Toda informação que a engine de preços/promoções precisa para identificar o usuário deve vir explicitamente no body.

Quando clientProfileData.email é necessário:

• O merchant tem uma promoção (frete grátis, desconto, etc.) condicionada a um Customer Cluster do Master Data — ex.: "clientes Prime ganham frete grátis".
• Esse tipo de regra é resolvido na VTEX por identidade do cliente, não por sales channel, price table ou cookie. Sem o email no body, a VTEX simula como visitante anônimo e ignora a regra.

Quando pode ser omitido:

• Simulação sem usuário logado.
• Merchant sem promoções cluster-based — preços/SLAs dependem apenas de SKU, CEP e sales channel.

Response

Headers de resposta:

Body:

{
  "cartSimulation": {
    "items": ["..."],
    "postalCode": "22071060",
    "country": "BRA",
    "logisticsInfo": ["..."],
    "totals": ["..."],
    "pickupPoints": [],
    "messages": []
  },
  "shippingMethods": [
    {
      "index": 0,
      "label": "Normal",
      "shippingType": "DELIVERY",
      "totalPrice": 2500,
      "deliveryTime": "5bd",
      "estimatedDeliveryDate": "2026-02-27T00:00:00+00:00",
      "selected": false,
      "hasMultiplePackages": false,
      "packages": [
        {
          "itemIds": ["1234", "5678"],
          "label": "Normal",
          "value": 2500,
          "deliveryTime": "5bd",
          "estimatedDeliveryDate": "2026-02-27T00:00:00+00:00",
          "sla": {
            "id": "Normal",
            "name": "Normal",
            "deliveryChannel": "delivery",
            "price": 2500,
            "shippingEstimate": "5bd",
            "shippingEstimateDate": "2026-02-27T00:00:00+00:00"
          }
        }
      ]
    }
  ]
}

Campos da Response

cartSimulation

Resposta original da simulação VTEX, sem modificações. Contém toda a informação logística retornada pela API /api/checkout/pub/orderForms/simulation da VTEX.

shippingMethods

Opções de frete geradas pelo motor de roteamento. Cada opção representa uma estratégia completa de fulfillment.

packages[]

Tipos de Frete (shippingType)

Notas

• cartSimulation nunca é modificada pelo motor de roteamento. É retornada exatamente como recebida da VTEX.
• shippingMethods pode ser vazio ([]) se o router não conseguir gerar opções.
• Regras de roteamento são aplicadas por merchant. Se um merchant possui regras customizadas (ex: shipping cap), elas são aplicadas apenas aos shippingMethods.

Visitor ID e consistência A/B

A atribuição de regras de roteamento (que pode estar sob teste A/B por merchant) é feita inteiramente no backend a partir de um identificador opaco de visitante. Você não precisa saber se há experimento ativo nem qual regra está rodando, mas precisa propagar o identificador entre chamadas para que o mesmo carrinho/cliente caia na mesma variante do A/B.

Como funciona:

1. Na chamada inicial (tipicamente /v1/orders-api/vtex/cart/simulation/), você pode enviar x-trinio-visitor-id com um valor estável que você mantém (ex.: UUID anônimo gerado no client). Não use identificadores pessoais (customer ID, e-mail, CPF, etc.) — headers podem ser logados em access logs, traces e ferramentas de observability, o que viraria vazamento de PII.
2. Quando você não envia, o backend gera um ULID e devolve no header de resposta x-trinio-visitor-id.
3. Armazene esse valor e reenvie como header x-trinio-visitor-id em chamadas subsequentes — tipicamente no /v1/orders-api/router/ no momento do checkout.

Por que isso importa: sem propagar o mesmo ID, o usuário pode receber uma variante diferente do A/B entre /v1/orders-api/vtex/cart/simulation/ e /v1/orders-api/router/ — vendo opções de frete que não casam com o que será efetivamente aplicado ao pedido.

Persistência sugerida no client: localStorage no browser, Keychain/EncryptedSharedPreferences em mobile, ou seu próprio mecanismo de sessão server-side.

Integração via Trinio Checkout SDK (plugin VTEX): se você usa o plugin VTEX da Trinio, passe o valor retornado no header x-trinio-visitor-id desta API na prop trinioVisitorId do createCheckout. O plugin propagará automaticamente nas chamadas subsequentes ao /v1/orders-api/router/. Veja trinioVisitorId na doc do SDK.

Exemplos: cURL

Sem identidade (anônimo)

curl -s -X POST https://prod.trinio.ai/v1/orders-api/vtex/cart/simulation/ \
  -H "Content-Type: application/json" \
  -H "x-trinio-merchant-id: <YOUR_MERCHANT_ID>" \
  -d '{
    "cartSimulation": {
      "items": [
        {"id": "1234", "quantity": "1", "seller": "1"},
        {"id": "5678", "quantity": "2", "seller": "1"}
      ],
      "postalCode": "22071060",
      "country": "BRA"
    },
    "leanShipping": false
  }' | jq .

Com identidade (resolve promoções cluster-based)

curl -s -X POST https://prod.trinio.ai/v1/orders-api/vtex/cart/simulation/ \
  -H "Content-Type: application/json" \
  -H "x-trinio-merchant-id: <YOUR_MERCHANT_ID>" \
  -d '{
    "cartSimulation": {
      "items": [
        {"id": "1234", "quantity": "1", "seller": "1"}
      ],
      "postalCode": "22071060",
      "country": "BRA",
      "clientProfileData": {
        "email": "cliente@example.com"
      }
    }
  }' | jq .

Propagando o visitor ID entre /v1/orders-api/vtex/cart/simulation/ e /v1/orders-api/router/

# 1) Primeira chamada — sem visitor id, backend gera e devolve no response header
curl -s -i -X POST https://prod.trinio.ai/v1/orders-api/vtex/cart/simulation/ \
  -H "Content-Type: application/json" \
  -H "x-trinio-merchant-id: <YOUR_MERCHANT_ID>" \
  -d '{ "cartSimulation": { ... } }'

# → response inclui:  x-trinio-visitor-id: 01ARZ3NDEKTSV4RRFFQ69G5FAV

# 2) Chamada subsequente — reenviando o id que veio na response anterior
curl -s -X POST https://prod.trinio.ai/v1/orders-api/router/ \
  -H "Content-Type: application/json" \
  -H "x-trinio-merchant-id: <YOUR_MERCHANT_ID>" \
  -H "x-trinio-visitor-id: 01ARZ3NDEKTSV4RRFFQ69G5FAV" \
  -d '{ "orderForm": { ... } }'

Erros