API legada/Referência completa/Vitrine /api/storefront

POSTCalcular frete

Cota as formas de envio, com preço e prazo, para uma lista de itens e um CEP de destino, antes ou durante o checkout.

Recebe os itens de uma sacola e o destino e devolve cada forma de envio que atende, com o preço e o prazo. Use na página do carrinho ("calcule o frete") ou antes de criar a sessão de checkout. Não precisa de carrinho nem de login: você descreve os itens no próprio corpo.

A cotação é de leitura: não grava nada e não escolhe o frete. A escolha acontece no passo de frete do checkout, em que o servidor cota de novo para o endereço final.

Para um produto só, com a resposta no formato da 1.0, existe Cotação de frete.

POST/api/storefront/shipping/calculatePública

Cotar frete para uma lista de itens e um CEP

Corpo da requisição

itemsarrayobrigatório

Itens da sacola, ao menos um.

product_iduuidobrigatório

Id do produto.

quantityintegerobrigatório

Quantidade, inteiro maior que zero.

priceinteger

Preço unitário em centavos. Entra nas regras de frete grátis por valor.

vendor_iduuid

Seller dono do item, quando você já sabe.

weightinteger

Peso do item em gramas.

widthinteger

Largura em cm.

heightinteger

Altura em cm.

lengthinteger

Comprimento em cm.

free_shippingboolean

Item com frete grátis próprio.

postal_codestring

CEP de destino, com ou sem hífen. Obrigatório (ou os campos de localização) quando há produto físico.

country_codestring

País (BR). CEP só é validado para o Brasil.

state_codestring

Sigla do estado, alternativa ao CEP.

city_iduuid

Cidade cadastrada, alternativa ao CEP.

district_iduuid

Bairro cadastrado, alternativa ao CEP.

citystring

Nome da cidade; sem ele, é buscado pelo CEP.

districtstring

Nome do bairro; sem ele, é buscado pelo CEP.

cart_totalinteger

Valor da sacola em centavos, para regras de frete grátis por valor mínimo.

address_iduuid

Endereço salvo do cliente, para áreas de entrega desenhadas no mapa.

streetstring

Rua do destino, para áreas desenhadas no mapa.

numberstring

Número do destino.

address_districtstring

Bairro do destino.

address_citystring

Cidade do destino.

Cabeçalhos

Authorizationstring

Opcional. Token de app Bearer vat_... com o escopo read_shipping.

Exemplo de requisição

bash

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

Resposta

200Formas de envio do destino (reduzida a 2 itens)

json

{
  "postal_code": "01310100",
  "rates": [
    {
      "method_id": "85e87a54-dcee-4947-8cfa-f6406f2f3cbb",
      "method_display_id": 53,
      "method_name": "Motoboy",
      "method_code": "motoboy_msdxztz7",
      "cost": 500,
      "estimated_days": 0,
      "min_delivery_days": 0,
      "max_delivery_days": 0,
      "delivery_time": "30 min",
      "free_shipping": false,
      "is_pickup": false,
      "shipping_id": "85e87a54-dcee-4947-8cfa-f6406f2f3cbb",
      "shipping": "Motoboy",
      "rate_str": "5.00"
    },
    {
      "method_id": "50000000-0000-0000-0000-000000000001",
      "method_display_id": 5,
      "method_name": "Entrega Padrão",
      "method_code": "standard",
      "cost": 1000,
      "estimated_days": 10,
      "min_delivery_days": 10,
      "max_delivery_days": 10,
      "delivery_time": "7-10 dias úteis",
      "free_shipping": false,
      "is_pickup": false,
      "shipping_id": "50000000-0000-0000-0000-000000000001",
      "shipping": "Entrega Padrão",
      "rate_str": "10.00"
    }
  ]
}

Campos da resposta

postal_codestring

CEP normalizado, só dígitos.

ratesarray

Uma entrada por forma de envio elegível. Vazia quando nenhuma atende.

rates[].method_iduuid

Id da forma de envio. É o valor de shipping_method_id no passo de frete do checkout. shipping_id repete o valor.

rates[].method_namestring

Nome para exibir. shipping repete o valor.

rates[].method_codestring

Código estável da forma de envio.

rates[].costinteger

Preço do frete em centavos. rate_str repete em reais, como texto.

rates[].estimated_daysinteger

Prazo estimado em dias.

rates[].min_delivery_daysinteger

Menor prazo da faixa, em dias.

rates[].max_delivery_daysinteger

Maior prazo da faixa, em dias.

rates[].delivery_timestring

Texto de prazo para exibir (7-10 dias úteis). Pode faltar.

rates[].free_shippingboolean

true se o frete é grátis nesta cotação.

rates[].is_pickupboolean

true para retirada em loja.

rates[].service_codestring

Serviço da transportadora, quando a forma expande várias opções (PAC, SEDEX). Pode faltar.

Erros

Status	Quando	Corpo
400	Corpo que não é JSON	`{"error": "invalid request body", "detail": "..."}`
400	`items` ausente ou vazio	`{"error": "at least one item is required"}`
400	`quantity` zero, negativa ou não inteira	`{"error": "invalid_quantity", "detail": "items[0].quantity must be a positive whole number"}`
400	CEP brasileiro que não tem 8 dígitos ou é sentinela (`00000000`)	`{"error": "invalid_postal_code", "detail": "..."}`
400	Produto físico sem CEP nem localização	`{"error": "shipping_location_required", "detail": "postal_code or location fields are required for physical products"}`
403	Token de app sem o escopo `read_shipping`	`{"error": "missing_scope", "required": "read_shipping"}`
500	Falha ao calcular	`{"error": "failed to calculate shipping rates", ...}`

