VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Frete e entrega

Data de entrega

Estima a data de chegada de um produto, ou de vários de uma vez, considerando preparo, horário de corte e dias úteis.

A janela de entrega é o módulo que transforma "prazo em dias" numa data: considera quanto tempo a loja leva para separar o pedido, até que horas ela ainda despacha no mesmo dia, e pula fins de semana e feriados. O resultado é o que a vitrine mostra como "Receba até quinta, 15/out".

Data de um produto

GET/api/v1/storefront/delivery-estimatePública

Data estimada de entrega de um produto

Estima a data em que um produto chega, somando o tempo de preparo da loja, o horário de corte, o calendário de dias úteis e feriados e o prazo do método. Exige o módulo delivery-window.

Parâmetros de consulta

product_iduuid
Produto.
postal_codestring
CEP do destino.
shipping_method_iduuid
Método de envio cujo prazo usar. Sem ele, vale o método mais rápido.
min_daysinteger
Prazo mínimo de trânsito (dias) já cotado, de 1 a 120. Valor fora do intervalo é ignorado.
max_daysinteger
Prazo máximo de trânsito (dias) já cotado, de 1 a 120. Use min_days/max_days para a data bater com o prazo de uma cotação em tempo real.

Exemplo de requisição

Resposta

200Estimativa

Campos da resposta

earliest_datestring
Data mais cedo, YYYY-MM-DD.
latest_datestring
Data mais tarde, YYYY-MM-DD.
business_daysinteger
Dias úteis até a data mais tarde (preparo + trânsito máximo).
business_days_mininteger
Dias úteis até a data mais cedo.
display_textstring
Texto pronto para exibir, no formato escolhido pela loja.
display_formatstring
date_rangebusiness_dayshidden
Como a loja quer exibir: date_range (mostrar a data), business_days (mostrar "X-Y dias úteis") ou hidden (nunca mostrar data de calendário).
buy_by_datestring
"Compre até" (YYYY-MM-DD), só em janelas de dia fixo. Ausente nas demais.
fixed_windowboolean
Presente (true) quando a data vem da regra de dia fixo, que conta dias corridos (sem feriados nem horário de corte).

Erros

StatusQuandoCorpo
403Módulo delivery-window desligado na loja.{"error":"module_disabled","module":"delivery-window"}
500Falha ao calcular a data (por exemplo product_id que não é UUID).{"error":"failed to calculate delivery estimate","detail":"..."}

Promessa em lote

POST/api/v1/storefront/delivery-promisePública

Promessa de entrega em lote

Para listagens e carrinho: resolve, numa só chamada, a promessa mais cedo de cada produto para um CEP. Produto sem método elegível simplesmente não aparece no resultado (sem selo, sem erro). Exige o módulo delivery-window.

Corpo da requisição

postal_codestringobrigatório
CEP do destino. Vazio devolve promises vazio (sem chute nacional).
product_idsuuid[]obrigatório
Produtos a consultar.

Exemplo de requisição

Resposta

200Promessas por produto

Campos da resposta

postal_codestring
O CEP enviado. Vazio se você não enviou.
promisesobject
Mapa do id do produto para a promessa. Produto sem promessa não aparece.
promises.{id}.delivery_datestring
YYYY-MM-DD.
promises.{id}.formattedstring
Data por extenso curta, para exibir.
promises.{id}.method_iduuid
Método que dá a entrega mais cedo.
promises.{id}.method_namestring
Nome do método.
promises.{id}.cutoff_atstring
RFC 3339 (fuso de São Paulo): até quando comprar para valer esta data.
promises.{id}.ships_todayboolean
true quando um pedido feito agora ainda é despachado hoje.
promises.{id}.display_formatstring
Mesmo significado de display_format acima. A data só deve aparecer em date_range.

Erros

StatusQuandoCorpo
400Corpo que não é JSON.{"error":"invalid request body","detail":"..."}
403Módulo delivery-window desligado na loja.{"error":"module_disabled","module":"delivery-window"}
500Falha ao calcular as promessas.{"error":"failed to calculate delivery promises","detail":"..."}
Dê o mesmo prazo da cotação à data

Depois de cotar o frete em tempo real, chame delivery-estimate com shipping_method_id, min_days e max_days do método escolhido: a data exibida bate com o prazo cotado em vez de usar o prazo cadastrado.

Sem `product_id`, ainda responde

A rota não exige product_id. Sem ele (ou com um produto que não existe), devolve uma data com os padrões da loja. Sempre envie o produto para a data refletir o preparo dele.

Veja também

  • Estimativa de frete
  • Pontos de retirada
Anterior
Pedido mínimo e frete grátis
Próxima
Pontos de retirada
Nesta página
  • Data de um produto
  • Exemplo de requisição
  • Resposta
  • Erros
  • Promessa em lote
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também
bash
curl "$BASE_URL/api/v1/storefront/delivery-estimate?product_id=22fbd12a-1b6e-41ea-a84f-4d9cf06c8766&postal_code=01310100"
bash
curl -X POST "$BASE_URL/api/v1/storefront/delivery-promise" \
  -H "Content-Type: application/json" \
  -d '{
  "postal_code": "01310-100",
  "product_ids": [
    "22fbd12a-1b6e-41ea-a84f-4d9cf06c8766"
  ]
}'
json
{
  "earliest_date": "2026-10-15",
  "latest_date": "2026-10-16",
  "business_days": 2,
  "business_days_min": 2,
  "display_text": "qui., 15 de out.",
  "display_format": "date_range"
}
json
{
  "postal_code": "01310-100",
  "promises": {
    "22fbd12a-1b6e-41ea-a84f-4d9cf06c8766": {
      "delivery_date": "2026-10-15",
      "formatted": "quinta, 15/out",
      "method_id": "85e87a54-dcee-4947-8cfa-f6406f2f3cbb",
      "method_name": "Motoboy",
      "cutoff_at": "2026-10-11T14:00:00-03:00",
      "ships_today": false,
      "display_format": "date_range"
    }
  }
}