API atual/Referência completa/Entrega agendada

Janelas de entrega

Cria, lista, lê, altera e apaga as janelas semanais de horário de um método de envio, com capacidade por data.

Uma janela diz: neste método de envio, às segundas, entre 08:00 e 12:00, aceitamos até 10 pedidos por data. Cadastre uma janela por dia e faixa de horário. O cliente só vê as que estão ativas e ainda têm vaga na data escolhida.

Listar janelas

GET/api/v1/admin/delivery/slotsAdmin

Lista as janelas de entrega

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

Parâmetros de consulta

shipping_method_iduuid

Só as janelas deste método.

statusstring

ADactivedisabled

A/active ou D/disabled. Outro valor é ignorado.

searchstring

Texto no nome do método de envio (sem diferenciar maiúsculas).

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/delivery/slots?shipping_method_id=50000000-0000-0000-0000-000000000001&status=A" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Janelas retornadas

json

{
  "slots": [
    {
      "id": "17b60b02-d01b-419d-8faa-d09ff8a00940",
      "shipping_method_id": "50000000-0000-0000-0000-000000000001",
      "day_of_week": 1,
      "start_time": "08:00",
      "end_time": "12:00",
      "max_orders": 10,
      "status": "A",
      "created_at": "2026-07-12T17:24:22.086908Z",
      "updated_at": "2026-07-12T17:24:22.086908Z"
    }
  ],
  "total": 1
}

Campos da resposta

slotsarray

Janelas, sem paginação.

totalinteger

Quantidade devolvida.

slots[].iduuid

Id da janela.

slots[].shipping_method_iduuid

Método de envio a que a janela pertence.

slots[].day_of_weekinteger

0123456

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

slots[].start_timestring

Início da janela, HH:MM.

slots[].end_timestring

Fim da janela, HH:MM.

slots[].max_ordersinteger

Máximo de pedidos agendados por data nesta janela.

slots[].statusstring

AD

A ativa ou D desativada.

slots[].created_atstring

Criação, RFC 3339 em UTC.

slots[].updated_atstring

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

Consultar uma janela

GET/api/v1/admin/delivery/slots/{id}Admin

Lê uma janela de entrega

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

Parâmetros de caminho

iduuidobrigatório

Id da janela.

Exemplo de requisição

bash

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

Resposta

200Janela encontrada

json

{
  "id": "17b60b02-d01b-419d-8faa-d09ff8a00940",
  "shipping_method_id": "50000000-0000-0000-0000-000000000001",
  "day_of_week": 1,
  "start_time": "08:00",
  "end_time": "12:00",
  "max_orders": 10,
  "status": "A",
  "created_at": "2026-07-12T17:24:22.086908Z",
  "updated_at": "2026-07-12T17:24:22.086908Z"
}

Criar uma janela

POST/api/v1/admin/delivery/slotsAdmin

Cria uma janela de entrega

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

Corpo da requisição

shipping_method_iduuidobrigatório

Método de envio da janela.

day_of_weekintegerobrigatório

0123456

0 domingo a 6 sábado.

start_timestringobrigatório

Início, HH:MM.

end_timestringobrigatório

Fim, HH:MM.

max_ordersintegerpadrão: 50

Pedidos por data. Menor que 1 vira 50.

statusstringpadrão: A

A/active ou D/disabled. Um valor não reconhecido vira ativo.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/delivery/slots" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "shipping_method_id": "50000000-0000-0000-0000-000000000001",
    "day_of_week": 3,
    "start_time": "14:00",
    "end_time": "18:00",
    "max_orders": 4
  }'

Resposta

201Janela criada

json

{
  "id": "6bd3bc21-fc3b-4f6f-ac7c-10df0c5fd512",
  "shipping_method_id": "50000000-0000-0000-0000-000000000001",
  "day_of_week": 3,
  "start_time": "14:00",
  "end_time": "18:00",
  "max_orders": 4,
  "status": "A",
  "created_at": "2026-07-12T17:24:22.086908Z",
  "updated_at": "2026-07-12T17:24:22.086908Z"
}

Alterar uma janela

Alteração parcial. Não há campo para trocar o método: para isso, crie outra janela. Um corpo sem nenhum campo conhecido é recusado.

PUT/api/v1/admin/delivery/slots/{id}Admin

