Entregas e rotas

🛂 Permissões: order.start_delivery, order.complete_delivery, order.assign_driver 🔒 Plano: rotas/mês limitadas por max_monthly_routes. 📍 Caminho: Operações → Entregas

A tela de entregas é o cockpit do dia da operação: pedidos a entregar, motoristas, rotas e finalização.

O que é uma rota

Uma rota (SavedRoute) agrupa vários pedidos para serem entregues por um mesmo motorista, em sequência otimizada. As rotas têm status:

Status	Significado
active	Em andamento.
completed	Todas as entregas finalizadas.
cancelled	Rota abortada.

Painel de entregas

Em Operações → Entregas você vê:

• Pedidos com status Pending ou In_Transit.
• Filtros por motorista atribuído, data, região.
• Mapa com pinos de cada endereço.

Atribuindo motorista

1. Selecione um ou mais pedidos.
2. Clique em Atribuir motorista.
3. Escolha um usuário com role DRIVER ou ADMIN.
4. (Opcional) Salve como rota.

Motoristas com app mobile recebem a rota direto no celular.

Iniciando a entrega

• O motorista (no painel ou app) clica em Iniciar entrega — pedido vira In_Transit.
• O cliente é notificado por WhatsApp (se a integração estiver ativa) e/ou push.

Concluindo a entrega

Ao chegar:

• Concluir entrega marca o pedido como Delivered.
• O motorista pode anexar foto do comprovante e observação.
• Se a entrega falhar, registre a falha com motivo (cliente ausente, recusa, etc.) — o webhook delivery.failed é disparado para integrações.

Otimização de rota

Rotas salvas podem ser otimizadas (sequência ideal de paradas, partindo do endereço da loja). O sistema usa as coordenadas do endereço de cada pedido — clientes sem geolocalização podem ser geocodificados em massa pela equipe.

Visualização no mapa

A aba de mapa mostra:

• 📍 Pino da loja.
• 🟢 Pedidos Pending.
• 🔵 Pedidos In_Transit.
• ✅ Pedidos Delivered do dia.

Webhooks de entrega

Eventos disparados (ver Webhooks):

• delivery.completed
• delivery.failed

Limite do plano

A criação de novas rotas é bloqueada ao atingir max_monthly_routes no mês.

Boas práticas

• Geocodifique clientes ao cadastrar — sem coordenadas, o pedido não aparece no mapa nem em rotas otimizadas.
• Use rotas mesmo para um único motorista — facilita relatório no fim do dia.
• Notifique o cliente sempre que iniciar a entrega — reduz reclamação.
• Em caso de falha, registre motivo padronizado (categórico) para extrair métrica de falha por região/cliente.