API atual/Referência completa/Frete e entrega

Janelas de entrega

Lista janelas de entrega com vaga, reserva uma para um pedido e lê a reserva.

Alguns métodos de entrega (motoboy, entrega própria) trabalham com janelas: "segunda, das 09h às 12h". Cada janela tem um dia da semana, um horário e uma capacidade (quantos pedidos cabem naquele dia). O cliente escolhe uma janela e a loja reserva a vaga.

Fluxo: listar as janelas livres da data, reservar uma e, depois, ler a reserva quando for preciso mostrá-la.

Janelas livres

GET/api/v1/storefront/delivery/slotsCliente

Janelas de entrega com vaga numa data

Lista as janelas de entrega de um método numa data, só as que ainda têm vaga. Exige cliente logado (escopo customer:read).

Parâmetros de consulta

shipping_method_iduuidobrigatório

Método de envio.

datestringobrigatório

Data desejada, YYYY-MM-DD. O dia da semana da data escolhe as janelas.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/delivery/slots?shipping_method_id=85e87a54-dcee-4947-8cfa-f6406f2f3cbb&date=2026-10-12" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Janelas com vaga

json

{
  "slots": [
    {
      "id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
      "shipping_method_id": "85e87a54-dcee-4947-8cfa-f6406f2f3cbb",
      "day_of_week": 1,
      "start_time": "09:00",
      "end_time": "12:00",
      "max_orders": 10,
      "status": "A",
      "created_at": "2026-08-04T00:51:15Z",
      "updated_at": "2026-08-04T00:51:15Z",
      "booked_count": 3
    }
  ],
  "total": 1
}

Campos da resposta

slotsobject[]

Janelas ativas daquele dia da semana com pelo menos uma vaga. [] quando não há.

slots[].iduuid

Id da janela. Use em book.

slots[].shipping_method_iduuid

Método da janela.

slots[].day_of_weekinteger

0123456

Dia da semana: 0 domingo, 1 segunda, ..., 6 sábado.

slots[].start_timestring

Início, HH:MM.

slots[].end_timestring

Fim, HH:MM.

slots[].max_ordersinteger

Capacidade: pedidos por dia nesta janela.

slots[].statusstring

Situação da janela (A ativa). Aqui sempre ativa.

slots[].booked_countinteger

Reservas já feitas naquela data. Ausente quando é 0.

totalinteger

Quantidade de janelas.

Erros

Status	Quando	Corpo
401	Cliente não identificado: a rota exige token de cliente.	`{"error":"missing authorization header"}`
400	Falta `shipping_method_id` ou `date`.	`{"error":"shipping_method_id and date are required"}`
400	`date` fora do formato `YYYY-MM-DD`, ou `shipping_method_id` que não é UUID. O corpo traz a mensagem do servidor.	`{"error":"invalid date format (use YYYY-MM-DD): ..."}`

Reservar

POST/api/v1/storefront/delivery/bookCliente

Reserva uma janela de entrega

Reserva uma janela para um pedido. Exige cliente logado (escopo customer:write). Cada pedido tem no máximo uma reserva ativa.

Corpo da requisição

order_iduuidobrigatório

Pedido a agendar.

slot_iduuidobrigatório

Janela escolhida (id de Janelas livres).

delivery_datestringobrigatório

YYYY-MM-DD. O dia da semana tem de ser o da janela.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/delivery/book" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "order_id": "3f6c2d8e-91b4-4a7c-b5e0-7d1a2c3b4e5f",
  "slot_id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
  "delivery_date": "2026-10-12"
}'

Resposta

201Reserva criada

json

{
  "id": "1f2e3d4c-5b6a-4978-8695-a4b3c2d1e0f9",
  "order_id": "3f6c2d8e-91b4-4a7c-b5e0-7d1a2c3b4e5f",
  "slot_id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
  "delivery_date": "2026-10-12",
  "time_window": "09:00 - 12:00",
  "status": "scheduled",
  "created_at": "2026-10-11T14:05:00Z",
  "updated_at": "2026-10-11T14:05:00Z"
}

Campos da resposta

iduuid

Id da reserva.

order_iduuid

Pedido.

slot_iduuid

Janela.

delivery_datestring

YYYY-MM-DD.

time_windowstring

Horário no formato HH:MM - HH:MM.

statusstring

scheduleddeliveredcancelled

scheduled, delivered ou cancelled.

created_atstring

RFC 3339.

updated_atstring

