Roteirizações
Criado por Igor Ribeiro em 30 de setembro de 2026
Atualizado por Igor Ribeiro em 01 de outubro de 2026
Roteirizações — Painel
A tela Roteirizações é onde a transportadora monta e otimiza os roteiros de entrega do dia: seleciona os veículos e as entregas que vão sair para a rua, envia esse conjunto para o motor de otimização de rotas, revisa o resultado num mapa, ajusta manualmente se necessário e finaliza o roteiro — o que atribui definitivamente motorista, placa e um código de carga a cada entrega.
Visão Geral
A tela Roteirizações é onde a transportadora monta e otimiza os roteiros de entrega do dia: seleciona os veículos e as entregas que vão sair para a rua, envia esse conjunto para o motor de otimização de rotas, revisa o resultado num mapa, ajusta manualmente se necessário e finaliza o roteiro — o que atribui definitivamente motorista, placa e um código de carga a cada entrega. É a tela mais complexa do Painel: reúne um assistente de 4 etapas para criar um roteiro novo, uma tela de mapa para editar o resultado (trocar entregas entre veículos, reordenar a sequência de cada veículo, salvar, sincronizar com um sistema integrado e finalizar), um modo de comparação entre uma sequência montada manualmente e a sequência calculada pelo motor de otimização, e a sincronização opcional com o sistema integrado Atak (importação e remoção de cargas, gerenciamento de percursos e ajudantes usados nessa integração). A Roteirizações consome os cadastros de Veículos, Motoristas, Centros de Distribuição e Clientes, e as entregas disponíveis vêm da tela Entregas — uma entrega roteirizada aqui deixa de aparecer como disponível para outro roteiro até ser removida ou revertida.
Pré-requisitos
Para a tela Roteirizações funcionar, é necessário que:
- o usuário tenha uma sessão autenticada válida no Painel — sem sessão ativa, qualquer ação realizada nesta tela retorna erro de sessão expirada e o Painel desconecta o usuário automaticamente (ver Feedbacks ao Usuário).
- o perfil do usuário tenha a permissão de área “Roteirização” ativa — sem essa condição, o item de menu não é exibido e uma tentativa de acesso direto pela URL é bloqueada.
- a empresa tenha a integração com o sistema integrado habilitada nas Configurações (endereço de conexão com o sistema integrado configurado) para usar os botões SINCRONIZAR e COMPARAR ROTEIRO — sem isso, o Painel avisa que a configuração não foi feita e fecha o fluxo.
- para criar um roteiro novo, é necessário que o limite diário de veículos distintos roteirizados da empresa esteja configurado — se estiver ausente, o botão NOVO ROTEIRO avisa que o limite “parece não estar configurado” e não avança.
- para concluir a etapa de Informações Gerais, é necessário ter ao menos um Centro de Distribuição cadastrado, pois ele é obrigatório como ponto de partida do roteiro.
- para concluir a etapa de Veículos, é necessário ter ao menos um veículo cadastrado e disponível dentro do limite diário.
- para concluir a etapa de Entregas, é necessário ter ao menos uma entrega com status “aguardando” no período informado.
Fluxo Operacional
- O usuário acessa a tela Roteirizações pelo menu e vê a lista de roteiros já criados, com o limite diário de veículos ainda disponíveis para roteirização.
- Ao clicar em NOVO ROTEIRO, o usuário percorre um assistente de 4 etapas: (1) informações gerais do roteiro (nome, data, horários, Centro de Distribuição), (2) seleção dos veículos que participarão, (3) seleção das entregas que serão roteirizadas, e (4) um resumo com as opções de restrição de peso e de tempo antes de enviar.
- Ao confirmar o envio, o Painel chama o motor de otimização de rotas e exibe o resultado num mapa: quais veículos ficaram com rota, quais entregas ficaram sem vínculo (desvinculadas) e um resumo de distância, peso e tempo por veículo.
- No mapa, o usuário pode revisar e ajustar manualmente: reordenar a sequência de entregas de um veículo, mover entregas entre veículos ou para a lista de desvinculadas, e escolher se cada ajuste deve ser reotimizado pelo motor ou apenas reorganizado na sequência atual.
- O usuário pode SALVAR o roteiro para continuar depois, SINCRONIZAR as cargas com o sistema integrado (se a empresa usa essa integração) e, por fim, FINALIZAR — o que atribui definitivamente motorista, placa e carga a cada entrega roteirizada.
- Alternativamente, o usuário pode SINCRONIZAR ou COMPARAR ROTEIRO diretamente da lista: a sincronização importa cargas já montadas manualmente no sistema integrado direto para um novo roteiro (sem passar pelo motor de otimização); a comparação importa essa mesma sequência manual e, ao mesmo tempo, roteiriza automaticamente o mesmo conjunto de entregas, mostrando lado a lado qual das duas é mais eficiente.
- Um roteiro já finalizado pode ser consultado (VER), ter seu arquivo baixado (BAIXAR, em CSV ou TXT) e ter um relatório de carga gerado em PDF (RELATÓRIO); só pode ser editado enquanto não estiver finalizado.
Interface e Comportamentos
Lista de Roteiros
A lista mostra nome, data de embarque, se está finalizado, a carga (ou “Não finalizado” em cinza quando ainda não há carga), se está sincronizado com o sistema integrado (só para empresas integradas), total de rotas, entregas, distância e peso — e, expandindo cada linha, os veículos daquele roteiro com placa, marca, motorista, carga externa, entregas e peso. A distância é exibida em metros com uma casa decimal abaixo de 1000 m, e em quilômetros acima disso; o peso segue a mesma regra entre quilogramas e toneladas, sempre com vírgula como separador decimal.
Cada roteiro tem os botões VER (abre o mapa, sempre disponível), EDITAR (só aparece se o roteiro não estiver finalizado, e exige permissão de edição), BAIXAR (sempre disponível), SINCRONIZAR individual (só para empresas integradas e roteiros finalizados, exige permissão de edição), RELATÓRIO (só para roteiros finalizados) e REMOVER (exige permissão de edição).
Ao lado da busca por nome/carga/data, um indicador mostra quantos veículos distintos ainda podem ser roteirizados hoje, calculado como o limite diário da empresa menos o consumo já registrado, nunca exibindo um número negativo.
Retomada de Roteirização Inacabada
Se o usuário sair da tela de criação de roteiro no meio do processo (sem cancelar explicitamente) e escolher salvar o progresso, a próxima vez que abrir a tela Roteirizações o Painel oferece retomar de onde parou. Essa retomada é armazenada apenas no navegador utilizado — ver “Comportamento Offline e Dados Locais”.
Passo 1 — Informações Gerais do Roteiro
Campos: Nome (obrigatório), Data de embarque (obrigatória), Horário inicial e final da rota, Horário inicial e final do almoço, Velocidade média, Descarregamento por peso por minuto OU Tempo médio de descarregamento (mutuamente exclusivos — só um dos dois pode ser preenchido), e Centro de Distribuição (obrigatório, ponto de partida dos veículos).
Ao editar um roteiro já existente, todos os campos deste passo ficam bloqueados para alteração, exceto Nome e Data de embarque — os horários, a velocidade, o modo de descarregamento e o Centro de Distribuição só podem ser definidos na criação.
Se o usuário preencher só um dos dois horários da rota (início ou fim), o Painel pede o outro antes de avançar; se deixar os dois vazios, o roteiro segue sem restrição de horário, mas pede uma confirmação extra avisando que a restrição de tempo só é aplicada com os dois horários preenchidos. A mesma regra de par completo vale para o horário de almoço. Quando os quatro horários (início/fim da rota e início/fim do almoço) estão preenchidos, o Painel também exige que o horário de almoço esteja inteiramente contido dentro do horário da rota.
Passo 2 — Seleção de Veículos
Lista os veículos da empresa com filtros por placa, marca, tipo, carroceria, modelo, capacidade, acesso ao Centro Expandido de São Paulo e dia de rodízio. Duas abas alternam entre “Lista” (todos os veículos filtrados) e “Selecionados” (os já escolhidos para este roteiro, com capacidade total somada).
Um veículo já usado em outro roteiro roteirizado hoje continua selecionável sem contar de novo contra o limite diário; um veículo novo só pode ser adicionado se ainda houver limite diário de veículos distintos disponível — caso contrário, a seleção é bloqueada com aviso. Ao editar um roteiro existente, um veículo que já tem entregas atribuídas fica bloqueado para remoção da seleção.
Cada veículo pode ser marcado individualmente para “retornar à origem” ao final da rota (volta ao Centro de Distribuição depois da última entrega) — sem essa marcação, a rota termina na última entrega.
Passo 3 — Seleção de Entregas
Lista as entregas com status “aguardando” dentro do período de embarque informado (o padrão é a data do roteiro), com filtros por tipo de documento, emissor, cliente, número, CEP, logradouro, bairro, cidade, UF, e — para empresas integradas ao Atak — filial, Centro de Distribuição, percurso, temperatura e característica (com/sem osso). Duas abas alternam entre “Lista” e “Selecionados”, com contagem e peso total somado. As colunas exibidas na tabela são uma preferência do usuário, guardada no servidor — não mudam de navegador para navegador, mas mudam entre usuários diferentes.
Ao lado da seleção, três ações adicionais: IMPORTAR entregas a partir de arquivo (.csv, .xls, .xlsx, .xml ou .txt), ADICIONAR uma entrega manualmente, e CORRIGIR ENDEREÇOS — disponível apenas quando o Painel identifica alguma entrega com endereço inconsistente dentro do período filtrado; a correção roda em lote e pode levar um tempo para concluir. Para empresas integradas ao Atak, um botão SINCRONIZAR adicional importa pedidos diretamente do sistema integrado.
Se as entregas selecionadas pertencerem a mais de uma filial, o Painel pede para escolher a filial padrão do roteiro antes de avançar (ver Regras de Negócio).
Passo 4 — Resumo e Envio
Mostra um resumo com data, total de veículos, capacidade somada, total de entregas, peso total e total de locais distintos (endereços únicos). Duas opções controlam a otimização: “Restrição de peso” (respeita a capacidade de cada veículo ao distribuir as entregas) e “Restrição de tempo” (respeita a janela de horário de cada entrega e do veículo) — a segunda só pode ser ativada se os horários de início e fim da rota tiverem sido informados no Passo 1.
O botão final muda conforme o contexto: CRIAR ROTAS (roteiro novo) envia o conjunto para o motor de otimização; COMPARAR ROTAS (modo comparação) roteiriza automaticamente e, ao mesmo tempo, monta a sequência manual informada, para exibir as duas lado a lado; EDITAR ROTAS (roteiro já existente) reconstrói a visualização a partir da sequência já salva, sem chamar o motor de otimização novamente.
Se houver alguma entrega sem peso informado e a restrição de peso estiver ativa, o Painel avisa que a restrição será desconsiderada inteiramente para o envio (não apenas para aquela entrega) e pede confirmação antes de prosseguir.
Mapa do Roteiro Gerado
Exibe o mapa com as rotas calculadas, um resumo recolhível com a lista de veículos com rota e sem rota (cada um com o percentual de ocupação de peso e de tempo, coloridos em verde até 50%, amarelo entre 50% e 90% e vermelho acima disso) e, se houver, a lista de entregas desvinculadas (sem veículo definido). Passar o mouse sobre um ponto do mapa mostra um resumo da entrega ou do Centro de Distribuição.
Os botões SALVAR, SINCRONIZAR e FINALIZAR exigem permissão de edição e ficam desabilitados enquanto não houver ao menos uma rota gerada, durante o processamento, e depois que o roteiro já estiver finalizado.
Editar Sequência de Entregas de um Veículo
Permite arrastar e soltar as entregas de um único veículo para mudar a ordem de atendimento, ou inverter a sequência inteira com um botão. Uma entrega com status “desvinculado” (cancelada depois de já roteirizada) não pode ser arrastada. A confirmação recalcula apenas a sequência e a ordem de carregamento localmente — não chama o motor de otimização de novo; a persistência só ocorre quando o roteiro é salvo ou finalizado.
Mover Entregas Entre Veículos ou Para Desvinculadas
Permite arrastar entregas entre o veículo atual, um segundo veículo escolhido (quando o roteiro tem mais de um) e a lista de desvinculadas. Cada entrega pode ser “fixada” antes de confirmar, para que o motor de otimização priorize mantê-la na posição definida ao recalcular. Ao confirmar, se o veículo já tinha rota, o Painel pergunta se deve roteirizar novamente (chamando o motor) ou apenas manter a sequência atual informada manualmente; se algum veículo envolvido tiver entrega com status “desvinculado”, a operação inteira é bloqueada até que ela seja movida para a lista de desvinculadas. As opções de restrição de peso e de tempo daquele veículo são reavaliadas dinamicamente conforme o novo conjunto de entregas (o Painel sugere ativar ou desativar cada restrição conforme o peso total e os horários informados).
Sincronização com o Sistema Integrado
Disponível apenas para empresas com a integração configurada. A partir da lista de roteiros ou do mapa, SINCRONIZAR abre um formulário para revisar motorista, veículo, percurso e ajudantes de cada rota antes de enviar as cargas ao sistema integrado; o mesmo formulário valida que o mesmo motorista, ou o mesmo veículo, não esteja selecionado em mais de uma rota do envio. Existem telas auxiliares para ativar/inativar percursos e ajudantes usados nessa sincronização, acessadas de dentro do próprio formulário.
Separadamente, SINCRONIZAR (botão global da lista) e COMPARAR ROTEIRO importam cargas já montadas manualmente no sistema integrado para dentro do Painel — a primeira gera diretamente um roteiro novo com a sequência importada; a segunda gera esse mesmo roteiro manual e, ao lado, roteiriza automaticamente as mesmas entregas para comparação.
Remoção de Roteiro
Ao remover um roteiro que ainda não tem nenhuma carga sincronizada externamente, a remoção é imediata e devolve as entregas ao status “aguardando”. Se o roteiro tiver ao menos uma carga já sincronizada, o Painel pergunta se as cargas também devem ser removidas do sistema integrado antes; a remoção de cada carga externa é reportada individualmente (sucesso ou falha por veículo), e o usuário decide se remove o roteiro interno mesmo que alguma carga externa não tenha sido removida. Em qualquer um dos casos, se o roteiro já estava finalizado, a remoção também desfaz a atribuição feita nas entregas: motorista, placa e carga voltam a ficar vazios.
Download e Relatório do Roteiro
BAIXAR oferece dois formatos: um arquivo padrão em CSV e um arquivo em TXT (rotulado como “padrão Atak” para empresas integradas). RELATÓRIO gera um PDF de carga por roteiro (disponível só para roteiros finalizados), aberto em um visualizador próprio dentro do Painel.
Feedbacks ao Usuário
Passo 1 — Horários
| Situação | Feedback | Texto exato |
|---|---|---|
| Nome não preenchido | Notificação de erro + destaque no campo | “‘NOME’ deve ser preenchido.” |
| Data de embarque não preenchida | Notificação de erro + destaque no campo | “‘DATA DE EMBARQUE’ deve ser preenchido.” |
| Só um dos dois horários da rota preenchido (início sem fim) | Notificação de erro + destaque nos dois campos | “‘HORÁRIO DE TÉRMINO’ não preenchido.” |
| Só um dos dois horários da rota preenchido (fim sem início) | Notificação de erro + destaque nos dois campos | “‘HORÁRIO DE INÍCIO’ não preenchido.” |
| Horário de início igual ou maior que o de término | Notificação de erro + destaque nos dois campos | “‘HORÁRIO DE INÍCIO’ não pode ser maior, ou igual, ao ‘HORÁRIO DE TÉRMINO’.” |
| Almoço com só um dos dois horários preenchido (fim faltando) | Notificação de erro + destaque nos dois campos | “‘HORÁRIO DE TÉRMINO DO ALMOÇO’ não preenchido.” |
| Almoço com só um dos dois horários preenchido (início faltando) | Notificação de erro + destaque nos dois campos | “‘HORÁRIO DE INÍCIO DO ALMOÇO’ não preenchido.” |
| Início do almoço igual ou maior que o término do almoço | Notificação de erro + destaque nos dois campos | “‘HORÁRIO DE INÍCIO DO ALMOÇO’ não pode ser maior, ou igual, ao ‘HORÁRIO DE TÉRMINO DO ALMOÇO’.” |
| Horário de início da rota igual ou maior que o início do almoço | Notificação de erro + destaque nos dois campos | “‘HORÁRIO DE INÍCIO’ não pode ser maior, ou igual, ao ‘HORÁRIO DE INÍCIO DO ALMOÇO’.” |
| Horário de início da rota igual ou maior que o término do almoço | Notificação de erro + destaque nos dois campos | “‘HORÁRIO DE INÍCIO’ não pode ser maior, ou igual, ao ‘HORÁRIO DE TÉRMINO DO ALMOÇO’.” |
| Horário de término da rota igual ou menor que o início do almoço | Notificação de erro + destaque nos dois campos | “‘HORÁRIO DE TÉRMINO’ não pode ser menor, ou igual, ao ‘HORÁRIO DE INÍCIO DO ALMOÇO’.” |
| Horário de término da rota igual ou menor que o término do almoço | Notificação de erro + destaque nos dois campos | “‘HORÁRIO DE TÉRMINO’ não pode ser menor, ou igual, ao ‘HORÁRIO DE TÉRMINO DO ALMOÇO’.” |
Passo 1 — Demais Campos e Confirmações
| Situação | Feedback | Texto exato |
|---|---|---|
| Velocidade média zero ou negativa | Notificação de erro + destaque no campo | “‘VELOCIDADE MÉDIA’ não pode ser igual ou menor que zero.” |
| Velocidade média com formato inválido | Notificação de erro + destaque no campo | “‘VELOCIDADE MÉDIA’ inválida.” |
| Preenchidos peso/min e tempo médio de descarga ao mesmo tempo | Notificação de erro + destaque nos dois campos | “É necessário informar somente um dos dois campos, o ‘DESCARREGAMENTO DE PESO POR MINUTO’ ou o ‘TEMPO MÉDIO DE DESCARREGAMENTO’.” |
| Descarregamento por peso/min zero ou negativo | Notificação de erro + destaque no campo | “‘DESCARREGAMENTO DE PESO POR MINUTO’ não pode ser igual ou menor que zero.” |
| Tempo médio de descarregamento zero ou negativo | Notificação de erro + destaque no campo | “‘TEMPO MÉDIO DE DESCARREGAMENTO’ não pode ser igual ou menor que zero.” |
| Centro de Distribuição não selecionado | Notificação de erro + destaque no campo | “‘CENTRO DE DISTRIBUIÇÃO’ deve ser preenchido.” |
| Sem restrição de horário e almoço preenchido | Confirmação | “O horário do almoço será desconsiderado devido aos campos de início e término das entregas estarem vazios. – SOMENTE SERÁ CONSIDERADA A RESTRIÇÃO DE TEMPO SE OS HORÁRIOS ESTIVEREM PREENCHIDOS – Deseja continuar?” |
| Sem restrição de horário e almoço vazio | Confirmação | “Os horários de início e término das entregas estão vazios. – SOMENTE SERÁ CONSIDERADA A RESTRIÇÃO DE TEMPO SE OS HORÁRIOS ESTIVEREM PREENCHIDOS – Deseja continuar?” |
Passo 2 e Passo 3 — Seleção
| Situação | Feedback | Texto exato |
|---|---|---|
| Nenhum veículo selecionado | Notificação de erro | “Selecione ao menos um veículo.” |
| Contagem de veículos selecionados inconsistente | Notificação de erro | “Não possível identificar todos os veículos selecionados.” |
| Limite diário de veículos distintos atingido | Notificação de erro | “O seu limite diário de veículos distintos para roteirização foi atingido. Caso precise selecionar mais veículos, por favor, entre em contato conosco.” |
| Nenhuma entrega selecionada | Notificação de erro | “Selecione ao menos uma entrega.” |
| Contagem de entregas selecionadas inconsistente | Notificação de erro | “Não foi possível identificar todas as entregas selecionadas.” |
| Filtro de entregas sem as duas datas de embarque | Notificação de erro + destaque nos campos | “Por favor, informe a data de embarque inicial e final.” |
| Confirmação de correção de endereços em lote | Confirmação | “Essa ação poderá levar um tempo até ser concluída, deseja continuar?” |
| Arquivo importado com extensão inválida | Notificação de erro | “O arquivo {nome do arquivo} não é de extensão válida (.csv, .xls, .xlsx, .xml ou .txt).” |
| Nenhum arquivo válido para importar | Notificação de erro | “Por favor, importe arquivoa válidos (.csv, .xls, .xlsx, .xml ou .txt).” |
Passo 4 e Envio ao Motor de Otimização
| Situação | Feedback | Texto exato |
|---|---|---|
| Entregas sem peso informado e restrição de peso ativa | Confirmação | “Existem entregas sem o peso informado – SOMENTE SERÁ CONSIDERADA RESTRIÇÃO DE PESO SE TODAS AS ENTREGAS TIVEREM O PESO INFORMADO – Deseja continuar?” |
| Falha ao gerar o roteiro | Notificação de erro | “Não foi possível gerar um roteiro. Por favor, verifique as informações que deseja roteirizar e tente novamente.” |
| Falha de comunicação ao enviar para o motor | Notificação de erro | “Não foi possível processar o roteiro. Por favor, tente novamente.” |
| Motor de otimização rejeita uma entrega específica | Notificação de erro | “Entrega Nº {número do documento}: {mensagem retornada pelo motor}” |
| Motor de otimização rejeita um veículo específico | Notificação de erro | “Veículo {placa}: {mensagem retornada pelo motor}” |
Mapa — Resultado, Salvar e Finalizar
| Situação | Feedback | Texto exato |
|---|---|---|
| Nenhuma rota viável com as restrições informadas | Notificação de erro | “Infelizmente, com as restrições iniciais, não foi possível gerar rotas viáveis. Por favor, tente editar as entregas dos veículos.” |
| Otimização concluída com sucesso | Notificação de sucesso | “Otimização cargas e rotas concluída.” |
| Resumo de rotas geradas | Notificação de sucesso | “Total de rotas geradas: {quantidade}.” |
| Resumo de entregas vinculadas | Notificação de sucesso | “Total de entregas vinculadas: {quantidade}.” |
| Resumo de entregas desvinculadas | Notificação de sucesso | “Total de entregas desvinculadas: {quantidade}.” |
| Entrega já desvinculada em outro roteiro | Confirmação | “Uma ou mais entregas estão desvinculadas em outros roteiros: entrega {número} (carga {carga})(, …). É necessário remover dos roteiros anteriores para continuar. Deseja remover agora?” |
| Roteiro salvo com sucesso | Notificação de sucesso | “Roteiro salvo com sucesso.” |
| Mesmo motorista em mais de uma rota do roteiro | Notificação de erro | “Motorista, {nome}, está selecionado para mais de uma rota no mesmo período.” |
| Tentativa de salvar sem nenhuma rota gerada | Notificação de erro | “Não há rotas geradas.” |
| Entrega com status desvinculado ao tentar finalizar | Aviso (alerta) | “Há entrega(s) com status DESVICULADO, que pode(m) ter sido cancelada(s), no(s) veículo(s). – REMOVA-A(S) PARA A LISTA DE DESVINCULADAS PARA FINALIZAR.” |
| Confirmação de finalização | Confirmação | “As rotas geradas serão salvas, suas entregas atribuidas as cargas do roteiro do dia {data} e seus veículos atribuídos ao limite diário de veículos distintos roteirizados. Deseja continuar?” |
| Roteiro finalizado com sucesso | Notificação de sucesso | “Roteiro finalizado com sucesso.” |
Lista de Roteiros e Sincronização
| Situação | Feedback | Texto exato |
|---|---|---|
| Confirmação de remoção de roteiro | Confirmação | “Deseja mesmo remover o roteiro?” |
| Roteiro com carga já sincronizada, confirmando remoção também externa | Confirmação | “O roteiro possui carga(s) sincronizada(s) externamente, deseja também remover as carga(s) no Sitema Integrado {nome da integração}?” |
| Remoção concluída com sucesso | Notificação de sucesso | “Roteiro removido com sucesso.” |
| Limite diário de roteirização não configurado | Aviso (alerta) | “Seu limite diário de veículos roterizados parece não estar configurado. Favor entrar em contato com o suporte.” |
| Roteirização inacabada encontrada ao abrir a lista | Confirmação | “Existe uma roteirização inacabada. Deseja retomar a roteirização?” |
| Confirmação de cancelamento do assistente | Confirmação | “Deseja mesmo cancelar?” |
| Confirmação de salvar progresso ao sair sem finalizar | Confirmação | “Deseja salvar a roteirização em andamento antes de sair?” |
| Configuração de integração ausente | Notificação de erro | “Configuração de integração não selecionada em: Configurações -> Roteirização.” |
| Endereço de conexão com o sistema integrado ausente | Notificação de erro | “Endereço da API de integração não informado em: Configurações -> Roteirização.” |
| Falha de conexão com o sistema integrado | Notificação de erro | “Não foi possível conectar com a API do sistema integrado.” |
| Mesmo motorista em mais de uma rota (sincronização) | Notificação de erro | “Motorista {nome} está selecionado para mais de uma rota no mesmo período.” |
| Mesmo veículo em mais de uma rota (sincronização) | Notificação de erro | “Veículo {placa} está selecionado para mais de uma rota no mesmo período.” |
Sessão expirada: em qualquer chamada ao servidor nesta feature, se a sessão tiver expirado o Painel exibe “Desculpe, sua sessão expirou.” e desconecta automaticamente o usuário após 2 segundos — comportamento comum a toda a tela, não repetido linha a linha acima.
Regras de Negócio
Limite Diário de Veículos Distintos Roteirizados
O limite diário é definido por empresa e contado por placa de veículo distinta usada no dia (não por quantidade de roteiros). Um veículo já contabilizado no dia pode ser reutilizado em outro roteiro sem consumir o limite de novo. Atualmente, finalizar um roteiro nesta tela não decrementa esse limite — a contagem só é de fato atualizada quando uma carga é sincronizada com o sistema integrado Atak, ou quando entregas são atribuídas manualmente em lote pela tela Entregas; para uma empresa sem essa integração, o limite exibido tende a nunca diminuir por esta tela, mesmo finalizando roteiros normalmente.
Restrição de Peso e de Tempo na Otimização
A restrição de peso, quando ativa, faz o motor de otimização respeitar a capacidade de cada veículo ao distribuir as entregas; se qualquer entrega do envio estiver sem peso informado, a restrição inteira é desconsiderada para aquele envio, mediante confirmação do usuário. A restrição de tempo só é aplicada quando o roteiro tem horário de início e término definidos; sem os dois preenchidos, a otimização ignora completamente qualquer janela de horário das entregas.
Horário de Atendimento de Cada Entrega
O horário de atendimento usado por entrega segue esta ordem de prioridade: (1) horário definido manualmente para aquela entrega; (2) primeira e última janela de horário cadastrada para aquele cliente no dia da semana correspondente à data de embarque; (3) horário geral de início/término do roteiro.
Tempo de Descarregamento
Cada entrega usa, nesta ordem: o tempo médio de descarregamento específico daquele cliente, se cadastrado; senão, o valor geral definido no roteiro (tempo médio de descarregamento OU descarregamento por peso por minuto, conforme o que foi configurado no Passo 1 — os dois nunca coexistem no mesmo roteiro).
Sequência e Ordem de Carregamento
Dentro de cada veículo, a sequência de atendimento é numerada de forma crescente a partir do Centro de Distribuição (posição 0); a ordem de carregamento é o inverso — a última entrega da rota é a primeira a ser carregada no veículo. Reordenar manualmente a sequência de um veículo recalcula os dois valores sem chamar novamente o motor de otimização.
Retorno à Origem
Cada veículo pode ser configurado individualmente para retornar ao Centro de Distribuição ao final da rota. Quando marcado, o ponto de retorno é adicionado como último ponto da rota, sem tempo de deslocamento nem horário de atendimento considerados na volta.
Acesso ao Centro Expandido de São Paulo e Rodízio
Um veículo marcado como habilitado a acessar o Centro Expandido de São Paulo tem seu dia de rodízio calculado pelo último dígito da placa: final 1 ou 2 (segunda-feira), 3 ou 4 (terça-feira), 5 ou 6 (quarta-feira), 7 ou 8 (quinta-feira), 9 ou 0 (sexta-feira). Um veículo sem essa marcação não tem dia de rodízio calculado.
Filial Padrão do Roteiro
Quando as entregas selecionadas (empresas integradas ao Atak) pertencem a mais de uma filial, é obrigatório escolher qual delas será a filial padrão do roteiro antes de prosseguir; havendo apenas uma filial entre as entregas selecionadas, ela é aplicada automaticamente, sem necessidade de escolha.
Comparação Entre Sequência Manual e Roteirização Automática
No modo de comparação, o Painel calcula, para o mesmo conjunto de entregas: a diferença percentual de veículos usados, de capacidade de peso somada, de entregas atendidas, de peso total, de distância e de tempo estimados entre a sequência montada manualmente e a sequência calculada pelo motor de otimização (percentual positivo indica que a versão roteirizada automaticamente usa menos recursos). A ocupação de capacidade é comparada de forma direta (quanto maior, melhor) e a eficiência (distância média por veículo) de forma invertida (quanto menor a distância por veículo, melhor).
Formação do Código de Carga
Ao finalizar o roteiro, cada entrega recebe um código de carga formado pelo nome do roteiro combinado com a posição do veículo dentro dele — é esse código que aparece na Lista de Roteiros e que identifica a carga também no sistema integrado, quando aplicável. Enquanto o roteiro não é finalizado, esse código permanece vazio (a lista mostra “Não finalizado”).
Sincronização Externa Após Alteração do Roteiro
Se um veículo do roteiro já tinha uma carga sincronizada com o sistema integrado e o conjunto de entregas desse veículo muda numa gravação seguinte (entrega adicionada, removida ou movida para outro veículo), esse veículo passa a ficar pendente de nova sincronização e o roteiro deixa de ser considerado sincronizado como um todo.
Comportamento Offline e Dados Locais
O progresso de uma roteirização em andamento (da etapa 2 até a etapa 4 do assistente) pode ser salvo no navegador do usuário ao sair da tela sem cancelar explicitamente, mediante confirmação. Esse progresso — passo atual, veículos e entregas selecionados, filtros aplicados — fica guardado apenas naquele navegador; ao reabrir a tela Roteirizações no mesmo navegador, o Painel oferece retomar de onde parou, e o progresso salvo é descartado assim que retomado ou quando o usuário cancela explicitamente o assistente. Esse mecanismo não sincroniza entre dispositivos nem entre usuários diferentes, e não tem relação com uso sem conexão à internet — a tela exige conexão ativa com o servidor durante toda a montagem do roteiro.
Separadamente, a seleção de veículos e de entregas feita durante a montagem de um roteiro novo é também temporariamente guardada no servidor, para manter a seleção entre páginas e filtros da mesma tela — mas isso não impede que a mesma entrega seja escolhida ao mesmo tempo em duas montagens de roteiro diferentes; apenas o roteiro salvo por último efetivamente recebe aquela entrega (ver Troubleshooting).
Evidências e Documentos Gerados
O download do roteiro (botão BAIXAR) gera um arquivo em CSV ou um arquivo em TXT (rotulado como padrão Atak para empresas integradas), montado pelo servidor a partir dos dados já salvos do roteiro — sempre gerado na hora, nunca reaproveitado de uma exportação anterior. O relatório de carga por roteiro (botão RELATÓRIO, disponível só para roteiros finalizados) gera um PDF com os dados de carga daquele roteiro específico, também montado na hora. No modo de comparação, o Painel também é capaz de gerar um PDF comparativo entre a sequência manual e a roteirizada. Nenhum desses arquivos é armazenado no servidor após a geração — cada solicitação gera um novo arquivo.
Troubleshooting
O botão NOVO ROTEIRO não avança e avisa sobre o limite diário
Cenário: o usuário clica em NOVO ROTEIRO, mas o limite diário de veículos roteirizados da empresa não está configurado.
Mensagem exibida: “Seu limite diário de veículos roterizados parece não estar configurado. Favor entrar em contato com o suporte.”
O que fazer: contatar o suporte para que o limite diário de veículos roteirizados da empresa seja configurado.
A seleção de um veículo é bloqueada mesmo havendo veículos disponíveis
Cenário: o usuário tenta selecionar um veículo ainda não usado hoje, mas o limite diário de veículos distintos já foi atingido no dia.
Mensagem exibida: “O seu limite diário de veículos distintos para roteirização foi atingido. Caso precise selecionar mais veículos, por favor, entre em contato conosco.”
O que fazer: reutilizar um veículo já roteirizado hoje, ou contatar o suporte para ampliar o limite diário.
Não é possível avançar do Passo 3 sem selecionar nenhuma entrega
Cenário: o usuário tenta avançar para o Passo 4 sem marcar nenhuma entrega na lista.
Mensagem exibida: “Selecione ao menos uma entrega.”
O que fazer: selecionar ao menos uma entrega com status “aguardando” dentro do período filtrado antes de avançar.
Nenhuma rota viável é gerada após o processamento
Cenário: o motor de otimização recebeu o conjunto de veículos e entregas, mas nenhuma rota pôde ser montada respeitando as restrições informadas (peso e/ou tempo).
Mensagem exibida: “Infelizmente, com as restrições iniciais, não foi possível gerar rotas viáveis. Por favor, tente editar as entregas dos veículos.”
O que fazer: voltar e revisar as entregas e veículos selecionados, ou desativar temporariamente a restrição de peso ou de tempo para verificar se o volume de entregas é compatível com a capacidade disponível.
Não é possível salvar o roteiro porque o mesmo motorista aparece em duas rotas
Cenário: o usuário atribuiu o mesmo motorista a dois veículos diferentes dentro do mesmo roteiro antes de salvar ou finalizar.
Mensagem exibida: “Motorista, {nome}, está selecionado para mais de uma rota no mesmo período.”
O que fazer: revisar os veículos do roteiro e atribuir um motorista diferente a cada rota antes de salvar.
O botão FINALIZAR é bloqueado por causa de uma entrega desvinculada
Cenário: uma entrega já roteirizada em um dos veículos foi cancelada por outro canal (por exemplo, diretamente na tela Entregas) enquanto o roteiro ainda estava sendo editado, e por isso passou a ter status “desvinculado”.
Mensagem exibida: “Há entrega(s) com status DESVICULADO, que pode(m) ter sido cancelada(s), no(s) veículo(s). – REMOVA-A(S) PARA A LISTA DE DESVINCULADAS PARA FINALIZAR.”
O que fazer: abrir a edição do veículo indicado, mover a entrega desvinculada para a lista de entregas desvinculadas e tentar finalizar novamente.
O limite diário de veículos nunca parece diminuir, mesmo finalizando roteiros
Cenário: a empresa não usa a integração com o sistema integrado Atak; roteiros são finalizados normalmente, mas o indicador de veículos disponíveis no dia continua igual.
Mensagem exibida: Nenhuma — o indicador simplesmente não muda depois de finalizar um roteiro.
O que fazer: não é um problema pontual de uma tentativa — hoje, finalizar um roteiro por esta tela não contabiliza o limite diário para empresas sem a integração; se o controle desse limite for necessário, contatar o suporte para avaliar o cadastro do consumo por outro caminho (edição em lote de entregas ou sincronização).
Uma entrega selecionada em um roteiro “desaparece” depois de aparecer em outro roteiro salvo por outra pessoa
Cenário: duas pessoas da mesma empresa monta(ra)m, ao mesmo tempo, dois roteiros diferentes e ambas selecionaram a mesma entrega ainda disponível; o roteiro salvo por último é o que efetivamente fica com aquela entrega.
Mensagem exibida: Nenhuma no momento da seleção duplicada — o aviso só aparece depois, ao tentar salvar o roteiro que perdeu a entrega, avisando que ela está desvinculada em outro roteiro (ver T-09).
O que fazer: combinar com a equipe para não montar dois roteiros com o mesmo período/entregas ao mesmo tempo; se acontecer, seguir a confirmação de remoção do vínculo anterior ao salvar o segundo roteiro.
Ao salvar, o Painel avisa que uma entrega já está desvinculada em outro roteiro
Cenário: alguma das entregas selecionadas para este roteiro já está marcada como desvinculada dentro de outro roteiro da empresa.
Mensagem exibida: “Uma ou mais entregas estão desvinculadas em outros roteiros: entrega {número} (carga {carga}). É necessário remover dos roteiros anteriores para continuar. Deseja remover agora?”
O que fazer: confirmar a remoção do vínculo anterior para continuar salvando este roteiro; recusar interrompe o salvamento sem alterar nada.
A tela de sincronização com o sistema integrado fecha sozinha com aviso de configuração
Cenário: o usuário aciona SINCRONIZAR ou COMPARAR ROTEIRO, mas a integração da empresa não está configurada, ou o endereço de conexão com o sistema integrado não foi informado.
Mensagem exibida: “Configuração de integração não selecionada em: Configurações -> Roteirização.” ou “Endereço da API de integração não informado em: Configurações -> Roteirização.”
O que fazer: completar a configuração da integração em Configurações -> Roteirização antes de tentar sincronizar novamente.
A sincronização é desfeita e o roteiro volta a não-finalizado sozinho
Cenário: o usuário finalizou um roteiro e, na sequência, tentou sincronizar as cargas com o sistema integrado, mas a conexão com o sistema integrado falhou (mesmo que por uma instabilidade momentânea de rede).
Mensagem exibida: “Não foi possível conectar com a API do sistema integrado.”
O que fazer: verificar a conexão com a internet e o status do sistema integrado; o roteiro precisa ser finalizado novamente (motorista, placa e carga são reatribuídos ao finalizar de novo), então confirmar todos os dados antes de tentar sincronizar mais uma vez.
Um veículo ou uma de suas entregas pode não ser salvo sem nenhum aviso
Cenário: ao salvar um roteiro (com ou sem finalizar), o sistema regrava tudo a partir do que foi enviado na tela; se a gravação de um veículo específico ou de alguma de suas entregas falhar no meio desse processo, o roteiro ainda assim é considerado salvo com sucesso, desde que nenhum campo tenha sido rejeitado por validação.
Mensagem exibida: Nenhuma — o Painel confirma “Roteiro salvo com sucesso.” mesmo quando isso ocorre.
O que fazer: depois de salvar, conferir se todos os veículos e todas as entregas selecionadas aparecem corretamente no roteiro salvo; se algum estiver faltando, refazer a inclusão daquele veículo ou entrega e salvar novamente, ou contatar o suporte se o problema persistir.
Casos de Uso
Caso 1 — Criação de um roteiro novo do início ao fim
Um usuário clica em NOVO ROTEIRO, preenche o nome “ROTA SEGUNDA MANHÔ, a data de amanhã, horário de início e término da rota, e seleciona o Centro de Distribuição principal. No Passo 2, seleciona três veículos disponíveis dentro do limite diário. No Passo 3, filtra as entregas do dia seguinte e seleciona 40 entregas com status “aguardando”. No Passo 4, mantém a restrição de peso ativa (todas as entregas têm peso informado) e clica em CRIAR ROTAS. O motor de otimização retorna três rotas viáveis e nenhuma entrega desvinculada; o usuário revisa o mapa, clica em SALVAR e, depois de conferir tudo, em FINALIZAR — as 40 entregas passam a ter motorista, placa e carga atribuídos.
Caso 2 — Ajuste manual após a otimização automática
Depois de gerar as rotas do Caso 1, o usuário percebe que uma entrega ficou na lista de desvinculadas por estar fora da capacidade de peso de todos os veículos. Ele abre a edição de um dos veículos, arrasta essa entrega para a lista roteirizada daquele veículo e confirma. Como o peso total passou a exceder a capacidade do veículo, o Painel avisa e pergunta se deve desconsiderar a restrição de peso para aquele veículo especificamente; o usuário confirma, e o motor de otimização recalcula apenas a rota daquele veículo.
Caso 3 — Comparação entre roteirização manual e automática (empresa integrada)
Um usuário de uma empresa integrada ao Atak clica em COMPARAR ROTEIRO, escolhe a mesma data e importa uma carga já montada manualmente no sistema integrado, com sete veículos. O Painel monta a sequência manual exatamente como veio do sistema integrado e, ao mesmo tempo, roteiriza automaticamente o mesmo conjunto de entregas. O resumo comparativo mostra que a versão automática usa apenas cinco veículos e reduz a distância total estimada em 18% — o usuário decide salvar a versão automática como o roteiro do dia.
Caso 4 (borda) — Tentativa de finalizar com uma entrega cancelada no meio do processo
Enquanto um roteiro ainda está aberto no mapa (sem finalizar), outra pessoa cancela uma das entregas já roteirizadas diretamente na tela Entregas. Ao tentar FINALIZAR, o Painel identifica que essa entrega está com status “desvinculado” dentro do veículo e bloqueia a finalização, orientando o usuário a movê-la para a lista de desvinculadas antes de tentar novamente.