Veja também

POSTCalcular frete

Cota as formas de envio, com preço e prazo, para uma lista de itens e um CEP de destino, antes ou durante o checkout.

A cotação é de leitura: não grava nada e não escolhe o frete. A escolha acontece no passo de frete do checkout, em que o servidor cota de novo para o endereço final.

Para um produto só, com a resposta no formato da 1.0, existe Cotação de frete.

POST/api/storefront/shipping/calculatePública

Cotar frete para uma lista de itens e um CEP

Corpo da requisição

itemsarrayobrigatório

Itens da sacola, ao menos um.

product_iduuidobrigatório

Id do produto.

quantityintegerobrigatório

Quantidade, inteiro maior que zero.

priceinteger

Preço unitário em centavos. Entra nas regras de frete grátis por valor.

vendor_iduuid

Seller dono do item, quando você já sabe.

weightinteger

Peso do item em gramas.

widthinteger

Largura em cm.

heightinteger

Altura em cm.

lengthinteger

Comprimento em cm.

free_shippingboolean

Item com frete grátis próprio.

postal_codestring

CEP de destino, com ou sem hífen. Obrigatório (ou os campos de localização) quando há produto físico.

country_codestring

País (BR). CEP só é validado para o Brasil.

state_codestring

Sigla do estado, alternativa ao CEP.

city_iduuid

Cidade cadastrada, alternativa ao CEP.

district_iduuid

Bairro cadastrado, alternativa ao CEP.

citystring

Nome da cidade; sem ele, é buscado pelo CEP.

districtstring

Nome do bairro; sem ele, é buscado pelo CEP.

cart_totalinteger

Valor da sacola em centavos, para regras de frete grátis por valor mínimo.

address_iduuid

Endereço salvo do cliente, para áreas de entrega desenhadas no mapa.

streetstring

Rua do destino, para áreas desenhadas no mapa.

numberstring

Número do destino.

address_districtstring

Bairro do destino.

address_citystring

Cidade do destino.

Cabeçalhos

Authorizationstring

Opcional. Token de app Bearer vat_... com o escopo read_shipping.

Exemplo de requisição

bash

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

Resposta

200Formas de envio do destino (reduzida a 2 itens)

json

{
  "postal_code": "01310100",
  "rates": [
    {
      "method_id": "85e87a54-dcee-4947-8cfa-f6406f2f3cbb",
      "method_display_id": 53,
      "method_name": "Motoboy",
      "method_code": "motoboy_msdxztz7",
      "cost": 500,
      "estimated_days": 0,
      "min_delivery_days": 0,
      "max_delivery_days": 0,
      "delivery_time": "30 min",
      "free_shipping": false,
      "is_pickup": false,
      "shipping_id": "85e87a54-dcee-4947-8cfa-f6406f2f3cbb",
      "shipping": "Motoboy",
      "rate_str": "5.00"
    },
    {
      "method_id": "50000000-0000-0000-0000-000000000001",
      "method_display_id": 5,
      "method_name": "Entrega Padrão",
      "method_code": "standard",
      "cost": 1000,
      "estimated_days": 10,
      "min_delivery_days": 10,
      "max_delivery_days": 10,
      "delivery_time": "7-10 dias úteis",
      "free_shipping": false,
      "is_pickup": false,
      "shipping_id": "50000000-0000-0000-0000-000000000001",
      "shipping": "Entrega Padrão",
      "rate_str": "10.00"
    }
  ]
}

Campos da resposta

postal_codestring

CEP normalizado, só dígitos.

ratesarray

Uma entrada por forma de envio elegível. Vazia quando nenhuma atende.

rates[].method_iduuid

Id da forma de envio. É o valor de shipping_method_id no passo de frete do checkout. shipping_id repete o valor.

rates[].method_namestring

Nome para exibir. shipping repete o valor.

rates[].method_codestring

Código estável da forma de envio.

rates[].costinteger

Preço do frete em centavos. rate_str repete em reais, como texto.

rates[].estimated_daysinteger

Prazo estimado em dias.

rates[].min_delivery_daysinteger

Menor prazo da faixa, em dias.

rates[].max_delivery_daysinteger

Maior prazo da faixa, em dias.

rates[].delivery_timestring

Texto de prazo para exibir (7-10 dias úteis). Pode faltar.

rates[].free_shippingboolean

true se o frete é grátis nesta cotação.

rates[].is_pickupboolean

true para retirada em loja.

rates[].service_codestring

Serviço da transportadora, quando a forma expande várias opções (PAC, SEDEX). Pode faltar.

Erros

Status	Quando	Corpo
400	Corpo que não é JSON	`{"error": "invalid request body", "detail": "..."}`
400	`items` ausente ou vazio	`{"error": "at least one item is required"}`
400	`quantity` zero, negativa ou não inteira	`{"error": "invalid_quantity", "detail": "items[0].quantity must be a positive whole number"}`
400	CEP brasileiro que não tem 8 dígitos ou é sentinela (`00000000`)	`{"error": "invalid_postal_code", "detail": "..."}`
400	Produto físico sem CEP nem localização	`{"error": "shipping_location_required", "detail": "postal_code or location fields are required for physical products"}`
403	Token de app sem o escopo `read_shipping`	`{"error": "missing_scope", "required": "read_shipping"}`
500	Falha ao calcular	`{"error": "failed to calculate shipping rates", ...}`