RFC 3339.

Erros

Status	Quando	Corpo
401	Cliente não identificado: a rota exige token de cliente.	`{"error":"missing authorization header"}`
400	Corpo que não é JSON.	`{"error":"invalid request body","detail":"..."}`
400	Falta `order_id`, `slot_id` ou `delivery_date`.	`{"error":"order_id, slot_id, and delivery_date are required"}`
400	Janela inexistente.	`{"error":"delivery slot not found"}`
400	Janela inativa.	`{"error":"delivery slot is not active"}`
400	`delivery_date` fora do formato `YYYY-MM-DD`.	`{"error":"invalid delivery_date format: ..."}`
400	A data não cai no dia da semana da janela.	`{"error":"delivery date does not match slot's day of week"}`
400	Janela lotada na data.	`{"error":"delivery slot is fully booked for this date"}`
400	O pedido já tem uma entrega agendada.	`{"error":"order already has a scheduled delivery"}`

Ler a reserva

GET/api/v1/storefront/delivery/schedule/{orderID}Cliente

Janela reservada de um pedido

Devolve a reserva mais recente de um pedido. Exige cliente logado (escopo customer:read).

Parâmetros de caminho

orderIDuuidobrigatório

Id do pedido.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/delivery/schedule/3f6c2d8e-91b4-4a7c-b5e0-7d1a2c3b4e5f" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Reserva do pedido

json

{
  "id": "1f2e3d4c-5b6a-4978-8695-a4b3c2d1e0f9",
  "order_id": "3f6c2d8e-91b4-4a7c-b5e0-7d1a2c3b4e5f",
  "slot_id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
  "delivery_date": "2026-10-12",
  "time_window": "09:00 - 12:00",
  "status": "scheduled",
  "created_at": "2026-10-11T14:05:00Z",
  "updated_at": "2026-10-11T14:05:00Z",
  "shipping_method_name": "Motoboy"
}

Campos da resposta

shipping_method_namestring

Nome do método da janela, além dos campos da reserva acima.

Erros

Status	Quando	Corpo
401	Cliente não identificado: a rota exige token de cliente.	`{"error":"missing authorization header"}`
400	`orderID` que não é UUID.	`{"error":"invalid orderID","detail":"orderID must be a valid UUID"}`
404	O pedido não tem reserva.	`{"error":"no delivery schedule found"}`

Veja também

API atual/Referência completa/Frete e entrega

Janelas de entrega

Lista janelas de entrega com vaga, reserva uma para um pedido e lê a reserva.

Fluxo: listar as janelas livres da data, reservar uma e, depois, ler a reserva quando for preciso mostrá-la.

Janelas livres

GET/api/v1/storefront/delivery/slotsCliente

Janelas de entrega com vaga numa data

Lista as janelas de entrega de um método numa data, só as que ainda têm vaga. Exige cliente logado (escopo customer:read).

Parâmetros de consulta

shipping_method_iduuidobrigatório

Método de envio.

datestringobrigatório

Data desejada, YYYY-MM-DD. O dia da semana da data escolhe as janelas.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/delivery/slots?shipping_method_id=85e87a54-dcee-4947-8cfa-f6406f2f3cbb&date=2026-10-12" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Janelas com vaga

json

{
  "slots": [
    {
      "id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
      "shipping_method_id": "85e87a54-dcee-4947-8cfa-f6406f2f3cbb",
      "day_of_week": 1,
      "start_time": "09:00",
      "end_time": "12:00",
      "max_orders": 10,
      "status": "A",
      "created_at": "2026-08-04T00:51:15Z",
      "updated_at": "2026-08-04T00:51:15Z",
      "booked_count": 3
    }
  ],
  "total": 1
}

Campos da resposta

slotsobject[]

Janelas ativas daquele dia da semana com pelo menos uma vaga. [] quando não há.

slots[].iduuid

Id da janela. Use em book.

slots[].shipping_method_iduuid

Método da janela.

slots[].day_of_weekinteger

0123456

Dia da semana: 0 domingo, 1 segunda, ..., 6 sábado.

slots[].start_timestring

Início, HH:MM.

slots[].end_timestring

Fim, HH:MM.

slots[].max_ordersinteger

Capacidade: pedidos por dia nesta janela.

slots[].statusstring

Situação da janela (A ativa). Aqui sempre ativa.

slots[].booked_countinteger

Reservas já feitas naquela data. Ausente quando é 0.

