API atual/Referência completa/Entrega agendada

Agendamentos de entrega

Lista as entregas marcadas, lê o agendamento de um pedido e cancela um agendamento para liberar a vaga.

Um agendamento liga um pedido a uma janela em uma data. Quem cria é o cliente, no checkout; o administrador consulta e, se preciso, cancela. Estas rotas servem à equipe de expedição: ver o que sai amanhã, achar a data combinada de um pedido e liberar uma vaga.

Listar entregas agendadas

GET/api/v1/admin/delivery/scheduledAdmin

Lista as entregas agendadas

Exige o privilégio manage_shipping (também para ler) e o módulo delivery-scheduling ligado.

Parâmetros de consulta

datestring

Um único dia, YYYY-MM-DD. Atalho para date_from e date_to iguais.

date_fromstring

Primeiro dia, YYYY-MM-DD.

date_tostring

Último dia, YYYY-MM-DD.

statusstring

scheduleddeliveredcancelled

scheduled, delivered ou cancelled (ou S, V, I). Valor desconhecido devolve lista vazia.

pageintegerpadrão: 1

Página, a partir de 1.

per_pageintegerpadrão: 20

Itens por página, de 1 a 200. Qualquer outro valor vira 20.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/delivery/scheduled?date=2026-07-20&status=scheduled" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Entregas retornadas

json

{
  "deliveries": [
    {
      "id": "a6fe3946-2350-42a6-87c3-598df29a3a6d",
      "order_id": "a4ff49de-f235-48f9-8959-d7aa4ef9feb4",
      "slot_id": "17b60b02-d01b-419d-8faa-d09ff8a00940",
      "delivery_date": "2026-07-20T00:00:00Z",
      "time_window": "08:00 - 12:00",
      "status": "scheduled",
      "created_at": "2026-07-12T18:18:33.533426Z",
      "updated_at": "2026-07-12T18:18:33.533426Z",
      "shipping_method_name": "Entrega Padrão",
      "start_time": "08:00",
      "end_time": "12:00",
      "customer_name": "Maria Souza",
      "customer_email": "maria.souza@example.com"
    }
  ],
  "page": 1,
  "per_page": 20,
  "total": 1,
  "total_pages": 1
}

Campos da resposta

deliveriesarray

Entregas da página.

deliveries[].iduuid

Id do agendamento.

deliveries[].order_iduuid

Pedido agendado.

deliveries[].slot_iduuid

Janela reservada.

deliveries[].delivery_datestring

Data da entrega (meia-noite UTC do dia combinado).

deliveries[].time_windowstring

Faixa de horário, HH:MM - HH:MM, copiada da janela no momento da reserva.

deliveries[].statusstring

scheduleddeliveredcancelled

scheduled, delivered ou cancelled.

deliveries[].shipping_method_namestring

Nome do método de envio da janela.

deliveries[].start_timestring

Início da janela (só na listagem geral).

deliveries[].end_timestring

Fim da janela (só na listagem geral).

deliveries[].customer_namestring

Nome do cliente do pedido (só na listagem geral).

deliveries[].customer_emailstring

E-mail do cliente (só na listagem geral).

deliveries[].created_atstring

Criação, RFC 3339 em UTC.

deliveries[].updated_atstring

Última alteração, RFC 3339 em UTC.

pageinteger

Página devolvida.

per_pageinteger

Itens por página.

totalinteger

Total que atende ao filtro.

total_pagesinteger

Quantidade de páginas (no mínimo 1).

Agendamento de um pedido

GET/api/v1/admin/delivery/schedule/{orderID}Admin

Lê o agendamento de um pedido

Exige o privilégio manage_shipping (também para ler) e o módulo delivery-scheduling ligado.

Parâmetros de caminho

orderIDuuidobrigatório

Id do pedido.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/delivery/schedule/$ORDER_ID" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Agendamento encontrado

json

{
  "id": "a6fe3946-2350-42a6-87c3-598df29a3a6d",
  "order_id": "a4ff49de-f235-48f9-8959-d7aa4ef9feb4",
  "slot_id": "17b60b02-d01b-419d-8faa-d09ff8a00940",
  "delivery_date": "2026-07-20T00:00:00Z",
  "time_window": "08:00 - 12:00",
  "status": "scheduled",
  "created_at": "2026-07-12T18:18:33.533426Z",
  "updated_at": "2026-07-12T18:18:33.533426Z",
  "shipping_method_name": "Entrega Padrão"
}

Cancelar um agendamento

Muda o agendamento de scheduled para cancelled, o que libera a vaga daquela janela naquela data. Só agendamentos em scheduled podem ser cancelados. O cliente não é avisado e o pedido não muda.

POST/api/v1/admin/delivery/schedule/{id}/cancelAdmin

Cancela um agendamento de entrega

Exige o privilégio manage_shipping (também para ler) e o módulo delivery-scheduling ligado. Sem corpo.

Parâmetros de caminho

iduuidobrigatório

Id do agendamento (campo id da listagem), não do pedido.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/delivery/schedule/$SCHEDULE_ID/cancel" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Agendamento cancelado

json

{
  "message": "delivery schedule cancelled"
}

Erros

Status	Quando	Corpo
401	Sem token, token inválido ou expirado	`{"error":"invalid or expired token"}`
403	Sem o privilégio `manage_shipping`	`{"error":"insufficient privileges","privilege_required_any":["manage_shipping"]}`
403	Módulo `delivery-scheduling` desligado	`{"error":"module_disabled","module":"delivery-scheduling"}`
400	`orderID` ou `id` que não é UUID	`{"error":"invalid orderID","detail":"orderID must be a valid UUID"}`
404	O pedido não tem agendamento	`{"error":"no delivery schedule found for this order"}`
500	Cancelar um agendamento que não existe ou que já não está `scheduled`	`{"error":"failed to cancel delivery schedule","detail":"delivery schedule not found or not in scheduled status"}`

