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

bash

curl "$BASE_URL/api/v1/storefront/delivery-estimate?product_id=22fbd12a-1b6e-41ea-a84f-4d9cf06c8766&postal_code=01310100"

Resposta

200Estimativa

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"
}

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

Status	Quando	Corpo
403	Módulo `delivery-window` desligado na loja.	`{"error":"module_disabled","module":"delivery-window"}`
500	Falha 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

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"
  ]
}'

Resposta

200Promessas por produto

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"
    }
  }
}

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

Status	Quando	Corpo
400	Corpo que não é JSON.	`{"error":"invalid request body","detail":"..."}`
403	Módulo `delivery-window` desligado na loja.	`{"error":"module_disabled","module":"delivery-window"}`
500	Falha ao calcular as promessas.	`{"error":"failed to calculate delivery promises","detail":"..."}`

Veja também

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.

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

bash

curl "$BASE_URL/api/v1/storefront/delivery-estimate?product_id=22fbd12a-1b6e-41ea-a84f-4d9cf06c8766&postal_code=01310100"

Resposta

200Estimativa

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"
}

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

Status	Quando	Corpo
403	Módulo `delivery-window` desligado na loja.	`{"error":"module_disabled","module":"delivery-window"}`
500	Falha 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

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

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"
  ]
}'

Resposta

200Promessas por produto

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"
    }
  }
}

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

Status	Quando	Corpo
400	Corpo que não é JSON.	`{"error":"invalid request body","detail":"..."}`
403	Módulo `delivery-window` desligado na loja.	`{"error":"module_disabled","module":"delivery-window"}`
500	Falha ao calcular as promessas.	`{"error":"failed to calculate delivery promises","detail":"..."}`