Altera uma janela de entrega

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

Parâmetros de caminho

iduuidobrigatório

Id da janela.

Corpo da requisição

day_of_weekinteger

0123456

0 a 6.

start_timestring

HH:MM.

end_timestring

HH:MM.

max_ordersinteger

Pedidos por data. Aqui 0 é gravado como está e a janela passa a não ter vaga.

statusstring

ADactivedisabled

A/active ou D/disabled.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/delivery/slots/$SLOT_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "max_orders": 8,
    "status": "active"
  }'

Resposta

200Janela alterada

json

{
  "id": "17b60b02-d01b-419d-8faa-d09ff8a00940",
  "shipping_method_id": "50000000-0000-0000-0000-000000000001",
  "day_of_week": 1,
  "start_time": "08:00",
  "end_time": "12:00",
  "max_orders": 8,
  "status": "A",
  "created_at": "2026-07-12T17:24:22.086908Z",
  "updated_at": "2026-07-12T17:24:22.086908Z"
}

Apagar uma janela

Exclusão definitiva. É recusada enquanto houver entregas futuras agendadas na janela; cancele-as antes em Agendamentos. Para parar de oferecer a janela sem perder o histórico, desative-a.

DELETE/api/v1/admin/delivery/slots/{id}Admin

Apaga uma janela de entrega

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

Parâmetros de caminho

iduuidobrigatório

Id da janela.

Exemplo de requisição

bash

curl -X DELETE "$BASE_URL/api/v1/admin/delivery/slots/$SLOT_ID" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Janela apagada

json

{
  "message": "delivery slot deleted"
}

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	Corpo que não é JSON	`{"error":"invalid request body","detail":"..."}`
404	Só na leitura de uma janela: o id não existe	`{"error":"delivery slot not found"}`
500	`shipping_method_id` vazio ou inexistente; `day_of_week` fora de 0 a 6; horários vazios; `status` desconhecido (só na alteração); janela inexistente (alterar e apagar); apagar com entregas futuras	`{"error":"failed to create delivery slot","detail":"day_of_week must be 0-6 (Sunday-Saturday)"}` / `{"error":"failed to delete delivery slot","detail":"cannot delete slot with 3 future scheduled deliveries"}`

Veja também

API atual/Referência completa/Entrega agendada

Janelas de entrega

Cria, lista, lê, altera e apaga as janelas semanais de horário de um método de envio, com capacidade por data.

Listar janelas

GET/api/v1/admin/delivery/slotsAdmin

Lista as janelas de entrega

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

Parâmetros de consulta

shipping_method_iduuid

Só as janelas deste método.

statusstring

ADactivedisabled

A/active ou D/disabled. Outro valor é ignorado.

searchstring

Texto no nome do método de envio (sem diferenciar maiúsculas).

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/delivery/slots?shipping_method_id=50000000-0000-0000-0000-000000000001&status=A" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Janelas retornadas

json

{
  "slots": [
    {
      "id": "17b60b02-d01b-419d-8faa-d09ff8a00940",
      "shipping_method_id": "50000000-0000-0000-0000-000000000001",
      "day_of_week": 1,
      "start_time": "08:00",
      "end_time": "12:00",
      "max_orders": 10,
      "status": "A",
      "created_at": "2026-07-12T17:24:22.086908Z",
      "updated_at": "2026-07-12T17:24:22.086908Z"
    }
  ],
  "total": 1
}

Campos da resposta

slotsarray

Janelas, sem paginação.

totalinteger

Quantidade devolvida.

slots[].iduuid

Id da janela.

slots[].shipping_method_iduuid

Método de envio a que a janela pertence.

slots[].day_of_weekinteger

0123456

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

slots[].start_timestring

Início da janela, HH:MM.

slots[].end_timestring

Fim da janela, HH:MM.

slots[].max_ordersinteger

Máximo de pedidos agendados por data nesta janela.

slots[].statusstring

AD

A ativa ou D desativada.

slots[].created_atstring

Criação, RFC 3339 em UTC.

slots[].updated_atstring

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

Consultar uma janela

GET/api/v1/admin/delivery/slots/{id}Admin

Lê uma janela de entrega

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

Parâmetros de caminho

iduuidobrigatório

Id da janela.

