Tarefas e relacionados (Schedule Routing (Roteirizador de tarefas))
1. O que é e como funciona?
A API de Schedule Routing é responsável pela roteirização das tarefas. É nela que podemos definir um ponto de partida, um conjunto de tarefas e solicitar a roteirização, permitindo que o sistema calcule a melhor rota (sequência de tarefas) a ser realizada, que representa o menor caminho a ser percorrido, evitando gastos e tempos desnecessários de deslocamento para diferentes locais.
2. Quando uso?
Sempre que houver necessidade de otimizar as rotas realizadas pelos usuários.
3. Como configurar?
Abaixo você verá alguns exemplos de como utilizar a roteirização API.
POST /CenterWeb/api/{$apiKey}/scheduleRouting.xml
Esta operação permite a roteirização das tarefas. Ela é realizada baseada na distância linear entre os pontos para definir a melhor sequência a ser realizada. Após a ordenação concluída, o sistema utiliza a API do Google Maps para retornar os tempos e distâncias estimados entre as tarefas.
Veja um exemplo da requisição com dados em XML e os parâmetros que podem ser passados:
<route>
<route>true</route>
<origin>
<agent><id>7</id></agent>
<transportMode>0</transportMode>
</origin>
<updateSchedules>true</updateSchedules>
<startTime>2016-01-01 00:00:00</startTime>
<estimate>true</estimate>
<schedules>
<schedule><id>655490714</id></schedule>
<schedule><id>655490083</id></schedule>
<schedule><id>655490389</id></schedule>
</schedules>
</route>
Na requisição acima, podem ser verificados os seguintes parâmetros:
<route>true|false</route> - Se não informado, o padrão é true. Permite informar se o roteirizador deve ou não ordenar as tarefas informadas baseado no algoritmo de proximidade por distância linear.
Se informado false no parâmetro, o sistema não ordena as tarefas, permitindo que o usuário defina a ordem de execução. Dessa forma, o sistema pode apenas retornar o tempo e distância estimado baseado na ordem já definida.
Se informado true no parâmetro o sistema calcula a menor distância entre os pontos através da distância linear entre eles, retornando assim o menor caminho a ser percorrido.
<origin><agent><id>X</id></agent><origin> - Define o ponto de origem para o cálculo do roteirizador.
O ponto de partida pode ser a última posição de uma pessoa armazenada no sistema através da última coordenada GPS válida capturada pela pessoa em campo. Para isso, deve ser informado o id interno da pessoa, conforme mostrado no exemplo acima.
Pode também ser buscada a posição a partir de uma posição fixa, passando a coordenada GPS do ponto, conforme exemplo: <geoCoordinate>-51.00000,-50.94949494</geoCoordinate>
<origin><transportMode>0|1|2</transportMode></origin> - Define o tipo de transporte que será usado para calcular a estimativa de tempo e distância.
As opções possíveis são: 0 - Carro, 1 - Bicicleta, 2 - Andando.
Caso não informado, o sistema busca a informação no campo customizável da pessoa informada na origem, (campo com identificador alternativo = "modotransporteroteirizacao"). Se o campo da pessoa também estiver vazio, ou não não for informada a pessoa na origem, o sistema assume Carro (0) como padrão.
<updateSchedules>true|false</updateSchedules> - Se não informado, o padrão é true. Informa se o roteirizador deve ou não alterar a prioridade e a situação das tarefas.
Esse parâmetro depende do parâmetro anterior <route>. Ou seja, se informado para roteirizar <route>true</route> e atualizar as tarefas <updateSchedules>true</updateSchedules>, então o sistema armazena na tarefa a ordem de execução calculada na roteirização no campo prioridade da tarefa. Dessa forma, se configurado no ambiente para que a execução seja baseada na prioridade da tarefa, o usuário deve seguir a ordem definida no roteirizador.
Além disso, o sistema muda a situação da tarefa para “Pendente de Envio para Campo” caso a tarefa esteja “Em Preparação”.
Se informado para não roteirizar <route>false</route> o sistema também pode atualizar as tarefas, mas irá armazenar a ordem de execução definida na chamada da requisição. Se informado <updateSchedules>true</updateSchedules>, o sistema não altera as tarefas na base de dados.
<startTime> - Data e hora em que a roteirização será executada. Serve para agendamento da roteirização. Há casos em que a roteirização é disparada, por exemplo, às 00:00, para que o roteiro comece a ser executado às 08:00. Neste caso, pode-se adicionar a tag <startTime> para que a roteirização seja, de fato, realizada antes das 08:00, a fim de retornar um tempo total mais preciso.
<estimate>true|false</estimate> - Se não informado, o padrão é false. Informa se deve chamar API do Google para calcular a distância e tempo estimado para percorrer a distância entre um ponto e outro.
Se informado <estimate>true</estimate> retorna a estimativa de chegada para cada uma das tarefas.
Se informado <estimate>false</estimate> não retorna nenhuma estimativa para as tarefas.
<schedules></schedules> - lista de tarefas que devem ser ordenadas baseado nos demais parâmetros informados acima.
Há um limite de 50 tarefas por requisição.
Devem ser informadas as tarefas a partir de seu ID interno ou pelo Identificador Alternativo e todas as tarefas devem possuir locais com coordenadas GPS válidas.
Se algum local das tarefas informadas não possuir coordenada GPS calculada a partir de seu endereço, o sistema retorna erro, informando que não é possível executar a roteirização das tarefas informadas.
Há casos em que a tarefa deve ser realizada em determinado local. Porém, antes de chegar no destino final, o usuário precisa passar, obrigatoriamente, em outro local. Nesse caso, essas tarefas devem estar encadeadas na roteirização, para respeitar uma precedência, como o exemplo abaixo:
<schedules>
<schedule>
<id>29432937</id>
<dependencies>
<schedule>
<id>29432935</id>
</schedule>
</dependencies>
</schedule>
<schedule>
<id>29432935</id>
</schedule>
<schedule>
<id>29432936</id>
</schedule>
</schedules>
Roteirizar tarefas pelo identificador alternativo
Também permitimos que as tarefas sejam enviadas para roteirização a partir do Identificador Alternativo, deixando o processo mais simples e rápido, conforme exemplo abaixo:
<schedules>
<schedule><alternativeIdentifier>ALT_ID_1</alternativeIdentifier></schedule>
<schedule><alternativeIdentifier>ALT_ID_2</alternativeIdentifier></schedule>
<schedule><alternativeIdentifier>ALT_ID_3</alternativeIdentifier></schedule>
</schedules>
Armazenar distância e tempo
Foi criada a opção de armazenar distância e tempo estimado na tarefa, conforme cálculo realizado na roteirização.
Para habilitar essa opção, peça ao Help Desk em solicitação via e-mail (ajuda@umov.me) a habilitação destes campos.
Após isso, acesse o menu Tarefas no Center > Opções > Configurações > aba Center > Marque a flag: “Armazenar distância e tempo estimado na roteirização”. Ao clicar nessa opção e clicar em salvar, 4 campos são criados ou ativados na tarefa.
São campos customizáveis estruturais que servem para armazenar as seguintes informações:
Distância total estimada (Km): distância total em KM estimado entre a posição do entregador no momento da roteirização e a posição da entrega.
Distância parcial estimada (Km): distância parcial em KM estimado entre a posição da tarefa anterior e a posição da entrega seguinte. Se for primeira entrega, a distância é calculada com base na posição do entregador.
Tempo total estimado (min): tempo total em minutos estimado entre para a entrega, considerando a posição do entregador no momento da roteirização e a posição da entrega. Leva em conta o tempo de parada em cada uma das tarefas.
Tempo parcial estimado (min): tempo parcial em minutos estimado entre para a entrega considerando a posição da tarefa anterior e a posição da entrega seguinte. Se for a primeira entrega, o tempo é calculado com base na posição do entregador. Não considera o tempo de parada na tarefa.
Ao desativar a opção nas configurações da tarefa, o sistema desativa os campos criados para a tarefa.
Ao executar a roteirização, quando estes campos estiverem criados na tarefa e estiver marcada a opção para atualizar as tarefas (<updateSchedules>true</updateSchedules>), o sistema irá armazenar as informações nas tarefas baseado no retorno dado pela API do Google Maps.
Caso todos os parâmetros sejam informados corretamente na requisição, o sistema retorna a lista de tarefas ordenadas de acordo com as configurações definidas. Veja abaixo exemplos de chamadas da API de roteirização.
Exemplo1: Roteirização simples de 3 locais.
XML:
<route>
<route>true</route>
<origin>
<agent><id>66459</id></agent>
</origin>
<updateSchedules>true</updateSchedules>
<estimate>true</estimate>
<schedules>
<schedule><id>29432937</id></schedule>
<schedule><id>29432935</id></schedule>
<schedule><id>29432936</id></schedule>
</schedules>
</route>
Retorno:
<route>
<origin>
<agent><id>66459</id>
<alternativeIdentifier>dev</alternativeIdentifier>
</agent>
<transportMode>0</transportMode>
</origin>
<schedules>
<schedule>
<id>29432936</id>
<alternativeIdentifier>29432936</alternativeIdentifier>
<priority>10</priority>
<estimationTime>2016-02-23 23:01:13</estimationTime>
<distance>6373</distance>
<totalDistance>6373</totalDistance>
</schedule>
<schedule>
<id>29432937</id>
<alternativeIdentifier>29432937</alternativeIdentifier>
<priority>20</priority>
<estimationTime>2016-02-23 23:06:02</estimationTime>
<distance>1618</distance>
<totalDistance>7991</totalDistance>
</schedule>
<schedule>
<id>29432935</id>
<alternativeIdentifier>29432935</alternativeIdentifier>
<priority>30</priority>
<estimationTime>2016-02-23 23:09:20</estimationTime>
<distance>817</distance>
<totalDistance>8808</totalDistance>
</schedule>
</schedules>
</route>
Exemplo 2: Roteirização de 3 locais, onde existe precedência de tarefa.
XML:
<route>
<route>true</route>
<origin>
<agent><id>66459</id></agent>
</origin>
<updateSchedules>true</updateSchedules>
<estimate>true</estimate>
<schedules>
<schedule>
<id>29432937</id>
<dependencies>
<schedule><id>29432935</id></schedule>
</dependencies>
</schedule>
<schedule><id>29432935</id></schedule>
<schedule><id>29432936</id></schedule>
</schedules>
</route>
Retorno:
<route>
<origin>
<agent>
<id>66459</id>
<alternativeIdentifier>dev</alternativeIdentifier>
</agent>
<transportMode>0</transportMode>
</origin>
<schedules>
<schedule>
<id>29432936</id>
<alternativeIdentifier>29432936</alternativeIdentifier>
<priority>10</priority>
<estimationTime>2016-02-23 23:08:03</estimationTime>
<distance>6373</distance>
<totalDistance>6373</totalDistance>
</schedule>
<schedule>
<id>29432935</id>
<alternativeIdentifier>29432935</alternativeIdentifier>
<priority>20</priority>
<estimationTime>2016-02-23 23:12:53</estimationTime>
<distance>1412</distance>
<totalDistance>7785</totalDistance>
</schedule>
<schedule>
<id>29432937</id>
<alternativeIdentifier>29432937</alternativeIdentifier>
<priority>30</priority>
<estimationTime>2016-02-23 23:13:54</estimationTime>
<distance>369</distance>
<totalDistance>8154</totalDistance>
</schedule>
</schedules>
</route>