API
uMov.me
Este documento descreve os aspectos gerais da API uMov.me para integração com outros
sistemas. Aqui são tratadas questões como autenticação, padrões de requisições e respostas
bem como referência para informações específicas dos recursos disponibilizados pela API.
Sumário
Como nossa API está estruturada
Autenticação
Gerar Token usando o Center
Gerar Token usando a API
Validação de usuários
Realizando requisições
Operações Disponíveis
Busca Simples Por Identificador
Busca Por Lista de Recursos
Criação de Novos Recursos
Atualização de Recursos
Paginação
Limites
Requisições simultâneas
Operações usando HTTP POST
ActivityHistory (Histórico de Execução de Atividades)
Descrição de Histórico
Busca por Lista de Históricos
Busca de histórico completo específico (com todos os dados do histórico)
Busca de um histórico específico
Busca de um item de histórico específico
Descrição de Item de Histórico
Atualização de histórico (Marcar como Exportado)
Inclusão de histórico
Callback Para Históricos Retornados
AppVersion (Versão do Aplicativo)
Descrição de uma appVersion
Descrição de uma app
Consultar versões disponíveis de um aplicativo
Consultar uma versão específica de um aplicativo
Agendamento de atualização da versão de um aplicativo
Activity (Atividade)
Descrição de uma Atividade
Busca por Lista de Atividades
Busca por Atividade Específica
Usando identificador interno
Usando identificador alternativo
Section (Seção)
Descrição de uma Seção
Busca Por Lista de Seções
Busca de uma Seção
Usando Identificador Interno
Usando Identificador Alternativo
Section Field (Campo da Seção)
Descrição de um Campo da Seção
Busca por Lista de Campos na Seção
Busca de um Campo na Seção
Usando Identificador Interno
Usando Identificador Alternativo
Section SubGroup (Subgrupo da Seção)
Descrição de um Subgrupo da Seção
Inserir subgrupo na seção
Busca de um Subgrupo da Seção
Usando Identificador Interno
Remoção de um Subgrupo da Seção em Específico
Inserir Subgrupos em Lote na Seção
Math Expressions (Fórmulas de Valor)
Descrição de uma Fórmula de Valor
Busca por Lista de Fórmulas de Valor
Busca de uma Fórmula de Valor
Usando identificador Interno
Logical Expressions (Fórmulas de Validação)
Descrição de uma Fórmula de Valor
Busca por Lista de Fórmulas de Validação
Busca de uma Fórmula de Validação
Usando Identificador Interno
Auditing (Auditoria)
Descrição de um Registro de Auditoria
Busca Por Lista de Auditoria
Busca Por uma Auditoria
Usando Identificador Interno
Descrição de um Valor da Auditoria
Busca Por uma Valor de Auditoria
Usando Identificador Interno
Busca Hierárquica da Auditoria de um Histórico
Atualização dos Dados do Contrato
Descrição das Informações do Contrato no uMov.me
Atualização dos Dados do Contrato
Criação/Cópia de Ambiente
Descrição de um Workspace/Ambiente
Criação/Copia de Workspace/Ambiente
Custom Entity (Cadastro Customizável)
Descrição de um Cadastro Customizável
Busca Por Lista de Cadastros Customizáveis
Busca de um Cadastro Customizável específico
Descrição de um Registro do Cadastro Customizável
Busca Por Lista de Registros do Cadastro Customizável
Busca de um Registro do Cadastro Customizável específico
Inclusão de um Registro do Cadastro Customizável
Inclusão em Lote de Registro de Cadastro Customizável
Custom Field / Custom Field Value (Campo Customizável / Valor Campo Customizável)
Descrição de um Custom Field
Busca Por Lista de Campos Customizáveis
Busca de um Campo Customizável
Usando Identificador Interno
Usando Identificador Alternativo
Descrição de um Custom Field Value
Inclusão/Alteração de Valores de Campos Customizáveis
Usando Identificador Interno
Usando o Identificador Alternativo:
Inclusão/Alteração em lote de Valores de Campos Customizáveis
Inclusão/Alteração de Valores no formato XML de Campos Customizáveis I
ExportLayout(Modelo de exportação)
Busca por lista de modelo de exportação
Busca por um modelo de exportação específico utilizando ID
GeoCoordinate (GeoCoordenadas)
Descrição de uma GeoCoordenada
Busca por lista de GeoCoordenadas
Busca por uma GeoCoordenada em específico
ImportFiles (Agendamento de importação de arquivos)
Agendamento de importação de arquivos
ImportLayout(Modelo de Importação)
Descrição de um Modelo de Importação
Descrição de um Campo do Modelo de Importação
Busca por lista de modelo de importação
Busca por um modelo de importação específico utilizando ID
Busca de um modelo de importação por entidade
Relação de Item
Group (Grupo)
Descrição de um Grupo
Busca por lista de Grupos
Busca por um Grupo específico
Inclusão de um Grupo
Atualização de um Grupo específico
Busca por um Grupo específico
Item (Item)
Descrição de um Item
Busca por lista de Itens
Busca por um Item específico
Inclusão de um Item
Atualização de um Item específico
Utilizando id interno
Utilizando identificador alternativo
Inclusão de itens em lote
Busca por um Item específico através do identificador alternativo
ItemCategory (Categoria de Item)
Descrição de uma Categoria de Item
Busca por lista de Categoria de Item
Busca por uma Categoria de Item específica
Inclusão de uma Categoria de Item
Atualização de uma Categoria de Item específica
Busca por uma Categoria de Item específica através do identificador alternativo
SectionItem (Item de Seção)
Descrição de um Item de Seção
Busca por lista de Itens de Seção
Busca por um Item de Seção específico
Inclusão de um Item de Seção
Atualização de um Item de Seção específico
SubGroup (Subgrupo)
Descrição de um Subgrupo
Busca por lista de Subgrupos
Busca por um Subgrupo específico
Inclusão de um Subgrupo
Atualização de um Subgrupo
Usando Identificador Interno
Usando Identificador Alternativo
Busca por um Subgrupo específico através do identificador alternativo
Mix de Produtos
Busca por Lista de Tipo de Mix de Produtos
Busca por Lista de Mix de Produtos
Busca por Lista de Itens de Mix de Produtos
Busca por Mix / Itens de Mix / Tipo de Mix de Produto
Usando Identificador Interno
Usando Identificador Alternativo
Descrição de um Tipo de Mix
Descrição de um Mix de Produtos
Descrição de um Item do Mix de Produtos
Tipo de Mix (MixType)
Descrição de um Tipo de Mix
Inclusão de um tipo de mix
Buscar todos os registros de tipo de mix
Buscar um registro específico de tipo de mix
Mix
Descrição de um Mix
Inclusão de um mix
Buscar todos os registros de mix
Buscar um Registro de Mix
Itens do Mix (Mix Product)
Descrição de um Item de Mix
Inclusão de um item do mix
Busca por Lista de Registros de Itens do Mix
Buscar por Lista de Produtos de um Mix
Buscar um registro específico de itens do mix
Relação de Locais
ServiceLocal (Local de Atendimento)
Descrição de um Local de Atendimento
Busca Por Lista de Locais de Atendimento
Busca de um Local de Atendimento específico
Inclusão de um Local de Atendimento
Atualização de um Local de Atendimento
Usando Identificador Interno
Usando Identificador Alternativo
ServiceLocal Activity (Atividades dos Locais)
Inclusão de atividades dos locais em lote
Remoção de uma atividade de Local em específico
Usando Identificador Alternativo:
ServiceLocalClassification (Classificação de local de atendimento)
Descrição de um Classificação de local de atendimento
Busca por lista de Classificação de local de atendimento
Busca por um Classificação de local de atendimento
Inclusão de um Classificação de local de atendimento
Atualização de um Classificação de local de atendimento específico
Busca por Classificação de Local de Atendimento
Usando Identificador Alternativo
ServiceLocalType(Tipo de Local de atendimento)
Descrição de um Tipo de local de atendimento
Busca por lista de Tipo de local de atendimento
Inclusão de um Tipo de local de atendimento
Atualização de um Tipo de Local de Atendimento
Usando Identificador Interno
Usando Identificador Alternativo
Busca por Tipo de Local de Atendimento
Usando Identificador Interno
Usando Identificador Alterantivo
Local3Dimension (Grupo de local de atendimento)
Descrição de um Grupo de local de atendimento
Busca por lista de Grupo de local de atendimento
Busca por Grupo de Local de Atendimento
Usando Identificador Interno
Usando Identificadot alternativo
Inclusão de um Grupo de local de atendimento
Atualização de um Grupo de local de atendimento específico
Busca por Grupo de Local de Atendimento
Usando Identificador Interno
Usando Identificador Alternativo
RELACAO DE PESSOAS
Agent (Agente)
Descrição de um Agente/Pessoa
Busca por Lista de Agentes/Pessoas
Busca de um Agente/Pessoa específica
Inclusão de um Agente/Pessoa específica
Atualização de um Agente/Pessoa especifíca
Usando Identificador Interno
Usando Identificador Alternativo
Busca por Agente/Pessoa
Usando Identificador Interno
Usando Identificador Alternativo
Agent Activity (Atividades dos Agentes)
Inclusão de atividades dos agentes em lote
AgentType (Tipo de Agente)
Descrição de um Tipo de Agente
Busca por lista de Tipo de Agente
Busca por um Tipo de Agente específico
Inclusão de um Tipo de Agente
Atualização de um Tipo de Agente
Usando Identificador Interno
Usando Identificaor Alternativo
Busca por um Tipo de Agente
Usando Identificador Interno
Usando Identificador Alternativo
SmsRequest (Envio de SMS)
Descrição de um SmsRequest
Inclusão de um SmsRequest
Team(Equipe)
Descrição de uma Equipe
Busca Por Lista de Equipes
Busca por uma Equipe
Usando Identificador Interno
Usando Identificador Alternativo
Inclusão de uma Equipe
Atualização de uma Equipe
Inclusão de uma pessoa em uma equipe
Remoção de uma pessoa de uma equipe
Consulta de uma pessoa em uma equipe
TeamType(Tipo de Equipe)
Descrição de um Tipo de Equipe
Busca Por Lista de Tipos de Equipe
Busca de um Tipo de Equipe
Inclusão de um Tipo de Equipe
Atualização de um Tipo de Equipe
RELACAO DE TAREFAS
Schedule (Tarefas)
Descrição de uma Tarefa
Busca Por Lista de Tarefas
Busca de uma tarefa
Usando Identificador Interno
Usando Identificador Alternativo
Inclusão de uma Tarefa
Atualização de uma Tarefa
Utilizando Identificador Interno
Utilizando Identificador Alternativo
Inclusão ou atualização de uma tarefa com identificadores alternativos
Cancelamento de uma tarefa
Schedule Item (Itens das Tarefas)
Inclusão de itens de tarefa em lote
Busca Por Lista de Tarefas
Busca por um Item de Tarefa em específico
Remoção de um Item de Tarefa em específico
Usando Identificador Interno
Usando Identificador Alternativo:
Envio Notificação Push
Criação de notificação
Envio de Mensagens
Criação da Mensagem
Como nossa API está 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. 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.
Gerar Token usando o Center
Caso o cliente tenha interesse em criar ou "reiniciar" esta chave, pode fazer isto pelo menu
Gestão > Integração > API
.
A chave é usada como parte das informações de uma dada requisição, exemplo:
https://api.umov.me/CenterWeb/api/
4526e732f53e811be6f0678c4512c9bcea990
/serviceLocal/5421.xmlNeste caso, o token
4526e732f53e811be6f0678c4512c9bcea990
é a chave de API dentro da
requisição. Toda requisição deve ter a chave enviada.
Gerar Token usando a 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 é:
URL:
https://api.umov.me/CenterWeb/api/
token.xml
Exemplo da requisição com dados do XML:
<apiToken> <login>fulano</login> <password>senhafulano</password> <domain>ambiente</domain> </apiToken>Validação de usuários
Através da API do uMov.me também é possível validar se um determinado usuário é valido
através de uma requisição POST via API. A requisição a ser feita é:
URL:
https://api.umov.me/CenterWeb/api/authentication.xml
Exemplo da requisição com dados do XML:
<authentication> <login>fulano</login> <password>senhafulano</password> <domain>ambiente</domain> </authentication>Possiveis códigos de retorno:
● 200: Usuário autorizado
● 401: Usuário não autorizado
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/...
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=trueEsta requisição está pedindo 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!
Busca Simples Por Identificador
GET https://api.umov.me/CenterWeb/api/{chave_api}/{nome_recurso}/{identificador_recurso}.xml
Busca Por Lista de Recursos
GET
https://api.umov.me/CenterWeb/api/{chave_api}/{nome_recurso}.{formato}?{parametro1}={valor1}&{p arametro2}={valor2}...
Criação de Novos Recursos
POST https://api.umov.me/{chave_api}/{nome_recurso}.{formato}
Atualização de Recursos
POST https://api.umov.me/CenterWeb/api/{chave_api}/{nome_recurso}/{identificador_recurso}.{formato}
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;
● 501 para entidades não disponiveis via API;
Referência dos códigos HTTP: W3C HTTP/1.1 Status Code Definitions
(
http://www.w3.org/Protocols/rfc2616/rfc2616sec10.html
)
Para requisições de criação e atualização de um recurso com sucesso, será enviado uma
mensagem ao usuário conforme o exemplo abaixo:
<result> <resourceName>serviceLocal</resourceName> <resourceId>5421</resourceId> <link>/serviceLocal/5421.xml</link> </result>
Ao realizar buscas por uma 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
<result> <resourceName>serviceLocal</resourceName> <size>N</size> <entries> <entry id="5421" link="/serviceLocal/5421.xml"/> ... <entries> </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, devese 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 5 conexões por segundo
.
Este bloqueio de conexões simultâneas ocorre baseado em um limite de requisições por IP e
TOKEN. Exemplificando:
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 cindo primeiras requisição observando a ordem de chegada. A sexta
requisição será bloqueada!
Operações usando HTTP POST
Ao atualizar um histórico você precisa em sua requisição POST identificar os dados do histórico
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 status do histórico para exportado. Veja a
base do form HTML.
<html> <form method="POST" action="http://api.umov.me/CenterWeb/api/{$apiKey}/activityHistory/{$id}.xml"> <input type="text" name="data" value="<activityHistory><executionExportStatus>true</executionExportStatus></activityHistory>" /> <input type="submit" /> </form> </html>Perguntas Frequentes!
●A API uMov.me não suporta outros formatos?
●Existe alguma aplicação demo, ou algum cliente da API uMov.me para que sirva
de exemplo?
Entre em contato conosco para saber do nosso roadmap!
ActivityHistory (Histórico de Execução de Atividades)
A API de ActivityHistory é responsável por retornar os dados de execução das tarefas de
campo. Ela é a forma como o sistema integrado ao uMov.me consegue saber o que aconteceu
em campo e poder assim dar prosseguimento aos processos de negócio envolvidos!
Descrição de Histórico
Campo Valor Tamanho Obrigatório Descrição
activity Não Dados relacionados à atividade.
initialStartTimeOnSystem texto 19 Não Data de inico da execução da atividade no sistema. Formato (yyyymmdd HH:mm:ss) 24hs.
id numérico 10 Não Identificador interno de histórico de execução de atividade no uMov.me
schedule
Não
Dados relacionados à tarefa
endFinishTimeOnS
ystem
texto
19
Não
Data final de execução da atividade.
Formato (yyyymmdd HH:mm:ss)
24hs.
status
true/fal
se
Não
Indica se o histórico está ativo ou
inativo, válido ou não válido.
Busca por Lista de Históricos
GET /CenterWeb/api/{$apiKey}/activityHistory.xml
Este recurso permite fazer a busca de históricos de um determinado ambiente. É permitido que
você adicione alguns parâmetros na requisição.
Os parâmetros são os seguintes:
● schedule
: pesquisar por uma determinada tarefa
GET /CenterWeb/api/{$apiKey}/activityHistory.xml?schedule=002
● Atividades iniciados entre 20111001 00:00:00 e 20111001 23:59:59
/CenterWeb/api/{$apiKey}/activityHistory.xml?initialStartTimeOnSystem=20111001%2008:00: 00&endStartTimeOnSystem=20111001%2023:59:00:00
● Atividades finalizadas entre 20111101 00:00:00 e 20111101 23:59:59
GET /CenterWeb/api/{$apiKey}/activityHistory.xml?endStartTimeOnSystem=20111101%2008:00:00&endFini shTimeOnSystem=20111101%2023:59:00:00● Atividades executadas entre 20111001 00:00:00 e 20111101 23:59:59
GET /CenterWeb/api/{$apiKey}/activityHistory.xml?initialStartTimeOnSystem=20111001%2008:00:00&endFi nishTimeOnSystem=20111101%2023:59:00:00● Atividades filtrando os históricos através de atributos das entidades vinculadas
GET /CenterWeb/api/{$apiKey}/activityHistory.xml?activity.captureGPS=true&schedule.alternativeIdentifier=t esteRealizar pesquisas de histórico de execução de atividades utilizando parâmetros pela API
uMov.me é simples assim. Veja um exemplo, do resultado de uma requisição que foi feita em
XML:
<result> <resourceName>activityHistory</resourceName> <size>1</size> <entries> <entry id="100" link="/activityHistory/100.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 histórico completo específico (com todos os dados do histórico)
GET /CenterWeb/api/{$apiKey}/activityHistoryHierarchical/{$id}.xml
Esta operação serve para puxar informações de um histórico de execução de atividade do
sistema de forma completa. Todos os dados da tarefa e dados coletados são retornadas nessa
requisição. Veja o exemplo de retorno de uma entidade abaixo (considerando uma requisição
feita em XML):
<activityHistory>
<id>445</id> <startTimeOnSystem>20101005 19:30:16</startTimeOnSystem> <finishTimeOnSystem>20101005 19:30:36</finishTimeOnSystem> <dataSource>0</dataSource> <status>true</status> <executionExportStatus>false</executionExportStatus> <biExportStatus>false</biExportStatus> <numberPicturesTaken>2</numberPicturesTaken> <numberPicturesReceived>1</numberPicturesReceived> <activity> <id>9</id> <description>Entrega Total Realizada</description> <alternativeIdentifier /> <displayOrder>1</displayOrder> <minimumAmountPics>0</minimumAmountPics> <maximumAmountPics>2</maximumAmountPics> <active>true</active> <comunicationType>0</comunicationType> <executionType>1</executionType> <loopExecution>false</loopExecution> <takePictures>true</takePictures> <showsSessionWebForm>false</showsSessionWebForm> <confirmClose>2</confirmClose> </activity> <schedule> <id>566</id> <situation> <id>50</id> <description>Returned</description> </situation> <agent> <id>38</id> <name>Entregador 5</name> <active>false</active> <login>e5</login> <centerwebUser>false</centerwebUser> <mobileUser>true</mobileUser> <biUser>false</biUser> <biUserRole>0</biUserRole> <inputWebAsAnotherUser>false</inputWebAsAnotherUser>
<centerwebUserRole>D</centerwebUserRole> <validateClient>0</validateClient> <exportStatus>false</exportStatus> </agent> <origin>1</origin> <hour>16:29</hour> <date>20101005</date> <priority>1</priority> <executionDate>20101005</executionDate> <alternativeIdentifier /> <executionHour>19:30</executionHour> <serviceLocal> <id>6</id> <alternativeIdentifier /> <description>Trevisan Sao Paulo</description> <geoCoordinate>23.566675, 46.6499364</geoCoordinate> <corporateName>Trevisan Tecnologia Ltda</corporateName> <streetType>Av.</streetType> <street>Paulista</street> <streetNumber>726</streetNumber> <streetComplement>sala 1707</streetComplement> <zipCode>99999999</zipCode> <state>SP</state> <observation /> <active>true</active> <origin>1</origin> <insertDateTime>20100707 20:25:15</insertDateTime> <lastUpdateDateTime>20101224 14:14:49</lastUpdateDateTime> </serviceLocal> <exportSituation>0</exportSituation> <observation /> <active>true</active> <activitiesOrigin>1</activitiesOrigin> <recreateTaskOnPda>false</recreateTaskOnPda> </schedule> <sections> <section> <id>9</id> <description>Unica</description> <order>0</order> <alternativeIdentifier /> <active>true</active> <mandatory>1</mandatory>
<useItem>false</useItem> <findItemsByIdentifier>false</findItemsByIdentifier> <itemFillMode>0</itemFillMode> <groupingItemsTypeOnMobile>1</groupingItemsTypeOnMobile><items> <item> <id>6</id> <description>Padrão Item</description> <active>true</active> <fields> <field> <id>23</id> <mobilePageNumber>1</mobilePageNumber> <order>0</order> <nullable>true</nullable> <unique>false</unique> <description>Nome Recebedor:</description> <updatable>true</updatable> <visible>true</visible> <tip /> <type>A</type> <size>25</size> <active>true</active> <sourceValue>0</sourceValue> <showValueInMobile>false</showValueInMobile> <fieldHistory> <id>2645</id> <value>yyyy</value> <valueForExhibition>yyyy</valueForExhibition> <status>true</status> </fieldHistory> </field> <field> <id>24</id> <mobilePageNumber>1</mobilePageNumber> <order>1</order> <nullable>true</nullable> <unique>false</unique> <description>Documento Recebedor:</description> <updatable>true</updatable> <visible>true</visible> <tip />
<type>N</type> <size>15</size> <active>true</active> <sourceValue>0</sourceValue> <showValueInMobile>false</showValueInMobile> <fieldHistory> <id>2646</id> <value>9999</value> <valueForExhibition>9999</valueForExhibition><status>true</status> </fieldHistory> </field> <field> <id>25</id> <mobilePageNumber>1</mobilePageNumber> <order>2</order> <nullable>true</nullable> <unique>false</unique> <description>Tipo Recebedor:</description> <updatable>true</updatable> <visible>true</visible> <tip /> <type>L</type> <active>true</active> <listType>U</listType> <sourceValue>0</sourceValue> <showValueInMobile>false</showValueInMobile> <fieldHistory> <id>2647</id> <value>1</value> <valueForExhibition>O Mesmo</valueForExhibition> <status>true</status> </fieldHistory> </field> </fields> </item> </items> </section> </sections> <geoCoordinates> <geoCoordinate> <id>1031046</id> <date>20121227</date> <hour>161027</hour> <latitude>0.0</latitude> <longitude>0.0</longitude> <type>ON_START_ACTIVITY</type> <observation>Não foi possível capturar as coordenadas. A pessoa desistiu após tentar novamente 0 vezes.</observation> <provider/> <withGps>true</withGps> <gpsEnabled>true</gpsEnabled> <networkEnabled>false</networkEnabled> </geoCoordinate> <geoCoordinate> <id>1031045</id> <date>20121227</date>
<hour>160808</hour> <latitude>0.0</latitude> <longitude>0.0</longitude> <type>ON_START_ACTIVITY</type> <observation>Não foi possível capturar as coordenadas. A pessoa desistiu após tentar novamente 0 vezes.</observation> <provider/> <withGps>true</withGps> <gpsEnabled>true</gpsEnabled> <networkEnabled>false</networkEnabled> </geoCoordinate> </geoCoordinates> </activityHistory>
Busca de um histórico específico
GET /CenterWeb/api/{$apiKey}/activityHistory/{$id}.xml
Esta operação serve para puxar informações de um histórico de execução de atividade do
sistema. Veja o exemplo de retorno de uma entidade abaixo (considerando uma requisição feita
em XML):
<activityHistory> <id>563486</id> <activity> <id>3146</id> <description>Atividade</description> <active>true</active> <loopExecution>false</loopExecution> <takePictures>false</takePictures> </activity> <schedule> <id>394748</id> <origin>4</origin> <hour>23:31</hour> <executionHour>23:31</executionHour> <active>true</active> <activitiesOrigin>3</activitiesOrigin> </schedule> <startTimeOnSystem>20111018 23:31:37</startTimeOnSystem> <finishTimeOnSystem>20111018 23:31:42</finishTimeOnSystem> <items> <activityHistoryItem id="11204373" link="/activityHistoryItem/11204373.xml"/> </items>
</activityHistory>
Note que ao requisitar as informações de um determinado histórico buscando pelo Id, um
conjunto de informações que compõe o histórico de execução são resgatos juntos. Entre as
informações estão, dados sobre a atividade, tarefa e uma lista de items que armazenam os
valores de execução para os campo da atividade.
Busca de um item de histórico específico
GET /CenterWeb/api/{$apiKey}/activityHistoryItem/{$id}.xml
Através desta operação é possivel obter os dados informados para os campos de uma
atividade no momento da execução pelo sistema. Veja o exemplo de retorno de uma entidade
abaixo (considerando uma requisição feita em XML):
<activityHistoryItem> <id>11204373</id> <section> <id>10475</id> <description>Entrega Realizada</description> <active>true</active> <mandatory>true</mandatory> </section> <item> <id>38096</id> <description>Padrão</description> <active>true</active> </item> <sectionField> <id>38037</id> <nullable>true</nullable> <unique>false</unique> <description>Nota</description> <updatable>true</updatable> <visible>true</visible> <type>N</type> <size>2</size> <active>true</active> </sectionField> <value>10</value> </activityHistoryItem>
Descrição de Item de Histórico
Campo Valor Tamanho Obrigatório Descrição
active true/false Não Indica se o item de histórico está ativo ou não id numérico 10 Não Identificador interno o item de histórico no
uMov.me
section.description texto 70 Não Descrição da seção que compõe o item de histórico
section.id numérico 10 Não Identificador interno no uMov.me da seção que compõe o item de histórico.
section.mandatory true/false Não Inidica se a seção que compõe o item de histórico é obrigatória
sectionField.active true/false Não Inidica se o campo está ativo ou não sectionField.description texto 100 Não Descrição do campo de uma seção
sectionField.id numérico 10 Não Identificador interno no uMov.me do campo de uma seção.
sectionField.nullable true/false Não Inidica se o campo da seção aceita valores nulos ou vazio.
sectionField.size numérico 10 Sim Tamanho do campo em caracteres.
sectionField.type
caracter 3 Sim Referente ao tipo de dado do campo. A(alfanumérico), N(numérico), B(booleano), D(data), T(time/hora), L(lista)
sectionField.unique true/false Não Inidica que o valor do campo não pode ser repetido em uma mesma seção e item
sectionField.updatable true/false Não Indica se o valor do campo pode ser alterado no momento da execução
sectionField.visible true/false Não Indica se o campo é visível na seção
value numérico 1000 Não Valor interno do campo utlizado para tratamento do resultado
valueForExhibition numérico 1000 Não Valor de exibição do campo selecionado pelo usuário
Atualização de histórico (Marcar como Exportado)
POST /CenterWeb/api/{$apiKey}/activityHistory/{$id}.xml
Esta operação faz com que o histórico da tarefa seja marcado como exportado. É possível
também informar o nome do arquivo ou lote gerado.
<activityHistory> <executionExportStatus>true</executionExportStatus> <exportFileName>Arquivo 12345</exportFileName> </activityHistory>
Esta operação faz com que o histórico da tarefa seja marcado como não exportado.
<activityHistory> <executionExportStatus>false</executionExportStatus> </activityHistory>Inclusão de histórico
POST /CenterWeb/api/{$apiKey}/schedule/{scheduleId}/activityHistory.xml POST /CenterWeb/api/{$apiKey}/schedule/alternativeIdentifier/{scheduleIdentifier}/activityHistory.xml
Esta operação permite fazer a criação de um histórico pela API.
O histórico pela api, segue uma estrutura similar ao utilizado pela busca de histórico completo
(hierárquico). Nele é informada toda a estrutura do histórico de forma hierárquica (Tarefa >
Atividade > Seção > Item > Campo) para que o sistema consiga mapear este registro de forma
correta.
A criação do histórico obriga a existência de uma tarefa. Esta tarefa por sua vez tem suas
atividades vinculadas, seguidas de seções e campos. Sendo assim para que um histórico seja
criado, é necessário que toda a hierarquia de uma execução seja préexistente no sistema.
Para criação do histórico começamos pela tarefa. Esta tarefa é identificada pela api através das
chaves {scheduleId} ou {scheduleIdentifier}, identificada acima na URL de exemplo. Isso
demonstra que é possível identificar uma tarefa através de seu id interno do sistema ou pelo
identificador alternativo cadastrado.
A tarefa informada na URL deve estar na situação pendente de envio ou em campo. Somente é
permitida a inclusão de históricos para atividades que mantem a tarefa em campo. Após a
inclusão do histórico, a tarefa passa para a situação Em Campo.
Existem dois tipos de histórico. Um relacionado a algum item ou aqueles utilizados em seções
sem items. Para cada caso, existe uma pequena alteração na estrutura do XML que deve ser
enviado para a API.
Exemplo de histórico
SEM
itens:
POST /CenterWeb/api/{$apiKey}/schedule/alternativeIdentifier/tarefa1/activityHistory.xml <activityHistory> <activity> <alternativeIdentifier>atividade1</alternativeIdentifier> </activity> <sections> <section> <alternativeIdentifier>secao1</alternativeIdentifier> <fields> <field> <alternativeIdentifier>campo1</alternativeIdentifier> <fieldHistory> <value>yyyy</value> <valueForExhibition>yyyy</valueForExhibition> </fieldHistory> </field> <field> <alternativeIdentifier>campo2</alternativeIdentifier> <fieldHistory> <value>9999</value> <valueForExhibition>9999</valueForExhibition> </fieldHistory> </field> </fields> </section> </sections> </activityHistory>
No exemplo acima está sendo criado um histórico para a tarefa identificada como "tarefa1".
Estão sendo preenchidos os campos "campo1" e "campo2" da seção "secao1" na atividade
"atividade1". Todos as referências são identificadas utilizando o identificador alternativo.
Exemplo de histórico
COM
itens:
POST /CenterWeb/api/{$apiKey}/schedule/alternativeIdentifier/tarefa2/activityHistory.xml <activityHistory> <activity> <alternativeIdentifier>atividade2</alternativeIdentifier> </activity> <sections> <section> <alternativeIdentifier>secao1</alternativeIdentifier> <items> <item> <alternativeIdentifier>item1</alternativeIdentifier> <fields> <field> <alternativeIdentifier>campo1</alternativeIdentifier> <fieldHistory> <value>yyyy</value> <valueForExhibition>yyyy</valueForExhibition> </fieldHistory> </field> <field> <alternativeIdentifier>campo2</alternativeIdentifier> <fieldHistory> <value>9999</value> <valueForExhibition>9999</valueForExhibition> </fieldHistory> </field> </fields> </item> </items> </section> </sections> </activityHistory>
No exemplo acima está sendo criado um histórico para a tarefa identificada como "tarefa2".
Estão sendo preenchidos os campos "campo1" e "campo2" do item "item1" da seção "secao1"
na atividade "atividade2". Todos as referências são identificadas utilizando o identificador
alternativo.
Callback Para Históricos Retornados
O sistema conta com um serviço de callback para notificar automaticamente um histórico
recebido na retaguarda para um outro sistema. Isso torna o processo mais ágil, sem a
necessidade de fazer requisições de API para consultar se a informação já chegou ou ainda
está sendo processada.
Para que o callback funcione de forma adequada, ainda deve ser solicitada a ativação do
recurso ao time de suporte. Em breve, estaremos disponibilizando uma interface para que seja
possível a ativação do recurso via uMov.Center.
Com o processo ativo, deve ser criado um campo customizável alfanumérico na tarefa. Esse
campo deve possuir identificador altenativo = "callback". Dessa forma, ao criar uma tarefa, deve
ser informado nesse campo (callback) a URL do seu sistema que irá receber os dados do
histórico que estão no uMov.me.
Quando um histórico da tarefa for recebido na retaguarda, com o processo de callback ativo, e
com uma URL de callback cadastrada na tarefa, será disparada uma requisição POST para a
URL informada contendo as informações dos históricos recebidos na retaguarda, conforme
exemplo listado abaixo:
<schedule> <alternativeIdentifier>Tarefa XXX</alternativeIdentifier> <activityHistories> <activityHistory id="8988776655445393"/> </activityHistories> </schedule>Note que nesse exemplo, é enviado o identificador alternativo da tarefa (Tarefa XXX) e o
histórico recebido para a tarefa abaixo com o id="8988776655445393". Para buscar os dados
do histórico, podem ser usados os métodos
GET/CenterWeb/api/{$apiKey}/activityHistoryHierarchical/{$id}.xml ou GET
/CenterWeb/api/{$apiKey}/activityHistory/{$id}.xml
, conforme listado acima.
Importante:
O sistema somente irá considerar os históricos recebidos após a data e hora de
ativação do recurso e para tarefas que possuem uma URL de callback válida. Além disso, ao
disparar a requisição do callback, o sistema marca o histórico como já integrado. Dessa forma,
a chamada da API de callback é executada uma única vez por histórico.
Observações importantes:
● Os valores informados deverão sempre respeitar as informações de tipo, tamanho, etc.
dos campos criados pelo sistema. (Ex. apenas números para campos numéricos, etc.);
● No caso de campo data o formato esperado do valor deverá ser AAAAMMDD;
● Não é possível fazer a criação de histórico para campos do tipo foto e multimidia pela
API;
● Os campos
value
e
valueForExhibition
são principalmente usados para casos onde
temos campo do tipo lista, nos demais casos (Alfanumérico, Numérico, etc.) você
deverá apenas repetir o valor esperado nos dois campos.
● As fórmulas de valor e validação para campos, seções e atividades não são executadas
na inclusão de histórico via API.
● Sistema não valida de itens estão vinculados a seção. Somente valida se item está
cadastrado no ambiente.
● Não são validados campos ou itens obrigatórios na inclusão via API.
● Não é feita a validação de seção e atividades antecessoras.
● As coordenadas GPS de execução não podem ser incluídas via API.
● Os valores preenchidos em campo lista não são validados para verificar se são válidos
conforme o cadastro do campo.
AppVersion (Versão do Aplicativo)
A API de AppVersion permite interagir com os aplicativos e versões geradas do aplicativo
vinculado ao ambiente.
Descrição de uma appVersion
Campo Valor Tamanho Obrigatório Descrição
id numérico 10 Sim Identificador interno da versão do aplicativo no uMov.me
description texto 100 Sim Descrição da versão do aplicativo.
version texto 20 Sim Identificação da versão do aplicativo informada na publicação da versão.
observation texto 500 Não Observação sobre a versão do aplicativo com detalhes sobre ela.
updateType texto 1 Sim Indica o tipo de atualização (0=Opcional | 1=Obrigatória).
publishDate dateTime Sim Data e hora da publicação da versão do aplicativo
Descrição de uma app
Campo Valor Tamanho Obrigatório Descrição
id numérico 10 Sim Identificador interno do aplicativo no uMov.me description texto 100 Sim Descrição do aplicativo.
observation texto 500 Não Observações gerais sobre o aplicativo
Importante
: uma versão de aplicativo (appVersion) sempre está vinculada a um aplicativo
(app). A consulta do aplicativo sempre será feita através da versão que está vinculada ao
ambiente.
Consulta a versão corrente do aplicativo vinculado ao ambiente
GET /CenterWeb/api/{$apiKey}/app/version.xml
Esta operação faz com que seja retornada a versão e o aplicativo vinculado ao ambiente.
Este é um exemplo de um xml retornado de um ambiente:
<appVersion> <id>1</id> <description>Versão 1 do aplicativo de vendas</description> <version>1.0</version> <observation>Versão inicial gerada para o aplicativo de força de vendas</observation> <updateType>0</updateType>
<publishDate>20130813 15:00:00</publishDate> <app> <id>1</id> <description>Força de Vendas</description> <observation>Aplicativo para vendas no uMov.me</observation> </app> </appVersion>
Consultar versões disponíveis de um aplicativo
GET
/CenterWeb/api/{$apiKey}/app/{$app_id}.xml
Esta operação faz com que seja retornada uma lista com as versões disponíveis de um
aplicativo. Somente será possível consultar versões de um aplicativo já vinculado ao ambiente
Este é um exemplo de um xml retornado de um ambiente:
<app> <id>1</id> <description>Força de Vendas</description> <observation>Aplicativo para vendas no uMov.me</observation> <versions> <appVersion id="1" link="/appVersion/1.xml" /> <appVersion id="2" link="/appVersion/2.xml" /> </versions> </app>
Consultar uma versão específica de um aplicativo
GET /CenterWeb/api/{$apiKey}/appVersion/{$appVersion_id}.xml
Esta operação faz com que seja retornada detalhes de uma versão específica para
conferência.
Este é um exemplo de um xml retornado de um ambiente:
<appVersion> <id>1</id> <description>Versão 1 do aplicativo de vendas</description> <version>1.0</version> <observation>Versão inicial gerada para o aplicativo de força de vendas</observation> <updateType>0</updateType>
<publishDate>20130813 15:00:00</publishDate> <app> <id>1</id> <description>Força de Vendas</description> <observation>Aplicativo para vendas no uMov.me</observation> </app> </appVersion>
Agendamento de atualização da versão de um aplicativo
POST /CenterWeb/api/{$apiKey}/app/version.xml
Esta operação faz com que seja agendada a atualização de um aplicativo
<app> <versions> <appVersion> <id>2</id> <scheduledDateTime>20130814 18:00:00</scheduledDateTime> </appVersion> </versions> </app>
Deve ser informada a versão que será aplicada no ambiente no momento da atualização.
Somente será possível atualizar para uma versão com data mais recente que a versão corrente
vinculada ao ambiente.
Pode ser informada a data e hora de agendamento. Essa data e hora é opcional. Se não
informada, o sistema irá gravar a data corrente para realizada a atualização no momento da
chamada.
Activity (Atividade)
A API de atividade permite consultar as atividades existentes no uMov.me.
Descrição de uma Atividade
Campo Valor Tamanho Obrigatório Descrição
description texto 10 Sim Descrição da atividade no uMov.me
id numérico 10 Não Identificador interno da atividade no uMov.me sections lista Não Lista de seções vinculadas à atividade
alternativeIdentifier texto 100 Não Identificador alternativo da atividade no uMov.me
displayOrder numérico 10 Não Ordem de exibição da atividade
active true / false Não Indica se uma atividade está no estado ativo ou não. Pode receber valores "true" ou "false" comunicationType caracter 1 Sim Tipo de sincronismo da atividade
(0Confirmado pelo Usuário | 1Sincronismo Automático | 2Sincronismo Manual) executionType caracter 1 Sim Tipo de execução da atividade (0Mantem
Tarefa no Dispositivo Móvel | 1Finaliza Tarefa | 2Finaliza Atividade)
loopExecution true / false Não Indica se execução da atividade é em loop. Pode receber valores "true" ou "false" showSessionWebForm true / false Não Indica se exibe seção na web com campos e
itens em formato de grade. Pode receber valores "true" ou "false"
confirmClose caracter 1 Não Confirmação de encerramento da atividade executada (0Confirma | 1Confirma e Exibe Dados para Conferência | 2Confirma e Exibe os Itens Não Coletados)
acceleratedExecution true / false Não Indica se atividade possui execução acelerada com teclas de atalho. Pode receber valores "true" ou "false"
captureGPS true / false Não Indica se GPS é coletado na execução da atividade. Pode receber valores "true" ou "false"
confirmWithoutGPS true / false Não Indica se solicita confirmação no encerramento de atividade sem GPS coletado. Pode receber valores "true" ou "false"
GPSIsMandatory true / false Não GPS obrigatório na execução da atividade. Pode receber valores "true" ou "false" locked true / false Não Indica se a atividade encontrase bloqueada
para edição. Pode receber valores "true" ou "false"
documentation texto 500 Não Utilizado para registrar a documentação do registro
logicalExpressions lista Não Lista de Fórmulas de Validação da atividade
Busca por Lista de Atividades
GET /CenterWeb/api/{$apiKey}/activity.xmlSe 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}/activity.xml?description=PedidoEsta requisição está puxando todas as atividades em que a sua descrição(description) é igual a
pedido.
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>activity</resourceName> <size>1</size> <entries> <entry id="1802274" link="/activity/1802274.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 retornada o
Id do registro no uMov.me e o link que possa ser usado para recuperar os dados específicos
deste registro. Através desta resposta, o chamador da API pode agora buscar as informações
específicas dos retornos que foram encontrados.
Busca por Atividade Específica
Usando identificador interno
Este recurso serve para puxar dados de uma atividade específica do sistema. Veja o exemplo
de retorno de uma entidade abaixo (considerando uma requisição feita em XML):
<activity> <id>1802275</id> <description>Fechamento</description> <sections> <section id="1782993" link="/section/1782993.xml"/> <section id="1782994" link="/section/1782994.xml"/> </sections> <alternativeIdentifier>ID_Fechamento</alternativeIdentifier> <active>true</active> <comunicationType>0</comunicationType> <executionType>1</executionType> <loopExecution>false</loopExecution> <showsSessionWebForm>false</showsSessionWebForm> <confirmClose>1</confirmClose> <acceleratedExecution>false</acceleratedExecution> <confirmWithoutGPS>true</confirmWithoutGPS> <GPSIsMandatory>false</GPSIsMandatory> <captureGPS>false</captureGPS> <locked>false</locked> <documentation>Documentação</documentation> <mathExpressions> <mathExpression id="1156641" link="/mathExpression/1156641.xml"/> </mathExpressions> <logicalExpressions> <logicalExpression id="1272199" link="/logicalExpression/1272199.xml"/> </logicalExpressions> </activity>
Usando identificador alternativo
GET /CenterWeb/api/{$apiKey}/activity/alternativeIdentifier/{$identificador alternativo}.xml
Este recurso serve para buscar dados de uma atividade específica do sistema através do seu
identificador alternativo. Veja o exemplo de retorno de uma entidade abaixo (considerando uma
requisição feita em XML):
<activity> <id>863526</id> <description>Atividade</description> <sections> <section id="843515" link="/section/843515.xml"/></sections> <alternativeIdentifier>ID_ATIV</alternativeIdentifier> <active>true</active> <comunicationType>0</comunicationType> <executionType>1</executionType> <loopExecution>false</loopExecution> <showsSessionWebForm>false</showsSessionWebForm> <confirmClose>1</confirmClose> <acceleratedExecution>false</acceleratedExecution> <confirmWithoutGPS>true</confirmWithoutGPS> <GPSIsMandatory>false</GPSIsMandatory> <captureGPS>false</captureGPS> <locked>false</locked> <documentation>Documentação</documentation> <mathExpressions> <mathExpression id="1156656" link="/mathExpression/1156656.xml"/> </mathExpressions> <logicalExpressions> <logicalExpression id="1272188" link="/logicalExpression/1272188.xml"/> </logicalExpressions> </activity>
Section (Seção)
Descrição de uma Seção
Campo Valor Tamanho Obrigatório Descrição
id numérico 10 Não Identificador interno da seção no uMov.me
description texto 100 Sim Descrição da seção da atividade order numérico 10 Não Ordem de exibição da seção na
atividade
sectionFields lista Não Lista de campos da seção alternativeIdentifier numérico 100 Não Identificador alternativo da seção mandatory caracter 1 Não Indica se o preenchimento da seção é
obrigatório ou opcional (0Opcional | 1Obrigatório)
