Rotas e relacionados (Itinerary (Rotas))
A API de Itinerary é responsável pela manutenção das rotas. É nela que vamos conseguir criar uma rota e permitir vincular locais, pessoas e atividades na mesma. Através dos recursos desta API poderemos criar rotas e atualizar as mesmas.
Descrição de um Rota
OBS: Para atualização de cadastro, somente o identificador alternativo é obrigatório.
Busca Por Lista de Rotas
GET /CenterWeb/api/{$apiKey}/itinerary.xml
Veja um exemplo, do resultado de uma requisição que foi feita em XML:
<result>
<resourceName>itinerary</resourceName>
<size>2</size>
<entries>
<entry id="001" link="/itinerary/001.xml"/>
<entry id="002" link="/itinerary/002.xml"/>
</entries>
</result>
A resposta da requisição será uma mensagem contendo o total de registro retornados e uma lista simples, sem detalhes de cada registro retornado, contendo para cada entrada, Id do registro no uMov.me e o link, que pode ser usado para recuperar os dados específicos deste registro.
Busca de uma rota específica
GET /CenterWeb/api/{$apiKey}/itinerary/{$id}.xml
Esta operação serve para puxar informações de uma rota do sistema. Veja o exemplo de retorno de uma entidade abaixo (considerando uma requisição feita em XML):
<itinerary>
<id>25142</id>
<description>Rota_Teste_1</description>
<origin>0</origin>
<agentRelation>0</agentRelation>
<displayOrder>1</displayOrder>
<alternativeIdentifier>Rota_Teste_1</alternativeIdentifier>
<active>true</active>
<validateTasksOnField>0</validateTasksOnField>
<exclusive>true</exclusive>
<itineraryDefault>true</itineraryDefault>
</itinerary>
Observação: Na consulta de uma rota já criada, o sistema não lista as atividades <activities>, locais <serviceLocal> e pessoas (agent) vinculadas a rota. Para isso, devem ser realizadas as demais chamadas conforme descrito na documentação de rotas.
Inclusão de uma rota
POST /CenterWeb/api/{$apiKey}/itinerary.xml
Esta operação serve para incluir uma rota no sistema. Existe um mínimo de informações que o sistema espera receber para poder realizar a criação de um novo registro no ambiente em questão. Confira a descrição de uma Rota para identificar os campos obrigatórios. Veja um exemplo da requisição com dados em XML:
<itinerary>
<description>Teste rota</description>
<origin>0</origin>
<agentRelation>1</agentRelation>
<displayOrder>1</displayOrder>
<alternativeIdentifier>TesteRota</alternativeIdentifier>
<validateTasksOnField>0</validateTasksOnField>
<exclusive>false</exclusive>
<active>true</active>
<itineraryDefault>false</itineraryDefault>
</itinerary>
Atualização de uma Rota
Ambas as operações abaixo permitem atualizar informações de uma rota utilizando ou o id interno ou o identificador alternativo. Assim é possível atualizar a rota enviando apenas os dados desejados conforme é demonstrado o xml de exemplo abaixo:
Utilizando id interno
POST /CenterWeb/api/{$apiKey}/itinerary/{$id}.xml
Utilizando identificador alternativo
POST /CenterWeb/api/{$apiKey}/itinerary/alternativeIdentifier/{$alternativeIdentifier}.xml
<itinerary>
<description>Teste Rota Nova</description>
</itinerary>
Busca de uma rota específica através do identificador alternativo
GET /CenterWeb/api/{$apiKey}/itinerary/alternativeIdentifier/{$alternative identifier}.xml
Esta operação serve para buscar informações de uma rota do sistema. Veja o exemplo de retorno de uma entidade abaixo (considerando uma requisição feita em XML):
<itinerary>
<id>25142</id>
<description>Rota_Teste_1</description>
<origin>0</origin>
<agentRelation>0</agentRelation>
<displayOrder>1</displayOrder>
<alternativeIdentifier>Rota_Teste_1</alternativeIdentifier>
<active>true</active>
<validateTasksOnField>0</validateTasksOnField>
<exclusive>true</exclusive>
<itineraryDefault>true</itineraryDefault>
</itinerary>