Entrega agendada

Em mercado, farmácia, flores e entrega local, o cliente quer escolher quando recebe: "terça-feira entre 14h e 18h". A entrega agendada permite isso. A loja cadastra janelas (slots): para um método de envio, num dia da semana, um horário de início e fim e uma capacidade máxima de pedidos por data. No checkout, o cliente escolhe uma data e uma janela com vaga, e a plataforma grava um agendamento ligando o pedido à janela.

Esta seção documenta o lado do administrador: criar e manter janelas, consultar o agendamento de um pedido, listar as entregas marcadas e cancelar um agendamento. A escolha da janela pelo cliente acontece nas rotas da loja virtual e não faz parte desta seção.

Como funciona

Um pedido só pode ter um agendamento em scheduled por vez.

Conceitos-chave

Janela, data e capacidade

A janela "segunda, 08:00 às 12:00, 10 pedidos" vale para todas as segundas-feiras. Cada segunda tem 10 vagas próprias: a conta é feita por data. Quando as vagas de uma data acabam, a janela deixa de ser oferecida naquela data.

Estados como letra ou palavra

Na janela, status sai sempre como letra (A, D), mas na escrita você pode enviar a letra ou a palavra (active, disabled). No agendamento, status sai por extenso (scheduled).

Cancelar não cancela o pedido

Cancelar um agendamento só libera a vaga e marca o agendamento. O pedido, o pagamento e o envio não mudam; avise o cliente e combine uma nova data.

Endpoints

Erros comuns

1. Esquecer que a leitura também exige manage_shipping. Um usuário só com view_shipping recebe 403.
2. Criar com day_of_week fora de 0 a 6. Volta 500 com a mensagem no detail.
3. Mandar max_orders: 0 na criação. O valor vira 50. Na alteração, 0 é gravado e a janela deixa de ter vaga.
4. Apagar uma janela em uso. É recusado (500) enquanto houver entregas futuras agendadas; cancele-as antes.
5. Filtrar entregas por um status que não existe. A listagem devolve vazio, sem erro.
6. Achar que o cancelamento avisa o cliente. Não avisa.

Próximos passos