API atual/Referência completa/Frete e entrega

Cotar frete

Cota o frete de um carrinho para um CEP, consolidado ou separado por seller.

Esta é a cotação oficial: a mesma regra que o checkout usa ao fechar o pedido. Ela olha a lista de métodos, as áreas de tarifa e os grupos de clientes, consulta as transportadoras em tempo real quando o método é desse tipo e devolve o preço e o prazo de cada opção.

Se você só quer "quanto custa o frete para este CEP" numa página de produto, Estimativa de frete é mais simples.

Cotação consolidada

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

Cota o frete do carrinho

Devolve os métodos de envio que servem para o carrinho inteiro, com o custo total de cada um. Se o carrinho tem itens de mais de um seller, só aparecem os métodos que todos os sellers oferecem, e o custo é a soma.

Corpo da requisição

postal_codestringobrigatório

CEP do destino, 8 dígitos, com ou sem hífen. Obrigatório para carrinho com produto físico (sem ele: 400 shipping_location_required, a não ser que mande a localização por outros campos).

itemsobject[]obrigatório

Linhas do carrinho. Pelo menos uma.

items[].product_iduuidobrigatório

Produto. Tem de existir no catálogo e não estar apagado.

items[].quantityintegerobrigatório

Quantidade, inteiro maior que zero. Zero, negativo ou null dão 400 invalid_quantity.

items[].vendor_iduuid

Aceito, mas ignorado: o seller vem do catálogo.

items[].priceinteger

Aceito, mas ignorado: o preço vem do catálogo.

items[].weightinteger

Aceito, mas ignorado: peso (gramas) vem do catálogo.

items[].widthinteger

Aceito, mas ignorado: medidas (cm) vêm do catálogo.

items[].heightinteger

Aceito, mas ignorado.

items[].lengthinteger

Aceito, mas ignorado.

items[].free_shippingboolean

Aceito, mas ignorado: vem do cadastro do produto.

cart_totalinteger

Aceito, mas ignorado: o total é recalculado a partir dos preços do catálogo.

country_codestring

País do destino (BR). Opcional.

state_codestring

UF do destino. Opcional: deduzida do CEP.

city_iduuid

Cidade do cadastro de localidades. Opcional.

district_iduuid

Bairro do cadastro de localidades. Opcional.

citystring

Nome da cidade, para áreas de tarifa por cidade. Opcional: deduzido do CEP.

districtstring

Nome do bairro. Opcional.

latnumber

Latitude do destino, só usada em áreas desenhadas no mapa.

lngnumber

Longitude do destino.

address_iduuid

Endereço salvo do cliente logado. Usado para localizar o ponto de entrega em áreas desenhadas.

streetstring

Rua digitada, para localizar o ponto de entrega.

numberstring

Número do endereço.

address_districtstring

Bairro do endereço digitado.

address_citystring

Cidade do endereço digitado.

Exemplo de requisição

bash

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

Resposta

200Métodos para o carrinho

json

{
  "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
    },
    {
      "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
    }
  ],
  "postal_code": "01310100",
  "weight": 0
}

Campos da resposta

ratesobject[]

Opções de frete para o carrinho, na ordem de posição dos métodos. Vazio quando nenhum método serve (veja unavailable).

rates[].method_iduuid

Id do método de envio. É o que você envia ao fechar o pedido.

rates[].method_display_idinteger

Número curto do método, para exibição.

rates[].method_namestring

Nome do método.

rates[].method_codestring

Código estável do método.

rates[].costinteger

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

rates[].carrier_costinteger

Custo cobrado pela transportadora, em centavos. Só aparece quando difere do cost.

rates[].estimated_daysinteger

Prazo em dias do método (o maior, na cotação consolidada). 0 quando é imediato ou não informado.

rates[].min_delivery_daysinteger

Menor prazo em dias.

rates[].max_delivery_daysinteger

Maior prazo em dias.

rates[].delivery_timestring

Texto de prazo para exibir (7-10 dias úteis). Ausente quando não há texto.

rates[].free_shippingboolean

true quando o frete saiu grátis (regra do método, produto ou promoção).

rates[].is_pickupboolean

true quando é retirada em loja, não entrega.

