O documento fornece uma introdução à API do uMov.me, explicando como ela funciona através de requisições HTTP, XML e conceitos REST para permitir a integração e automação de tarefas no sistema. A API permite pesquisar, visualizar e manter dados como agentes e itens, bem como realizar outras operações avançadas.

1. UMOV.ME API
Do básico ao avançado
@nbluis
http://about.me/nbluis

2. O QUE É ?
• Maneira
fácil (para desenvolvedores) de realizar
integração online com uMov.me
• Permite
pesquisar, visualizar e manter praticamente
todos os cadastros do sistema
• Permite
ainda realizar algumas operações avançadas
dentro do sistema

3. O QUE NÃO É ?
• Uma
forma diferente de usuários operarem o sistema
• Um
serviço a ser consumido por usuários finais (Agentes,
Vendedores, etc.)
• Solução
ideal para qualquer tipo de integração com
uMov.me

4. COMO FUNCIONA ?
• Através
de requisições HTTP
• Trafega
informação por XML
• Utiliza
conceitos de REST

5. COMO FUNCIONA ?
• Através
de requisições HTTP
• Trafega
informação por XML
• Utiliza
conceitos de REST

6. ENTENDENDO HTTP
HTTP é o protocolo padrão utilizado na internet
É através de HTTP que nosso navegador acessa
qualquer site na internet

7. ENTENDENDO HTTP
Cliente
Requisição / R
equest
http://api.umo
v.me
nse
sposta / Respo
Re
sta
eúdo da respo
Cont
Servidor

8. ENTENDENDO HTTP
A requisição é composta por 4 informações básicas
Método (Method)
Endereço (URL)
Conteúdo (Content/Payload)
Cabeçalhos adicionais (Headers)

9. ENTENDENDO HTTP
A resposta é composta por 4 informações básicas
Status code (Código de status de sucesso ou erro)
Resposta
Cabeçalhos adicionais (Headers)

10. PRINCIPAIS MÉTODOS HTTP
• GET
- Busca uma informação do servidor
• POST
- Atualiza uma informação no servidor
• Existem
outros (PUT / HEAD / DELETE) mas não são
utilizados por nossa api.

11. EXEMPLO DE REQUISIÇÃO
•
•
Método: GET
URL: http://google.com
•
Conteúdo: NENHUM
•
Cabeçalhos: NENHUM
•
Método: POST
•
URL: http://google.com/createUser
•
Conteúdo:
userName=Eduardo&password=senha
•
Cabeçalhos: NENHUM

12. COMO FUNCIONA ?
• Através
de requisições HTTP
• Trafega
informação por XML
• Utiliza
conceitos de REST

13. ENTENDENDO XML
•É
uma linguagem de marcação
• Baseado
• Facil
em tags
de representar estruturas complexas utilizando
texto
• Todo
mundo conhece

14. EXEMPLO DE XML
<carro>
<marca>Fiat</marca>
<modelo>Uno</modelo>
<ano>2013</ano>
<portas>2</portas>
<utilitarios>
<utilitario nome=”Vidro Elétrico”/>
</utilitarios>
</carro>

15. COMO FUNCIONA ?
• Através
de requisições HTTP
• Trafega
informação por XML
• Utiliza
conceitos de REST

16. ENTENDENDO REST
Um serviço REST nada mais é que utilizar o que já
aprendemos sobre HTTP para manusear este serviço.

17. EXEMPLO REST
Listar usuários:
Incluir usuário:
GET: http://servico.com/user
Resposta:
<usuarios>
<usuario>123</usuario>
</usuarios>
POST: http://servico.com/user
<usuario>
<nome>Novo usuário</nome>
</usuarios>
Visualizar usuário:
Alterar usuário:
GET: http://servico.com/user/123
Resposta:
<usuario>
<id>123</id>
<nome>Eduardo</nome>
</usuarios>
POST: http://servico.com/user/123
<usuario>
<nome>Novo nome</nome>
</usuarios>

18. ENTRANDO NO UMOV.ME
Agora que entendemos um mínimo sobre APIs vamos
ao uMov.me
No uMov.me é necessário utilizar um TOKEN de acesso
para realizar a autenticação na API

19. CRIANDO UM TOKEN
Para criar um TOKEN para um ambiente basta acessar a
tela de “Criação > Parâmetros” no uMov.Center

20. EXEMPLO DE ACESSO A API
GET: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent.xml

21. EXEMPLO DE ACESSO A API
GET: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent.xml
Método HTTP

22. EXEMPLO DE ACESSO A API
GET: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent.xml
URL Base

23. EXEMPLO DE ACESSO A API
GET: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent.xml
Token de acesso

24. EXEMPLO DE ACESSO A API
GET: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent.xml
Recurso acessado

25. EXEMPLO DE ACESSO A API
GET: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent.xml
Formato
(apenas xml)

26. EXEMPLO DE ACESSO A API
A maioria das operações da API segue um modelo
muito parecido de cadastro que será mostrado a seguir.
Todos os recursos disponíveis da API uMov.me está
disponível na KB: http://kb.umov.me/?q=pt-br/node/914

