Pessoas e relacionados (Agent (Agente))
1. O que é e como funciona?
A API de Agent permite interagir com a parte "Quem?" do uMov.me.
2. Quando uso?
API utilizada para criação e atualização de pessoas.
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 pessoa.
- 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 pessoas
Busca por pista de agentes/pessoas
GET /CenterWeb/api/{$apiKey}/agent.xml
Se ainda preferir, 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}/agent.xml?agentType.description=Padrão
Esta requisição filtra todos os agentes com base na descrição do tipo de agente, sendo o tipo de agente padrão.
GET /CenterWeb/api/{$apiKey}/agent.xml?name=fulano&active=true
Esta requisição está pedindo a todos os agentes disponíveis cujo nome tenha a palavra fulano presente (name=fulano) e que estejam ativos (active=true). 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>agent</resourceName>
<size>2</size>
<entries>
<entry id="5421" link="/agent/5421.xml"/>
<entry id="5422" link="/agent/5422.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, o ID do registro no uMov.me e o link que pode ser usado para recuperar os dados específicos deste registro.
GET /CenterWeb/api/{$apiKey}/agent.xml?initialInsertDateTime=AAAA-MM-DD HH:MM:SS&finalInsertDateTime=AAAA-MM-DD HH:MM:SS
Esta requisição filtra todos os agentes que foram inseridos neste período de data e hora.
Busca de um agente/pessoa específica através do id interno
GET /CenterWeb/api/{$apiKey}/agent/{$id}.xml
Este recurso serve para puxar dados de um agente/pessoa específica do sistema. Veja o exemplo de retorno de uma entidade abaixo (considerando uma requisição feita em XML):
<agent>
<id>5421</id>
<name>Fulano da Silva</name>
<active>false</active>
<alternativeIdentifier>id_alternativo</alternativeIdentifier>
<observation>Observação</observation>
<agentType>
<id>10860</id>
<description>Padrão</description>
<alternativeIdentifier>tipoPessoaPadrao</alternativeIdentifier>
<active>true</active>
</agentType>
<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>
<lastGeoPosition>-28.098883,-048.675000</lastGeoPosition>
<customFields>
<CPF>000000000-00</CPF>
<Número_Funcionário>1512</Número_Funcionário>
...
<customFields>
</agent>
Busca de um agente/pessoa específica através do identificador alternativo
GET /CenterWeb/api/{$apiKey}/agent/alternativeIdentifier/{$alternativeIdentifier}.xml
Este recurso serve para buscar dados de um agente/pessoa específica através de seu identificador alternativo do sistema. Veja o exemplo de retorno de uma entidade abaixo (considerando uma requisição feita em XML):
<agent>
<id>5421</id>
<name>Fulano da Silva</name>
<active>false</active>
<alternativeIdentifier>id_alternativo</alternativeIdentifier>
<observation>Observação</observation>
<agentType>
<id>10860</id>
<description>Pdrão</description>
<alternativeIdentifier>tipoPessoaPadrao</alternativeIdentifier>
<active>true</active>
</agentType>
<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>
<customFields>
<CPF>000000000-00</CPF>
<Número_Funcionário>1512</Número_Funcionário>
...
<customFields>
</agent>
Inclusão de um agente/pessoa específica
POST /CenterWeb/api/{$apiKey}/agent.xml
Este recurso serve para incluir um agente/pessoa no sistema. Existe um mínimo de informações que o sistema espera receber para poder realizar a criação de uma nova pessoa no ambiente em questão. Confira a descrição do agente para identificar os campos obrigatórios. Veja um exemplo da requisição com dados em XML:
<agent>
<active>true</active>
<image>
<imageUrlImport>http://www.testeimagem.jpg</imageUrlImport>
</image>
<agentType><id>10860*</id></agentType>
<login>fulano</login>
<name>Fulano da Silva</name>
<password>minha_senha</password>
<email>fulano@empresa.com</email>
<alternativeIdentifier>33456745</alternativeIdentifier>
<centerwebUser>true</centerwebUser>
<mobileUser>true</mobileUser>
<centerwebUserRole>D</centerwebUserRole>
<accessRole><id>123</id> OU <alternativeIdentifier>33456745</alternativeIdentifier></accessRole>
<customFields>
<CPF>000000000-00</CPF>
<Número_Funcionário>1512</Número_Funcionário>
<tipos_pessoa>
<alternativeIdentifier>1</alternativeIdentifier>
<alternativeIdentifier>2</alternativeIdentifier>
</tipos_pessoa>
...
<customFields>
</agent>
Neste caso, lendo o que está sendo pedido ao uMov.me é que seja criado um agente com os campos obrigatórios preenchidos (login, senha, nome e tipo de agente) e ainda, está sendo dito que o agente em questão está sendo criado ativo, com o emailfulano@empresa.com, e que o identificador dele no sistema de origem é 33456745 e que este usuário tem acesso ao center e ao celular para logar. E que no center, este agente/pessoa tem o perfil de Desenvolvedor (D).
*Este identificador interno é somente como exemplo. Você deve usar o tipo de agente cadastrado em seu sistemas através do http://center.umov.me/CenterWeb/agentType
Atualização de um agente/pessoa específica
Ambas as operações abaixo fazem com que os dados de um agente possam ser modificados no sistema. Desta forma você consegue atualizar informações isoladas de um agente utilizando ou o id interno ou o identificador alternativo. No xml abaixo é demonstrado a alteração de apenas de algumas informações.
Utilizando id interno:
POST /CenterWeb/api/{$apiKey}/agent/{$id}.xml
Utilizando identificador alternativo:
POST /CenterWeb/api/{$apiKey}/agent/alternativeIdentifier/{$alternativeIdentifier}.xml
<agent>
<name>Agente001</name>
</agent>
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, onde você precisa trocar {$apiKey} pela chave da sua API e {$id} pelo código do objeto que está sendo modificado. Neste exemplo estamos modificando o nome do agente para Agente001. Veja a base do form HTML.
<html>
<form method="POST" action="http://api.umov.me/CenterWeb/api/{$apiKey}/agent/{$id}.xml">
<input type="text" name="data" value="<agent><name>Agente001</name></agent>" />
<input type="submit" />
</form>
</html>