Base de Conhecimento

1. O que é e como funciona?

A API de Schedule é responsável pela manutenção das tarefas. É nela que vamos conseguir criar uma tarefa fazendo o panorama quem (Pessoa) deve ir onde (Local de Atendimento) fazer o que (Atividades relacionadas) e quando (identificando uma data e hora específica).

2. Quando uso?

API utilizada para criação e atualização de tarefas.

3. Como configurar?

Utilize os campos da tabela abaixo como referência no XML do corpo da requisição para criar ou atualizar os valores de uma tarefa.

- Para atualização de cadastro, somente o identificador alternativo é obrigatório.

- Para a inclusão de campos customizáveis do tipo multivalorado, leia a sessão de Inclusão/Alteração em lote de valores de Campos Customizáveis do artigo Custom Field / Custom Field Value (Campo customizável / Valor campo customizável).

Consulta de tarefas

Busca por lista de tarefas

GET /CenterWeb/api/{$apiKey}/schedule.xml

Se preferir ainda, pode refinar as pesquisas enviando parâmetros na requisição, para isso é necessário adicionar parâmetros igual realizamos em uma requisição HTTP:

GET /CenterWeb/api/{$apiKey}/schedule.xml?serviceLocal=134

ou caso necessite utilizar o Identificador Alternativo:

GET /CenterWeb/api/{$apiKey}/schedule.xml?serviceLocal.alternativeIdentifier=134

serviceLocal: pesquisar por um determinado local de atendimento

GET /CenterWeb/api/{$apiKey}/schedule.xml?agent=5421

agent: pesquisar por um determinado agente/pessoa

GET /CenterWeb/api/{$apiKey}/schedule.xml?initialInsertDateTime=AAAA-MM-DD HH:MM:SS&finalInsertDateTime=AAAA-MM-DD HH:MM:SS

Esta requisição filtra todas as tarefas que foram inseridas neste período de data e hora.

GET /CenterWeb/api/{$apiKey}/schedule.xml?situation=30

situation: situação da tarefa no sistema. Os valores possíveis são 30 (aguardando envio), 40 (em campo - disponível no dispositivo móvel), 50 (retornada de campo - executada) e 70 (cancelada).

GET /CenterWeb/api/{$apiKey}/schedule.xml?serviceLocal.country=Brasil&agent.active=true&situation.description=Em Campo

Filtra todas as tarefas com base em atributos das entidades vinculadas à tarefa

Enviar parâmetros para a API uMov.me é simples assim. Veja um exemplo, do resultado de uma requisição que foi feita em XML:

<result>

<resourceName>schedule</resourceName>

<size>2</size>

<entries>

<entry id="001" link="/schedule/001.xml"/>

<entry id="002" link="/schedule/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 tarefa específica através do id interno

GET /CenterWeb/api/{$apiKey}/schedule/{$id}.xml

Esta operação serve para puxar informações de uma tarefa do sistema. Veja o exemplo de retorno de uma entidade abaixo (considerando uma requisição feita em XML):

<schedule>

<id>93615</id>

<situation>

<id>50</id>

<description>Retornada de Campo</description>

</situation>

<serviceLocal>

<id>132</id>

<description>Delivery Place Sample</description>

<country>Spain</country>

<city>Barcelona</city>

<street>Avinguda del Paral. lel, 188</street>

<active>true</active>

</servicelocal>

<origin>3</origin>

<hour>14:57</hour>

<date>2011-07-18</date>

<alternativeIdentifier>S</alternativeIdentifier>

<agent>

<id>5421</id>

<name>Fulano da Silva</name>

<active>false</active>

<alternativeIdentifier>id_alternativo</alternativeIdentifier>

<email>user@empresa.com</email>

<cellphoneIdd>55</cellphoneIdd>

<cellphoneStd>51</cellphoneStd>

<cellphone>347851488</cellphone>

<login>fulano</login>

<centerwebUser>true</centerwebUser>

<mobileUser>true</mobileUser>

<centerwebUserRole>D</centerwebUserRole>

</agent>

<observation>Tarefa criada via API uMov.me</observation>

<active>true</active>

<activitiesOrigin>4</activitiesOrigin>

<activities>

<activity id="10" link="/activity/10.xml" />

<activity id="11" link="/activity/11.xml" />

</activities>

<customFields>

<Nro_OS>9854</Nro_OS>