Veja também

API atual/Referência completa/Entrega agendada

Agendamentos de entrega

Lista as entregas marcadas, lê o agendamento de um pedido e cancela um agendamento para liberar a vaga.

Listar entregas agendadas

GET/api/v1/admin/delivery/scheduledAdmin

Lista as entregas agendadas

Exige o privilégio manage_shipping (também para ler) e o módulo delivery-scheduling ligado.

Parâmetros de consulta

datestring

Um único dia, YYYY-MM-DD. Atalho para date_from e date_to iguais.

date_fromstring

Primeiro dia, YYYY-MM-DD.

date_tostring

Último dia, YYYY-MM-DD.

statusstring

scheduleddeliveredcancelled

scheduled, delivered ou cancelled (ou S, V, I). Valor desconhecido devolve lista vazia.

pageintegerpadrão: 1

Página, a partir de 1.

per_pageintegerpadrão: 20

Itens por página, de 1 a 200. Qualquer outro valor vira 20.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/delivery/scheduled?date=2026-07-20&status=scheduled" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Entregas retornadas

json

{
  "deliveries": [
    {
      "id": "a6fe3946-2350-42a6-87c3-598df29a3a6d",
      "order_id": "a4ff49de-f235-48f9-8959-d7aa4ef9feb4",
      "slot_id": "17b60b02-d01b-419d-8faa-d09ff8a00940",
      "delivery_date": "2026-07-20T00:00:00Z",
      "time_window": "08:00 - 12:00",
      "status": "scheduled",
      "created_at": "2026-07-12T18:18:33.533426Z",
      "updated_at": "2026-07-12T18:18:33.533426Z",
      "shipping_method_name": "Entrega Padrão",
      "start_time": "08:00",
      "end_time": "12:00",
      "customer_name": "Maria Souza",
      "customer_email": "maria.souza@example.com"
    }
  ],
  "page": 1,
  "per_page": 20,
  "total": 1,
  "total_pages": 1
}

Campos da resposta

deliveriesarray

Entregas da página.

deliveries[].iduuid

Id do agendamento.

deliveries[].order_iduuid

Pedido agendado.

deliveries[].slot_iduuid

Janela reservada.

deliveries[].delivery_datestring

Data da entrega (meia-noite UTC do dia combinado).

deliveries[].time_windowstring

Faixa de horário, HH:MM - HH:MM, copiada da janela no momento da reserva.

deliveries[].statusstring

scheduleddeliveredcancelled

scheduled, delivered ou cancelled.

deliveries[].shipping_method_namestring

Nome do método de envio da janela.

deliveries[].start_timestring

Início da janela (só na listagem geral).

deliveries[].end_timestring

Fim da janela (só na listagem geral).

deliveries[].customer_namestring

Nome do cliente do pedido (só na listagem geral).

deliveries[].customer_emailstring

E-mail do cliente (só na listagem geral).

deliveries[].created_atstring

Criação, RFC 3339 em UTC.

deliveries[].updated_atstring

Última alteração, RFC 3339 em UTC.

pageinteger

Página devolvida.

per_pageinteger

Itens por página.

totalinteger

Total que atende ao filtro.

total_pagesinteger

Quantidade de páginas (no mínimo 1).

Agendamento de um pedido

GET/api/v1/admin/delivery/schedule/{orderID}Admin

Lê o agendamento de um pedido

Exige o privilégio manage_shipping (também para ler) e o módulo delivery-scheduling ligado.

Parâmetros de caminho

orderIDuuidobrigatório

Id do pedido.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/delivery/schedule/$ORDER_ID" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Agendamento encontrado

json

{
  "id": "a6fe3946-2350-42a6-87c3-598df29a3a6d",
  "order_id": "a4ff49de-f235-48f9-8959-d7aa4ef9feb4",
  "slot_id": "17b60b02-d01b-419d-8faa-d09ff8a00940",
  "delivery_date": "2026-07-20T00:00:00Z",
  "time_window": "08:00 - 12:00",
  "status": "scheduled",
  "created_at": "2026-07-12T18:18:33.533426Z",
  "updated_at": "2026-07-12T18:18:33.533426Z",
  "shipping_method_name": "Entrega Padrão"
}

Cancelar um agendamento

POST/api/v1/admin/delivery/schedule/{id}/cancelAdmin

Cancela um agendamento de entrega

Exige o privilégio manage_shipping (também para ler) e o módulo delivery-scheduling ligado. Sem corpo.

Parâmetros de caminho

iduuidobrigatório

Id do agendamento (campo id da listagem), não do pedido.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/delivery/schedule/$SCHEDULE_ID/cancel" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Agendamento cancelado

json

{
  "message": "delivery schedule cancelled"
}

Erros

Status	Quando	Corpo
401	Sem token, token inválido ou expirado	`{"error":"invalid or expired token"}`
403	Sem o privilégio `manage_shipping`	`{"error":"insufficient privileges","privilege_required_any":["manage_shipping"]}`
403	Módulo `delivery-scheduling` desligado	`{"error":"module_disabled","module":"delivery-scheduling"}`
400	`orderID` ou `id` que não é UUID	`{"error":"invalid orderID","detail":"orderID must be a valid UUID"}`
404	O pedido não tem agendamento	`{"error":"no delivery schedule found for this order"}`
500	Cancelar um agendamento que não existe ou que já não está `scheduled`	`{"error":"failed to cancel delivery schedule","detail":"delivery schedule not found or not in scheduled status"}`