API legada/Referência completa/Frete e rotas

GETCotação de frete

Devolve as formas de entrega disponíveis, com preço e prazo, para um produto e um CEP, no formato da Venddor 1.0.

Dado um produto e um CEP de destino, devolve cada forma de entrega que atende esse CEP, com o preço e o prazo. É a cotação "rápida" que ERPs e vitrines antigas usam em uma página de produto, antes de existir carrinho. A conta usa o peso do produto, o seller dono dele e o preço unitário vezes a quantidade (para regras de frete grátis por valor).

Ela não considera cupons, promoções de carrinho nem os demais itens de um carrinho. Para cotar uma sacola completa, use o cálculo de frete da vitrine (Calcular frete).

GET/api/v1.0/delivery_methodsAutenticada

Cotar frete por produto e CEP

Parâmetros de consulta

product_iduuidobrigatório

Id do produto. Na URL sem v1.0, aceita também o id numérico legado do produto.

zipcodestringobrigatório

CEP de destino. Qualquer texto não vazio é aceito, inclusive com hífen (01310-100). O servidor não valida o formato: um CEP inválido devolve as formas de envio gerais da loja.

quantityintegerpadrão: 1

Quantidade do produto. Valor menor que 1 ou inválido vira 1.

Cabeçalhos

Authorizationstringobrigatório

Basic base64(e-mail:chave_de_api) ou Bearer $TOKEN. Qualquer usuário autenticado serve, não só administrador.

GET/api/delivery_methodsAutenticada

Alias de GET /api/v1.0/delivery_methods

Mesmo corpo, mesma resposta e mesmo comportamento de GET /api/v1.0/delivery_methods. Nesta URL (sem /v1.0), os ids de entidades usam o formato numérico legado.

Exemplo de requisição

bash

curl -u "$EMAIL:$API_KEY" \
  "$BASE_URL/api/v1.0/delivery_methods?product_id=22fbd12a-1b6e-41ea-a84f-4d9cf06c8766&zipcode=01310-100&quantity=2"

Resposta

200Formas de entrega do CEP

json

{
  "delivery_methods": [
    {
      "shipping_id": "85e87a54-dcee-4947-8cfa-f6406f2f3cbb",
      "shipping": "Motoboy",
      "rate": "5.00",
      "delivery_time": 0,
      "free_shipping": "N"
    },
    {
      "shipping_id": "50000000-0000-0000-0000-000000000003",
      "shipping": "Frete Grátis acima de R$199",
      "rate": "0.00",
      "delivery_time": 10,
      "free_shipping": "Y"
    }
  ],
  "params": { "page": 1, "items_per_page": 2, "total_items": 2 }
}

Campos da resposta

delivery_methodsarray

Uma entrada por forma de entrega elegível. A lista pode vir vazia se nenhuma atende.

delivery_methods[].shipping_iduuid

Id da forma de envio. Na URL sem v1.0 é um inteiro, e formas de envio diferentes podem ter o mesmo número (veja o aviso abaixo).

delivery_methods[].shippingstring

Nome da forma de envio, como a loja cadastrou.

delivery_methods[].ratestring

Preço do frete em reais, string decimal com duas casas ("10.00"). Não são centavos.

delivery_methods[].delivery_timeinteger

Prazo estimado em dias. 0 quando a forma não informa prazo (por exemplo, entrega por motoboy).

delivery_methods[].free_shippingstring

YN

Y se o frete é grátis nesta cotação. Letra, não booleano.

paramsobject

Paginação sintética: page sempre 1, items_per_page e total_items iguais ao número de formas devolvidas. Não há paginação real.

Erros

Status	Quando	Corpo
400	`product_id` ausente	`{"message": "product_id is required", "status": 400}`
400	`zipcode` ausente	`{"message": "zipcode is required", "status": 400}`
401	Sem credencial ou credencial inválida	`{"message": "Authentication required. Use HTTP Basic with email:api_key or Bearer <jwt>.", "status": 401}`
404	Produto não existe	`{"message": "Product not found", "status": 404}`
500	`product_id` que não é UUID, ou falha no cálculo	`{"message": "Failed to look up product: ...", "status": 500}` ou `Failed to calculate shipping: ...`

Veja também