<Contato>Fulano de tal</Contato>

...

</customFields>

</schedule>

Observação: Somente na consulta de uma tarefa já criada, o sistema lista as atividades <activities> vinculadas a tarefa. E o sistema mostra todas as atividades vinculadas à tarefa, independente se foi executada ou não.

Busca de uma tarefa específica através do identificador alternativo

GET /CenterWeb/api/{$apiKey}/schedule/alternativeIdentifier/{$alternative identifier}.xml

Esta operação serve para buscar informações de uma tarefa do sistema. Veja o exemplo de retorno de uma entidade abaixo (considerando uma requisição feita em XML):

<schedule>

<id>895590</id>

<agent>

<id>36324</id>

<name>user</name>

<login>user</login>

<active>true</active>

<alternativeIdentifier>exemplo</alternativeIdentifier>

<validateClient>0</validateClient>

<centerwebUser>true</centerwebUser>

<centerwebUserRole>D</centerwebUserRole>

<mobileUser>true</mobileUser>

<biUser>true</biUser>

<biUserRole>0</biUserRole>

<inputWebAsAnotherUser>true</inputWebAsAnotherUser>

<observation/>

<country/>

<state/>

<city/>

<neighborhood/>

<streetType/>

<street/>

<streetComplement/>

<email>user@umov.me</email>

<exportStatus>false</exportStatus>

<viewServiceLocal>false</viewServiceLocal>

<lockLoginInChangeImei>false</lockLoginInChangeImei>

</agent>

<serviceLocal>

<id>1220192</id>

<description>local 1</description>

<active>true</active>

<alternativeIdentifier>loc1</alternativeIdentifier>

<corporateName>nenhuma</corporateName>

<country>brasil</country>

<state>rs</state>

<city>porto alegre</city>

<cityNeighborhood>são joão</cityNeighborhood>

<streetType/>

<street>paraná</street>

<streetNumber>2021</streetNumber>

<streetComplement/>

<zipCode/>

<email/>

<observation/>

<geoCoordinate>-30.0122751, -51.196928000000014</geoCoordinate>

<origin>1</origin>

</serviceLocal>

<date>2013-07-16</date>

<hour>17:16</hour>

<alternativeIdentifier>IdNuncaUsado</alternativeIdentifier>

<recreateTaskOnPda>false</recreateTaskOnPda>

<observation/>

<situation>

<id>30</id>

<description>Pendente de Envio para Campo</description>

</situation>

<origin>1</origin>

<executionHour/>

<exportSituation>0</exportSituation>

<active>true</active>

<activitiesOrigin>4</activitiesOrigin>

<executionStartTime/>

<executionEndTime/>

<ignoringCanceledOnQuery>false</ignoringCanceledOnQuery>

<customFields>

<Nro_OS>9854</Nro_OS>

<Contato>Fulano de tal</Contato>

...

</customFields>

</schedule>

Busca de tarefas por Custom Field

GET /CenterWeb/api/{$apiKey}/schedule/.xml?{$identificadorAlternativoCustomField}={$valor}

Esta operação serve para puxar tarefas com determinado valor em um custom Field. Segue abaixo um exemplo de retorno.

<result>

<resourceName>schedule</resourceName>

<size>17</size>

<entries>

<entry id="23123123" link="/schedule/23123123.xml"/>

<entry id="35345354" link="/schedule/35345354.xml"/>

<entry id="45645622" link="/schedule/45645622.xml"/>

<entry id="46456335" link="/schedule/46456335.xml"/>

</entries>

</result>

Inclusão de tarefas

POST /CenterWeb/api/{$apiKey}/schedule.xml

Esta operação serve para incluir uma tarefa 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 Tarefa para identificar os campos obrigatórios. Veja um exemplo da requisição com dados em XML:

<schedule>

<agent>

<id>5421*</id>

</agent>

<serviceLocal>

<id>132**</id>

</serviceLocal>

<image>

<imageUrlImport>http://www.testeimagem.jpg</imageUrlImport>

</image>

<activitiesOrigin>4</activitiesOrigin>

<date>2011-11-01</date>

<hour>08:00</hour>

<activityRelationship>

<activity>

<alternativeIdentifier>identifier***</alternativeIdentifier>

</activity>

<activity>

<alternativeIdentifier>identifier***</alternativeIdentifier>

</activity>

</activityRelationship>

<customFields>