rates[].is_fallbackboolean

Presente (true) quando o preço é uma estimativa porque a transportadora não respondeu. Mostre "frete estimado".

rates[].delivery_estimatedboolean

Presente (true) quando o preço é da transportadora, mas o prazo é o configurado no método, não uma promessa dela.

rates[].service_codestring

Serviço específico dentro do método (por exemplo PAC ou SEDEX), quando o método devolve várias opções. Envie junto com method_id ao escolher.

rates[].carrierstring

Nome da transportadora, quando houver.

rates[].quote_idstring

Referência opaca da cotação em tempo real. Pode ser repassada ao checkout, que revalida.

rates[].volume_countinteger

Volumes (caixas) considerados na cotação em tempo real.

rates[].icon_urlstring

Ícone configurado para o método.

postal_codestring

O CEP usado, só com dígitos.

weightinteger

Peso total do carrinho em gramas, conforme o catálogo.

no_shipping_requiredboolean

true (e rates vazio) quando todos os itens são digitais: não há frete a cobrar.

selected_method_iduuid

Método pré-selecionado, quando a loja define um.

unavailableobject[]

Métodos ativos que não puderam ser cotados, com o motivo. Ausente quando nada foi excluído.

unavailable[].method_iduuid

Método excluído.

unavailable[].method_namestring

Nome do método.

unavailable[].codestring

Motivo estável: product_without_weight, product_without_dimensions, package_over_limit, route_not_served, service_not_in_contract, delivery_time_refused, invalid_postal_code, carrier_not_configured, carrier_unavailable, quote_refused, declared_value_out_of_range, outside_delivery_area, address_not_located.

unavailable[].messagestring

Texto em português para exibir. Traduza pelo code em outros idiomas.

unavailable[].reasonstring

Causa mais específica, opcional (por exemplo package_split_required, volume_limit_exceeded).

Erros

Status	Quando	Corpo
400	Corpo que não é JSON.	`{"error":"invalid request body","detail":"..."}`
400	Carrinho sem itens.	`{"error":"at least one item is required"}`
400	Quantidade zero, negativa ou nula.	`{"error":"invalid_quantity","detail":"items[0].quantity must be a positive whole number"}`
400	CEP malformado ou sentinela (`00000000`, `99999999`).	`{"error":"invalid_postal_code","detail":"invalid CEP: expected 8 digits (e.g. 01310-100)"}`
400	Produto físico sem CEP nem localização.	`{"error":"shipping_location_required","detail":"postal_code or location fields are required for physical products"}`
500	`product_id` que não é UUID, produto inexistente ou apagado, ou falha interna.	`{"error":"failed to calculate shipping rates","detail":"product ... is unavailable for shipping"}`

Cotação por seller

POST/api/v1/storefront/shipping/calculate-by-vendorPública

Cota o frete separado por seller

Mesmo corpo, mas a resposta traz um grupo por seller, cada um com os seus itens e os seus métodos. É a cotação do checkout de marketplace, em que o cliente escolhe um método por seller.

Corpo da requisição

(mesmos campos de /shipping/calculate)object

Veja o corpo da rota acima.

Exemplo de requisição

bash

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

Resposta

200Um grupo por seller

json

{
  "vendors": [
    {
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "vendor_name": "Loja Seller Teste",
      "items": [
        {
          "product_id": "22fbd12a-1b6e-41ea-a84f-4d9cf06c8766",
          "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
          "quantity": 2,
          "price": 30000,
          "weight": 0,
          "width": 0,
          "height": 0,
          "length": 0,
          "free_shipping": false
        }
      ],
      "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
        }
      ],
      "weight": 0
    }
  ],
  "postal_code": "01310100"
}

Campos da resposta

vendorsobject[]

Um grupo por seller. Itens sem seller formam um grupo da própria loja.

vendors[].vendor_idstring

Seller do grupo. _marketplace para itens da loja.

vendors[].vendor_namestring

Nome do seller.

vendors[].itemsobject[]

Itens do grupo como o servidor os entendeu (preço em centavos, peso em gramas e medidas em cm, do catálogo).

vendors[].ratesobject[]

Métodos que este seller oferece. Mesmo formato de rates[] da cotação consolidada.