27. EXEMPLO DE ACESSO A API
Exemplo utilizando agente como recurso
Listar agentes:
GET: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent.xml
Visualizar um agente:
GET: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent/123.xml
Incluir um agente:
POST: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent.xml
Alterar um agente:
POST: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent/123.xml

28. EXEMPLO DE ACESSO A API
Fique atento aos pontos destacados em cada operação

29. EXEMPLO DE ACESSO A API
Listar agentes:
GET: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent.xml
Visualizar um agente:
GET: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent/123.xml
Incluir um agente:
POST: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent.xml
Alterar um agente:
POST: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent/123.xml

30. EXEMPLO DE ACESSO A API
Para visualizar ou alterar um agente específico
precisamos informar qual agente queremos, utilizando
o seu id.
Visualizar um agente:
GET: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent/123.xml
Alterar um agente:
POST: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent/123.xml

31. EXEMPLO DE ACESSO A API
Para a maioria das demais operações basta alterar o
recurso na URL

32. EXEMPLO DE ACESSO A API
Exemplo utilizando item como recurso
Listar itens:
GET: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/item.xml
Visualizar um item:
GET: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/item/123.xml
Incluir um item:
POST: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/item.xml
Alterar um item:
POST: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/item/123.xml

33. EXEMPLOS ADICIONAIS
Os exemplos a seguir aprofundam um pouco mais cada
operação da API.
A maioria dos demais recursos da API podem ser
operados utilizando o mesmo formato ao que está
sendo mostrado.

34. EXEMPLO DE PESQUISA
Listar agentes:
GET: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent.xml
Resposta:
<result>
<resourceName>agent</resourceName>
<size>2</size>
<entries>
<entry id="1" link="/agent/1.xml"/>
<entry id="2" link="/agent/2.xml"/>
</entries>
</result>
Nome do recurso pesquisado
Quantidade de registros retornados
Link para acesso a visualização de cada registro
Identificador interno de cada registro

35. APROFUDANDO A
PESQUISA
A pesquisa permite também que filtremos informações
por qualquer campo da entidade sendo pesquisada
através da URL
Exemplo
GET: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent.xml?active=true

36. APROFUDANDO A
PESQUISA
Permite ainda pesquisas por campos de entidades
relacionadas ao recurso
Exemplo
GET: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/
agent.xml?agentType.description=Vendedores

37. LIMITE DA PESQUISA
Independente dos filtros informados, o retorno sempre
está sujeito a limitação de registros retornados
Por padrão este limite é de 20 registros

38. EXEMPLO DE VISUALIZAÇÃO
Visualizar um agente:
GET: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent/123.xml
Resposta:
<agent>
<id>123</id>
<name>Joao da Silva</name>
<login>joaosilva</login>
<agentType>
<id>1234</id>
<description>Vendedor</description>
</agentType>
<active>false</active>
<alternativeIdentifier/>
....
</agent>
XML apresentando todos os campos visíveis do recurso

39. EXEMPLO DE INCLUSÃO
Incluir um agente:
POST: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent.xml
Envio:
<agent>
<active>true</active>
<agentType><id>1234</id></agentType>
<login>fulano</login>
<name>Fulano da Silva</name>
<password>minha_senha_nao_criptografada</password>
<email>fulano@empresa.com</email>
<centerwebUser>true</centerwebUser>
<mobileUser>true</mobileUser>
<centerwebUserRole>D</centerwebUserRole>
</agent>
Resposta:
<result>
<resourceName>agent</resourceName>
<resourceId>1234</resourceId>
<link>/agent/1234.xml</link>
</result>
Nome do recurso operado
Identificador do novo agente
Dados do agente a ser incluso
Link para acesso ao novo agente

40. EXEMPLO DE ALTERAÇÃO
Alterar um agente:
POST: http://api.umov.me/CenterWeb/api/123exxxxxxxxx/agent/123.xml
Envio:
<agent>
<name>Novo Nome</name>
</agent>
Resposta:
<result>
<resourceName>agent</resourceName>
<resourceId>1234</resourceId>
<link>/agent/1234.xml</link>
</result>
Nome do recurso operado
Dados do agente a ser alterado
(apenas os dados a serem modificados)
Identificador do agente alterado
Link para acesso ao agente alterado

41. UTILIZANDO
IDENTIFICADOR
Todas as requisições básicas permitem operar os
recursos da API também pelo identificador alternativo
Nesse caso os XMLs não mudam, mudam apenas a
URL

42. EXEMPLO IDENTIFICADOR
ALTERNATIVO
O início da URL (http://api.umov.me/CenterWeb) foi omitida nos exemplos abaixo
Visualizar um agente:
GET: /123exxxxxxxxx/agent/alternativeIdentifier/123.xml
Alterar um agente:
POST: /123exxxxxxxxx/agent/alternativeIdentifier/123.xml

43. VISUALIZANDO ERROS
Sempre que ocorrer o erro em decorrência de uma
requisição, a mensagem será retornada permitindo um
melhor entendimento do problema

44. EXEMPLO DE ERRO
Retorno:
<result>
<statusCode>400</statusCode>
Código de erro http retornado
<errors>login: error.mandatory.field</errors>
Campo e mensagem de erro
<resourceName>agent</resourceName>
Recurso manipulado pela requisição
</result>

45. OBRIGADO
@nbluis
http://about.me/nbluis