<Nro_OS>9854</Nro_OS>

<Contato>Fulano de tal</Contato>

...

</customFields>

<scheduleType>

<id>254</id>

</scheduleType>

</schedule>

Neste caso, lendo o que está sendo pedido ao uMov.me é que seja criado uma Tarefa para o agente cujo id é 5421, utilizando o local de atendimento com o id 132. Além disto, está sendo dito que a tarefa em questão possuirá uma atividade associada manualmente (activitiesOrigin=4) com identificador alternativo identifier, que a data prevista para início é no dia 1° de Novembro do ano de 2011 a partir das 08hs da manhã.

*Este identificador interno é somente como exemplo. Você deve usar o agente cadastrado em seu sistemas através do http://center.umov.me/CenterWeb/agent

**Este identificador interno é somente como exemplo. Você deve usar o local cadastrado em seu sistemas através do http://center.umov.me/CenterWeb/serviceLocal

***Este identificador alternativo é somente como exemplo. Você deve usar o identificador alternativo da sua atividade cadastrada em seu sistemas através do http://center.umov.me/CenterWeb/activity

****Este identificador alternativo é somente como exemplo. Você deve usar o identificador alternativo de seu item cadastrado em seus sistema através do http://center.umov.me/CenterWeb/item

A vinculação de atividades nas tarefas também pode ser realizado a partir do ID interno da atividade:

<schedule>

<agent>

<id>5421*</id>

</agent>

<serviceLocal>

<id>132**</id>

</serviceLocal>

<image>

<imageUrlImport>http://www.testeimagem.jpg</imageUrlImport>

</image>

<activitiesOrigin>4</activitiesOrigin>

<date>2011-11-01</date>

<hour>08:00</hour>

<activityRelationship>

<activity>

<id>888</id>

</activity>

<activity>

<id>999</id>

</activity>

</activityRelationship>

<customFields>

<Nro_OS>9854</Nro_OS>

<Contato>Fulano de tal</Contato>

...

</customFields>

</schedule>

Atualização de tarefas

Ambas as operações abaixo permitem atualizar informações de uma tarefa utilizando ou o id interno ou o identificador alternativo. Assim é possível atualizar a tarefa enviando apenas os dados desejados conforme é demonstrado o xml de exemplo abaixo:

Utilizando id interno

POST /CenterWeb/api/{$apiKey}/schedule/{$id}.xml

Utilizando identificador alternativo

POST /CenterWeb/api/{$apiKey}/schedule/alternativeIdentifier/{$alternativeIdentifier}.xml

<schedule>

<hour>09:00</hour>

</schedule>

Inclusão ou atualização de uma tarefa através de identificadores alternativos

POST /CenterWeb/api/{$apiKey}/schedule.xml

Esta operação serve para incluir ou atualizar uma tarefa no sistema, informando o local ou pessoa através do identificador alternativo. Veja um exemplo da requisição com dados em XML:

<schedule>

<agent>

<alternativeIdentifier>AGENTE X</alternativeIdentifier>

</agent>

<serviceLocal>

<alternativeIdentifier>LOCAL Y</alternativeIdentifier>

</serviceLocal>

<image>

<imageUrlImport>http://www.testeimagem.jpg</imageUrlImport>

</image>

<activitiesOrigin>4</activitiesOrigin>

<date>2011-11-01</date>

<hour>08:00</hour>

<activityRelationship>

<activity>

<alternativeIdentifier>ATIVIDADE ABC</alternativeIdentifier>

</activity>

</activityRelationship>

<customFields>

<Nro_OS>9854</Nro_OS>

<Contato>Fulano de tal</Contato>

...

</customFields>

</schedule>

Observação: Ao vincular um local ou pessoa informando o identificador alternativo, o sistema fará a vinculação quando existir apenas um registro para o cadastro com o identificador alternativo. Caso possuir mais de um registro com o mesmo identificador alternativo, o sistema retornará uma mensagem de erro.

Cancelamento de tarefas

POST /CenterWeb/api/{$apiKey}/schedule/{$id}.xml

Para cancelar uma tarefa, basta realizar uma atualização comum informando a nova situação da tarefa. (70 = Cancelada). São passíveis de cancelamento apenas tarefas uja situação for diferente de 50 (retornada de campo - executada) e 70 (cancelada).

<schedule>

<situation><id>70</id></situation>

</schedule>

