VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
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

Resposta

200Janelas retornadas

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

Resposta

200Janela encontrada

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

Resposta

201Janela criada

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

Resposta

200Janela alterada

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

Resposta

200Janela apagada

Erros

StatusQuandoCorpo
401Sem token, token inválido ou expirado{"error":"invalid or expired token"}
403Sem o privilégio manage_shipping{"error":"insufficient privileges","privilege_required_any":["manage_shipping"]}
403Módulo delivery-scheduling desligado{"error":"module_disabled","module":"delivery-scheduling"}
400Corpo que não é JSON{"error":"invalid request body","detail":"..."}
404Só na leitura de uma janela: o id não existe{"error":"delivery slot not found"}
500shipping_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"}
Horários são só texto

A plataforma não confere se end_time é depois de start_time, nem se há janelas sobrepostas para o mesmo método e dia. Valide no seu lado. Um valor que não seja hora (25:99) é recusado pelo banco com 500.

Capacidade por data

max_orders limita os pedidos de cada data, não de todas juntas. Uma janela de segunda com max_orders: 10 aceita 10 pedidos em cada segunda-feira.

Veja também

  • Agendamentos
  • Métodos de envio
Anterior
Entrega agendada
Próxima
Agendamentos de entrega
Nesta página
  • Listar janelas
  • Exemplo de requisição
  • Resposta
  • Consultar uma janela
  • Exemplo de requisição
  • Resposta
  • Criar uma janela
  • Exemplo de requisição
  • Resposta
  • Alterar uma janela
  • Exemplo de requisição
  • Resposta
  • Apagar uma janela
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também
bash
curl "$BASE_URL/api/v1/admin/delivery/slots?shipping_method_id=50000000-0000-0000-0000-000000000001&status=A" \
  -H "Authorization: Bearer $TOKEN"
bash
curl "$BASE_URL/api/v1/admin/delivery/slots/$SLOT_ID" \
  -H "Authorization: Bearer $TOKEN"
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
  }'
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"
  }'
bash
curl -X DELETE "$BASE_URL/api/v1/admin/delivery/slots/$SLOT_ID" \
  -H "Authorization: Bearer $TOKEN"
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
}
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"
}
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"
}
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"
}
json
{
  "message": "delivery slot deleted"
}