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.
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
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
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
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