vendors[].weightinteger

Peso do grupo em gramas.

vendors[].unavailableobject[]

Métodos do seller que não puderam ser cotados. Ausente se nada foi excluído.

postal_codestring

O CEP usado, só com dígitos.

no_shipping_requiredboolean

true quando tudo é digital.

Erros

Os mesmos erros da cotação consolidada.

Veja também

API atual/Referência completa/Frete e entrega

Cotar frete

Cota o frete de um carrinho para um CEP, consolidado ou separado por seller.

Se você só quer "quanto custa o frete para este CEP" numa página de produto, Estimativa de frete é mais simples.

Cotação consolidada

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

Cota o frete do carrinho

Corpo da requisição

postal_codestringobrigatório

CEP do destino, 8 dígitos, com ou sem hífen. Obrigatório para carrinho com produto físico (sem ele: 400 shipping_location_required, a não ser que mande a localização por outros campos).

itemsobject[]obrigatório

Linhas do carrinho. Pelo menos uma.

items[].product_iduuidobrigatório

Produto. Tem de existir no catálogo e não estar apagado.

items[].quantityintegerobrigatório

Quantidade, inteiro maior que zero. Zero, negativo ou null dão 400 invalid_quantity.

items[].vendor_iduuid

Aceito, mas ignorado: o seller vem do catálogo.

items[].priceinteger

Aceito, mas ignorado: o preço vem do catálogo.

items[].weightinteger

Aceito, mas ignorado: peso (gramas) vem do catálogo.

items[].widthinteger

Aceito, mas ignorado: medidas (cm) vêm do catálogo.

items[].heightinteger

Aceito, mas ignorado.

items[].lengthinteger

Aceito, mas ignorado.

items[].free_shippingboolean

Aceito, mas ignorado: vem do cadastro do produto.

cart_totalinteger

Aceito, mas ignorado: o total é recalculado a partir dos preços do catálogo.

country_codestring

País do destino (BR). Opcional.

state_codestring

UF do destino. Opcional: deduzida do CEP.

city_iduuid

Cidade do cadastro de localidades. Opcional.

district_iduuid

Bairro do cadastro de localidades. Opcional.

citystring

Nome da cidade, para áreas de tarifa por cidade. Opcional: deduzido do CEP.

districtstring

Nome do bairro. Opcional.

latnumber

Latitude do destino, só usada em áreas desenhadas no mapa.

lngnumber

Longitude do destino.

address_iduuid

Endereço salvo do cliente logado. Usado para localizar o ponto de entrega em áreas desenhadas.

streetstring

Rua digitada, para localizar o ponto de entrega.

numberstring

Número do endereço.

address_districtstring

Bairro do endereço digitado.

address_citystring

Cidade do endereço digitado.

Exemplo de requisição

bash

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

Resposta

200Métodos para o carrinho

json

{
  "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
    },
    {
      "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
    }
  ],
  "postal_code": "01310100",
  "weight": 0
}

Campos da resposta

ratesobject[]

Opções de frete para o carrinho, na ordem de posição dos métodos. Vazio quando nenhum método serve (veja unavailable).

rates[].method_iduuid

Id do método de envio. É o que você envia ao fechar o pedido.

rates[].method_display_idinteger

Número curto do método, para exibição.

rates[].method_namestring

Nome do método.

rates[].method_codestring

Código estável do método.

rates[].costinteger

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

rates[].carrier_costinteger

Custo cobrado pela transportadora, em centavos. Só aparece quando difere do cost.

rates[].estimated_daysinteger

Prazo em dias do método (o maior, na cotação consolidada). 0 quando é imediato ou não informado.

rates[].min_delivery_daysinteger

Menor prazo em dias.

rates[].max_delivery_daysinteger

Maior prazo em dias.

rates[].delivery_timestring

Texto de prazo para exibir (7-10 dias úteis). Ausente quando não há texto.

rates[].free_shippingboolean

true quando o frete saiu grátis (regra do método, produto ou promoção).

rates[].is_pickupboolean

true quando é retirada em loja, não entrega.

rates[].is_fallbackboolean