Exemplo de requisição

bash

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

Resposta

200Janela encontrada

json

{
  "id": "17b60b02-d01b-419d-8faa-d09ff8a00940",
  "shipping_method_id": "50000000-0000-0000-0000-000000000001",
  "day_of_week": 1,
  "start_time": "08:00",
  "end_time": "12:00",
  "max_orders": 10,
  "status": "A",
  "created_at": "2026-07-12T17:24:22.086908Z",
  "updated_at": "2026-07-12T17:24:22.086908Z"
}

Criar uma janela

POST/api/v1/admin/delivery/slotsAdmin

Cria uma janela de entrega

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

Corpo da requisição

shipping_method_iduuidobrigatório

Método de envio da janela.

day_of_weekintegerobrigatório

0123456

0 domingo a 6 sábado.

start_timestringobrigatório

Início, HH:MM.

end_timestringobrigatório

Fim, HH:MM.

max_ordersintegerpadrão: 50

Pedidos por data. Menor que 1 vira 50.

statusstringpadrão: A

A/active ou D/disabled. Um valor não reconhecido vira ativo.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/delivery/slots" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "shipping_method_id": "50000000-0000-0000-0000-000000000001",
    "day_of_week": 3,
    "start_time": "14:00",
    "end_time": "18:00",
    "max_orders": 4
  }'

Resposta

201Janela criada

json

{
  "id": "6bd3bc21-fc3b-4f6f-ac7c-10df0c5fd512",
  "shipping_method_id": "50000000-0000-0000-0000-000000000001",
  "day_of_week": 3,
  "start_time": "14:00",
  "end_time": "18:00",
  "max_orders": 4,
  "status": "A",
  "created_at": "2026-07-12T17:24:22.086908Z",
  "updated_at": "2026-07-12T17:24:22.086908Z"
}

Alterar uma janela

Alteração parcial. Não há campo para trocar o método: para isso, crie outra janela. Um corpo sem nenhum campo conhecido é recusado.

PUT/api/v1/admin/delivery/slots/{id}Admin

Altera uma janela de entrega

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

Parâmetros de caminho

iduuidobrigatório

Id da janela.

Corpo da requisição

day_of_weekinteger

0123456

0 a 6.

start_timestring

HH:MM.

end_timestring

HH:MM.

max_ordersinteger

Pedidos por data. Aqui 0 é gravado como está e a janela passa a não ter vaga.

statusstring

ADactivedisabled

A/active ou D/disabled.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/delivery/slots/$SLOT_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "max_orders": 8,
    "status": "active"
  }'

Resposta

200Janela alterada

json

{
  "id": "17b60b02-d01b-419d-8faa-d09ff8a00940",
  "shipping_method_id": "50000000-0000-0000-0000-000000000001",
  "day_of_week": 1,
  "start_time": "08:00",
  "end_time": "12:00",
  "max_orders": 8,
  "status": "A",
  "created_at": "2026-07-12T17:24:22.086908Z",
  "updated_at": "2026-07-12T17:24:22.086908Z"
}

Apagar uma janela

Exclusão definitiva. É recusada enquanto houver entregas futuras agendadas na janela; cancele-as antes em Agendamentos. Para parar de oferecer a janela sem perder o histórico, desative-a.

DELETE/api/v1/admin/delivery/slots/{id}Admin

Apaga uma janela de entrega

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

Parâmetros de caminho

iduuidobrigatório

Id da janela.

Exemplo de requisição

bash

curl -X DELETE "$BASE_URL/api/v1/admin/delivery/slots/$SLOT_ID" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Janela apagada

json

{
  "message": "delivery slot deleted"
}

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	Corpo que não é JSON	`{"error":"invalid request body","detail":"..."}`
404	Só na leitura de uma janela: o id não existe	`{"error":"delivery slot not found"}`
500	`shipping_method_id` vazio ou inexistente; `day_of_week` fora de 0 a 6; horários vazios; `status` desconhecido (só na alteração); janela inexistente (alterar e apagar); apagar com entregas futuras	`{"error":"failed to create delivery slot","detail":"day_of_week must be 0-6 (Sunday-Saturday)"}` / `{"error":"failed to delete delivery slot","detail":"cannot delete slot with 3 future scheduled deliveries"}`