totalinteger

Quantidade de janelas.

Erros

Status	Quando	Corpo
401	Cliente não identificado: a rota exige token de cliente.	`{"error":"missing authorization header"}`
400	Falta `shipping_method_id` ou `date`.	`{"error":"shipping_method_id and date are required"}`
400	`date` fora do formato `YYYY-MM-DD`, ou `shipping_method_id` que não é UUID. O corpo traz a mensagem do servidor.	`{"error":"invalid date format (use YYYY-MM-DD): ..."}`

Reservar

POST/api/v1/storefront/delivery/bookCliente

Reserva uma janela de entrega

Reserva uma janela para um pedido. Exige cliente logado (escopo customer:write). Cada pedido tem no máximo uma reserva ativa.

Corpo da requisição

order_iduuidobrigatório

Pedido a agendar.

slot_iduuidobrigatório

Janela escolhida (id de Janelas livres).

delivery_datestringobrigatório

YYYY-MM-DD. O dia da semana tem de ser o da janela.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/delivery/book" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "order_id": "3f6c2d8e-91b4-4a7c-b5e0-7d1a2c3b4e5f",
  "slot_id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
  "delivery_date": "2026-10-12"
}'

Resposta

201Reserva criada

json

{
  "id": "1f2e3d4c-5b6a-4978-8695-a4b3c2d1e0f9",
  "order_id": "3f6c2d8e-91b4-4a7c-b5e0-7d1a2c3b4e5f",
  "slot_id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
  "delivery_date": "2026-10-12",
  "time_window": "09:00 - 12:00",
  "status": "scheduled",
  "created_at": "2026-10-11T14:05:00Z",
  "updated_at": "2026-10-11T14:05:00Z"
}

Campos da resposta

iduuid

Id da reserva.

order_iduuid

Pedido.

slot_iduuid

Janela.

delivery_datestring

YYYY-MM-DD.

time_windowstring

Horário no formato HH:MM - HH:MM.

statusstring

scheduleddeliveredcancelled

scheduled, delivered ou cancelled.

created_atstring

RFC 3339.

updated_atstring

RFC 3339.

Erros

Status	Quando	Corpo
401	Cliente não identificado: a rota exige token de cliente.	`{"error":"missing authorization header"}`
400	Corpo que não é JSON.	`{"error":"invalid request body","detail":"..."}`
400	Falta `order_id`, `slot_id` ou `delivery_date`.	`{"error":"order_id, slot_id, and delivery_date are required"}`
400	Janela inexistente.	`{"error":"delivery slot not found"}`
400	Janela inativa.	`{"error":"delivery slot is not active"}`
400	`delivery_date` fora do formato `YYYY-MM-DD`.	`{"error":"invalid delivery_date format: ..."}`
400	A data não cai no dia da semana da janela.	`{"error":"delivery date does not match slot's day of week"}`
400	Janela lotada na data.	`{"error":"delivery slot is fully booked for this date"}`
400	O pedido já tem uma entrega agendada.	`{"error":"order already has a scheduled delivery"}`

Ler a reserva

GET/api/v1/storefront/delivery/schedule/{orderID}Cliente

Janela reservada de um pedido

Devolve a reserva mais recente de um pedido. Exige cliente logado (escopo customer:read).

Parâmetros de caminho

orderIDuuidobrigatório

Id do pedido.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/delivery/schedule/3f6c2d8e-91b4-4a7c-b5e0-7d1a2c3b4e5f" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Reserva do pedido

json

{
  "id": "1f2e3d4c-5b6a-4978-8695-a4b3c2d1e0f9",
  "order_id": "3f6c2d8e-91b4-4a7c-b5e0-7d1a2c3b4e5f",
  "slot_id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
  "delivery_date": "2026-10-12",
  "time_window": "09:00 - 12:00",
  "status": "scheduled",
  "created_at": "2026-10-11T14:05:00Z",
  "updated_at": "2026-10-11T14:05:00Z",
  "shipping_method_name": "Motoboy"
}

Campos da resposta

shipping_method_namestring

Nome do método da janela, além dos campos da reserva acima.

Erros

Status	Quando	Corpo
401	Cliente não identificado: a rota exige token de cliente.	`{"error":"missing authorization header"}`
400	`orderID` que não é UUID.	`{"error":"invalid orderID","detail":"orderID must be a valid UUID"}`
404	O pedido não tem reserva.	`{"error":"no delivery schedule found"}`