Presente (true) quando o preço é uma estimativa porque a transportadora não respondeu. Mostre "frete estimado".

rates[].delivery_estimatedboolean

Presente (true) quando o preço é da transportadora, mas o prazo é o configurado no método, não uma promessa dela.

rates[].service_codestring

Serviço específico dentro do método (por exemplo PAC ou SEDEX), quando o método devolve várias opções. Envie junto com method_id ao escolher.

rates[].carrierstring

Nome da transportadora, quando houver.

rates[].quote_idstring

Referência opaca da cotação em tempo real. Pode ser repassada ao checkout, que revalida.

rates[].volume_countinteger

Volumes (caixas) considerados na cotação em tempo real.

rates[].icon_urlstring

Ícone configurado para o método.

postal_codestring

O CEP usado, só com dígitos.

weightinteger

Peso total do carrinho em gramas, conforme o catálogo.

no_shipping_requiredboolean

true (e rates vazio) quando todos os itens são digitais: não há frete a cobrar.

selected_method_iduuid

Método pré-selecionado, quando a loja define um.

unavailableobject[]

Métodos ativos que não puderam ser cotados, com o motivo. Ausente quando nada foi excluído.

unavailable[].method_iduuid

Método excluído.

unavailable[].method_namestring

Nome do método.

unavailable[].codestring

unavailable[].messagestring

Texto em português para exibir. Traduza pelo code em outros idiomas.

unavailable[].reasonstring

Causa mais específica, opcional (por exemplo package_split_required, volume_limit_exceeded).

Erros

Status	Quando	Corpo
400	Corpo que não é JSON.	`{"error":"invalid request body","detail":"..."}`
400	Carrinho sem itens.	`{"error":"at least one item is required"}`
400	Quantidade zero, negativa ou nula.	`{"error":"invalid_quantity","detail":"items[0].quantity must be a positive whole number"}`
400	CEP malformado ou sentinela (`00000000`, `99999999`).	`{"error":"invalid_postal_code","detail":"invalid CEP: expected 8 digits (e.g. 01310-100)"}`
400	Produto físico sem CEP nem localização.	`{"error":"shipping_location_required","detail":"postal_code or location fields are required for physical products"}`
500	`product_id` que não é UUID, produto inexistente ou apagado, ou falha interna.	`{"error":"failed to calculate shipping rates","detail":"product ... is unavailable for shipping"}`

Cotação por seller

POST/api/v1/storefront/shipping/calculate-by-vendorPública

Cota o frete separado por seller

Mesmo corpo, mas a resposta traz um grupo por seller, cada um com os seus itens e os seus métodos. É a cotação do checkout de marketplace, em que o cliente escolhe um método por seller.

Corpo da requisição

(mesmos campos de /shipping/calculate)object

Veja o corpo da rota acima.

Exemplo de requisição

bash

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

Resposta

200Um grupo por seller

json

{
  "vendors": [
    {
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "vendor_name": "Loja Seller Teste",
      "items": [
        {
          "product_id": "22fbd12a-1b6e-41ea-a84f-4d9cf06c8766",
          "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
          "quantity": 2,
          "price": 30000,
          "weight": 0,
          "width": 0,
          "height": 0,
          "length": 0,
          "free_shipping": false
        }
      ],
      "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
        }
      ],
      "weight": 0
    }
  ],
  "postal_code": "01310100"
}

Campos da resposta

vendorsobject[]

Um grupo por seller. Itens sem seller formam um grupo da própria loja.

vendors[].vendor_idstring

Seller do grupo. _marketplace para itens da loja.

vendors[].vendor_namestring

Nome do seller.

vendors[].itemsobject[]

Itens do grupo como o servidor os entendeu (preço em centavos, peso em gramas e medidas em cm, do catálogo).

vendors[].ratesobject[]

Métodos que este seller oferece. Mesmo formato de rates[] da cotação consolidada.

vendors[].weightinteger

Peso do grupo em gramas.

vendors[].unavailableobject[]

Métodos do seller que não puderam ser cotados. Ausente se nada foi excluído.

postal_codestring

O CEP usado, só com dígitos.

no_shipping_requiredboolean

true quando tudo é digital.

Erros

Os mesmos erros da cotação consolidada.