Base de Conhecimento

Como a API é estruturada

A API do uMov.me é implementada sobre o protocolo HTTP/HTTPS usando verbos conhecidos do protocolo como GET e POST para realizar as requisições. Originalmente o formato suportado pela API é XML - eXtensible Markup Language. A API é baseada nos conceitos REST (Representational State Transfer). Neste sentido dizemos que a nossa API é inspirada em REST e respeita os aspectos mais significativos e restritivos da sua arquitetura, em particular a restrição de "interface uniforme".

Cada recurso disponibilizado pela API possui sua própria URL base e é manipulado de forma isolada.

Autenticação

Para ter acesso a API uMov.me, o ambiente em questão deve possuir uma chave de acesso da API gerada (token). Isto é feito através das configurações do ambiente, onde um desenvolvedor pode requisitar uma chave de acesso. Quem possuir esta chave terá o acesso aos dados do ambiente através das chamadas de API. Esta chave de acesso não deve ser publicada pelo cliente — ela é a segurança do cliente no acesso ao sistema através da API.

Como obter seu token

1.Via Center:

Vá nas configurações de API do seu ambiente:

Clique em "Gerar Token", o código gerado aparecerá no campo.

Mas lembre-se: ao clicar quando já houver um Token, este será substituído pelo novo, ou seja, se você possui já uma integração via API ela deixará de funcionar.

A chave é usada como parte das informações de uma dada requisição, exemplo:

https://api.umov.me/CenterWeb/api/4526e732f53e811be6f0678c4512c9bcea990/serviceLocal/5421.xml

Neste caso, o token 4526e732f53e811be6f0678c4512c9bcea990 foi o Token gerado, e é a chave de API dentro da requisição. Toda requisição deve ter a chave enviada.

2.Via API:

É possível também gerar ou recuperar o token através de uma requisição POST via API. A requisição a ser feita é:

https://api.umov.me/CenterWeb/api/token.xml

Exemplo da requisição com dados do XML:

<login>fulano</login>

<password>senhafulano</password>

<domain>ambiente</domain>

</apiToken>

Realizando requisições

Ao realizar uma requisição para a API uMov.me é necessário:

Indicar a chave de API;
O recurso de interesse
Opcionalmente se pode informar um identificador, no caso de requisições que desejam retornar um registro em específico.
O tipo de conteúdo que está sendo tratado, seja no envio ou no retorno de informação. Com relação ao tipo de conteúdo a API uMov.me trabalha com o formato XML.

GET https://api.umov.me/CenterWeb/api/4526e732f53e811be6f0678c4512c9bcea990/serviceLocal/5421.xml

A requisição acima é lida da seguinte forma: desejo retornar (GET) informações via API existente no ambiente uMov.me com chave de API "4526e732f53e811be6f0678c4512c9bcea990", sobre um local de atendimento (serviceLocal) específico, de código 5421, em formato XML.

Ainda é possível adicionar parâmetros nas requisições. Este tipo de funcionalidade é disponível nas requisições de consulta de registros. Para enviar parâmetros na requisição, é necessário adicionar parâmetros igual realizamos em uma requisição HTTP/HTTPS. Exemplo:

GET https://api.umov.me/CenterWeb/api/{$apiKey}/agent.xml?name=fulano&active=true

Esta requisição está pedindo todos os agentes disponíveis cujo nome tenha a palavra fulano presente (name=fulano) e que estejam ativos (active=true).

Respostas e alertas de erro

O método de envio POST pode ser usado para realizar uma inserção ou atualização. No caso de uma inserção, é retornado o código 201 (recurso criado) no caso de sucesso. No caso de uma atualização de recurso, é retornado o código 200 (recurso atualizado).

Veja um resumo dos status HTTP que a API pode retornar:

200 - um retorno ok para uma consulta (GET) ou operação de atualização de dados com sucesso;

201 - um retorno indicando a criação de um novo registro, usado para inserção de dados (requisições POST para inclusão de dados);

400 - request mal realizado, retornado quando o cliente executa uma chamada sem usar os parâmetros esperados por exemplo;

401 - não autorizado, normalmente quando a chave de API uMov.me não está correta;

404 - quando pesquisado por um registro indicando um id especifico, porém inexistente;

429 - foi realizado mais requestas que o permitido em um determinado período de tempo.

501 - para entidades não disponíveis via API;

504 - indica que o servido não conseguiu responder em tempo

Referência dos códigos HTTP: W3C HTTP/1.1 Status Code Definitions (http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html)

Para requisições de criação e atualização de um recurso com sucesso, será enviado uma mensagem ao usuário, informando o que foi criado/atualizado e sua respectiva URL, conforme o exemplo abaixo:

<resourceName>serviceLocal</resourceName>

</result>

Ao realizar buscas por um lista de recursos, será enviada ao usuário uma mensagem informando as seguintes informações:

Nome do recurso pesquisado;

Total de registros encontrados;

Lista de entradas contento o link para acesso de cada recurso encontrado;

<resourceName>serviceLocal</resourceName>

...

</result>

Paginação

Existe uma número máximo de registros que uma pesquisa pode retornar. Por padrão a API mostra apenas a primeira página com resultados da pesquisa. Para exibir os demais registros, é necessário paginar a pesquisa, informando o número da página que se deseja consultar. Para isso, deve-se adicionar o parâmetro 'paging.page' à requisição informando o número da página desejada:

GET https://api.umov.me/CenterWeb/api/{$apiKey}/schedule.xml?paging.page=5

Limites

Requisições simultâneas:

A API do uMov.me trabalha atualmente com um limite máximo de 4 conexões por segundo. Este bloqueio de conexões simultâneas ocorre baseado em um limite de requisições por IP e TOKEN.

Dado que um determinado IP(200.x.x.x) ou token(4526e732f53e811be6f0678c4512c9bcea990) realizar 6 chamadas de forma simultânea(no mesmo segundo) para a o uMov.me, então serão processadas apenas as cinco primeiras requisição observando a ordem de chegada. A sexta requisição será bloqueada!

Selecionando valores de um custom fields do tipo lista.

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

Basta declarar a tag alternativeIdentifier dentro do campo customizável e informar os valores separados por '|' (pipe).

ServiceLocal com campo de lista múltipla de status:

<description>Local</description>

</status>

</customFields>

Primeiros passos com a integração via API