Inclusão e atualização de tarefas em lote

POST /CenterWeb/api/{$apiKey}/batch/schedules.xml

Este recurso permite fazer a criação e atualização de tarefas em lote, sem a necessidade de fazer inúmeras requisições para a API.

<schedules>

<schedule>

<agent>

<alternativeIdentifier>Agente X</alternativeIdentifier>

</agent>

<serviceLocal>

<alternativeIdentifier>Local Y</alternativeIdentifier>

</serviceLocal>

<image>

<imageUrlImport>http://www.testeimagem.jpg</imageUrlImport>

</image>

<alternativeIdentifier>alternative_identifier1</alternativeIdentifier>

<activitiesOrigin>4</activitiesOrigin>

<date>2015-12-30</date>

<hour>08:00</hour>

<activityRelationship>

<activity>

<alternativeIdentifier>Atividade XYZ</alternativeIdentifier>

</activity>

</activityRelationship>

<customFields>

<Nro_OS>99999</Nro_OS>

<Contato>Fulano de tal</Contato>

...

</customFields>

</schedule>

<schedule>

<agent>

<alternativeIdentifier>Agente X</alternativeIdentifier>

</agent>

<serviceLocal>

<alternativeIdentifier>Local ABC</alternativeIdentifier>

</serviceLocal>

<image>

<imageUrlImport>http://www.testeimagem.jpg</imageUrlImport>

</image>

<alternativeIdentifier>alternative_identifier2</alternativeIdentifier>

<activitiesOrigin>4</activitiesOrigin>

<date>2015-12-30</date>

<hour>10:00</hour>

<activityRelationship>

<activity>

<alternativeIdentifier>Atividade XYZ</alternativeIdentifier>

</activity>

</activityRelationship>

<customFields>

<Nro_OS>99999</Nro_OS>

<Contato>Fulano de tal</Contato>

...

</customFields>

</schedule>

<schedule>

<agent>

<alternativeIdentifier>Agente X</alternativeIdentifier>

</agent>

<serviceLocal>

<alternativeIdentifier>Local XY</alternativeIdentifier>

</serviceLocal>

<image>

<imageUrlImport>http://www.testeimagem.jpg</imageUrlImport>

</image>

<alternativeIdentifier>alternative_identifier3</alternativeIdentifier>

<activitiesOrigin>4</activitiesOrigin>

<date>2015-12-30</date>

<hour>14:00</hour>

<activityRelationship>

<activity>

<alternativeIdentifier>Atividade XYZ</alternativeIdentifier>

</activity>

</activityRelationship>

<customFields>

<Nro_OS>99999</Nro_OS>

<Contato>Fulano de tal</Contato>

...

</customFields>

</schedule>

</schedules>

IMPORTANTE: O sistema possui um limite onde permite até 50 tarefas na mesma requisição de inclusão em lote. Isso garante que o sistema opere normalmente sem requisições maiores que podem afetar outros serviços.

A seção <schedule></schedule> representa cada tarefa a ser inserida e pode ser replicada quantas vezes forem necessárias.

Caso algum erro ocorra, toda a operação será abortada e nenhuma tarefa será inserida.

Como retorno a esta chamada o sistema apresenta o link de acesso para cada tarefa criada. No link é mostrado o ID interno e o identificador alternativo de cada registro a fim de identificar melhor qual o ID gerado para cada tarefa criada.

Ex:

<result>

<resourceName>schedules</resourceName>

<size>2</size>

<entries>

<entry id="1401792" alternativeIdentifier="alternative_identifier1" link="/schedule/1401792.xml" />

<entry id="1401793" alternativeIdentifier="alternative_identifier2" link="/schedule/1401793.xml" />

<entry id="1401793" alternativeIdentifier="alternative_identifier3" link="/schedule/1401794.xml" />

</entries>

</result>

Operações usando HTTP POST

Ao criar ou atualizar um agente você precisa em sua requisição POST identificar os dados do agente utilizando um parâmetro com o nome data. Segue um exemplo disparando a requisição a partir de um formulário HTML:

<html>

<form method="POST" action="http://api.umov.me/CenterWeb/api/{$apiKey}/schedule/{$id}.xml">

<input type="text" name="data" value="<schedule><hour>09:00</hour></schedule>" />

<input type="submit" />

</form>

</html>

Tarefas e relacionados (Schedule (Tarefas))