API atual/Referência completa/Frete e entrega

Estimativa de frete

Estimativa rápida de preço e prazo de frete para um CEP, para a página do produto e o carrinho.

Use na página do produto e no carrinho, para o cliente ver preço e prazo sem montar o carrinho inteiro. O limite de corpo é 1 MB.

POST/api/v1/storefront/shipping/estimatePública

Estimativa rápida de frete por CEP

A estimativa rápida do botão "Calcular frete" da página do produto e do carrinho. Devolve as opções por CEP, com preço e uma data de chegada pronta para exibir, na ordem de posição que o administrador definiu.

Corpo da requisição

postal_codestringobrigatório

CEP do destino, 8 dígitos, com ou sem hífen. Letras e sentinelas (00000000, 99999999) são recusadas.

itemsobject[]obrigatório

Itens, de 1 a 100.

items[].product_iduuidobrigatório

Produto.

items[].quantityintegerpadrão: 1

Quantidade, maior que zero.

items[].weightinteger

Peso em gramas. Vale o que você enviar; se omitir, vem do catálogo.

items[].widthinteger

Largura em cm. Mesma regra.

items[].heightinteger

Altura em cm. Mesma regra.

items[].lengthinteger

Comprimento em cm. Mesma regra.

items[].vendor_iduuid

Seller. Se omitir, vem do catálogo.

items[].priceinteger

Preço unitário em centavos. Se omitir, vem do catálogo.

items[].free_shippingboolean

Produto com frete grátis. Se omitir, vem do catálogo.

subtotalinteger

Subtotal do carrinho em centavos, usado em regras de frete grátis e faixas por valor.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/shipping/estimate" \
  -H "Content-Type: application/json" \
  -d '{
  "postal_code": "01310-100",
  "items": [
    {
      "product_id": "22fbd12a-1b6e-41ea-a84f-4d9cf06c8766",
      "quantity": 1
    }
  ],
  "subtotal": 30000
}'

Resposta

200Opções de frete

json

{
  "postal_code": "01310-100",
  "rates": [
    {
      "method_id": "85e87a54-dcee-4947-8cfa-f6406f2f3cbb",
      "method_name": "Motoboy",
      "method_code": "motoboy_msdxztz7",
      "price": 500,
      "delivery_days_min": 2,
      "delivery_days_max": 2,
      "delivery_estimate": "qui., 15 de out.",
      "icon": "📦",
      "free_shipping": false,
      "is_pickup": false
    },
    {
      "method_id": "50000000-0000-0000-0000-000000000003",
      "method_name": "Frete Grátis acima de R$199",
      "method_code": "free_above_199",
      "price": 0,
      "delivery_days_min": 10,
      "delivery_days_max": 10,
      "delivery_estimate": "ter., 27 de out.",
      "icon": "🎉",
      "free_shipping": true,
      "is_pickup": false
    }
  ],
  "free_shipping_threshold": 0
}

Campos da resposta

postal_codestring

O CEP no formato 00000-000.

ratesobject[]

Opções, na ordem de posição dos métodos (a rota não reordena por preço).

rates[].method_iduuid

Id do método.

rates[].method_namestring

Nome.

rates[].method_codestring

Código do método. Ausente se vazio.

rates[].priceinteger

Preço em centavos. 0 é grátis.

rates[].delivery_days_mininteger

Menor prazo em dias úteis.

rates[].delivery_days_maxinteger

Maior prazo em dias úteis.

rates[].delivery_estimatestring

Texto pronto: uma data (qui., 15 de out.) ou uma faixa (3-5 dias úteis), conforme o formato configurado pela loja na Janela de Entrega.

rates[].iconstring

Emoji de apoio.

rates[].free_shippingboolean

Frete grátis.

rates[].is_pickupboolean

Retirada em loja.

free_shipping_thresholdinteger

Valor, em centavos, a partir do qual o frete é grátis para toda a loja. 0 quando não há.

unavailableobject[]

Métodos que não puderam ser cotados, com code e message. Ausente se nada foi excluído. Mesmo formato de Cotar frete.

Erros

Status	Quando	Corpo
400	Corpo que não é JSON.	`{"error":"invalid request body","detail":"..."}`
400	CEP malformado ou sentinela.	`{"error":"invalid_postal_code","detail":"invalid CEP: expected 8 digits (e.g. 01310-100)"}`
400	Sem itens.	`{"error":"at least one item is required"}`
400	Mais de 100 itens.	`{"error":"too many items: maximum 100 allowed"}`
400	Quantidade menor que 1.	`{"error":"invalid_quantity","detail":"quantity must be a positive whole number"}`
500	`product_id` que não é UUID, ou falha interna.	`{"error":"failed to calculate shipping rates","detail":"..."}`

Veja também