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

Transcrição

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

2 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 1

3 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 2

4 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 3

5 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 4

6 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 5

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

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

9 Como nossa API está estruturada A API do umov.me é implementada sobre o protocolo HTTP/HTTPS usando verbos conhecidos do protocolo como 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. 8

10 A chave é usada como parte das informações de uma dada requisição, exemplo: e732f53e811be6f0678c4512c9bcea990 /servicelocal/5421.xml Neste 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: 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: Exemplo da requisição com dados do XML: <authentication> <login>fulano</login> <password>senhafulano</password> <domain>ambiente</domain> </authentication> 9

11 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; A requisição acima é lida da seguinte forma: desejo retornar () 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: 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). Enviar parâmetros para a API umov.me é simples assim! Operações Disponíveis 10

12 Busca Simples Por Identificador Busca Por Lista de Recursos arametro2}={valor2}... Criação de Novos Recursos POST Atualização de Recursos POST 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 () 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 ( sec10.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: 11

13 <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, deve se adicionar o parâmetro 'paging.page' à requisição informando o número da página desejada: Limites Requisições simultâneas 12

14 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=" <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! 13

15 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 (yyyy mm dd 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 (yyyy mm dd 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 /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 /CenterWeb/api/{$apiKey}/activityHistory.xml?schedule=002 Atividades iniciados entre :00:00 e :59:59 14

16 /CenterWeb/api/{$apiKey}/activityHistory.xml?initialStartTimeOnSystem= %2008:00: 00&endStartTimeOnSystem= %2023:59:00:00 Atividades finalizadas entre :00:00 e :59:59 /CenterWeb/api/{$apiKey}/activityHistory.xml?endStartTimeOnSystem= %2008:00:00&endFini shtimeonsystem= %2023:59:00:00 Atividades executadas entre :00:00 e :59:59 /CenterWeb/api/{$apiKey}/activityHistory.xml?initialStartTimeOnSystem= %2008:00:00&endFi nishtimeonsystem= %2023:59:00:00 Atividades filtrando os históricos através de atributos das entidades vinculadas /CenterWeb/api/{$apiKey}/activityHistory.xml?activity.captureGPS=true&schedule.alternativeIdentifier=t este Realizar 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) /CenterWeb/api/{$apiKey}/activityHistoryHierarchical/{$id}.xml 15

17 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> :30:16</startTimeOnSystem> <finishtimeonsystem> :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> <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> 16

18 <centerwebuserrole>d</centerwebuserrole> <validateclient>0</validateclient> <exportstatus>false</exportstatus> </agent> <origin>1</origin> <hour>16:29</hour> <date> </date> <priority>1</priority> <executiondate> </executionDate> <alternativeidentifier /> <executionhour>19:30</executionhour> <servicelocal> <id>6</id> <alternativeidentifier /> <description>trevisan Sao Paulo</description> <geocoordinate> , </geoCoordinate> <corporatename>trevisan Tecnologia Ltda</corporateName> <streettype>av.</streettype> <street>paulista</street> <streetnumber>726</streetnumber> <streetcomplement>sala 1707</streetComplement> <zipcode> </zipcode> <state>sp</state> <observation /> <origin>1</origin> <insertdatetime> :25:15</insertDateTime> <lastupdatedatetime> :14:49</lastUpdateDateTime> </servicelocal> <exportsituation>0</exportsituation> <observation /> <activitiesorigin>1</activitiesorigin> <recreatetaskonpda>false</recreatetaskonpda> </schedule> <sections> <section> <id>9</id> <description>unica</description> <order>0</order> <alternativeidentifier /> <mandatory>1</mandatory> <useitem>false</useitem> <finditemsbyidentifier>false</finditemsbyidentifier> <itemfillmode>0</itemfillmode> <groupingitemstypeonmobile>1</groupingitemstypeonmobile> 17

19 <items> <item> <id>6</id> <description>padrão Item</description> <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> <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> <sourcevalue>0</sourcevalue> <showvalueinmobile>false</showvalueinmobile> <fieldhistory> <id>2646</id> <value>9999</value> <valueforexhibition>9999</valueforexhibition> 18

20 <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> <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> </id> <date> </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> </id> <date> </date> 19

21 <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 /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> <loopexecution>false</loopexecution> <takepictures>false</takepictures> </activity> <schedule> <id>394748</id> <origin>4</origin> <hour>23:31</hour> <executionhour>23:31</executionhour> <activitiesorigin>3</activitiesorigin> </schedule> <starttimeonsystem> :31:37</startTimeOnSystem> <finishtimeonsystem> :31:42</finishTimeOnSystem> <items> <activityhistoryitem id=" " link="/activityhistoryitem/ xml"/> </items> 20

22 </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 /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> </id> <section> <id>10475</id> <description>entrega Realizada</description> <mandatory>true</mandatory> </section> <item> <id>38096</id> <description>padrão</description> </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> </sectionfield> <value>10</value> </activityhistoryitem> 21

23 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 sectionfield.unique sectionfield.updatable 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) true/false Não Inidica que o valor do campo não pode ser repetido em uma mesma seção e item 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 22

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

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

26 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 25

27 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=" "/> </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=" ". Para buscar os dados do histórico, podem ser usados os métodos /CenterWeb/api/{$apiKey}/activityHistoryHierarchical/{$id}.xml ou /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 AAAA MM DD; 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. 26

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

29 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 /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> 28

30 <publishdate> :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 /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 /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> 29

31 <publishdate> :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> :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 30

32 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 (0 Confirmado pelo Usuário 1 Sincronismo Automático 2 Sincronismo Manual) executiontype caracter 1 Sim Tipo de execução da atividade (0 Mantem Tarefa no Dispositivo Móvel 1 Finaliza Tarefa 2 Finaliza 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 (0 Confirma 1 Confirma e Exibe Dados para Conferência 2 Confirma 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 encontra se bloqueada para edição. Pode receber valores "true" ou "false" documentation texto 500 Não Utilizado para registrar a documentação do registro mathexpressions lista Não Lista de Fórmulas de Valor da atividade 31

33 logicalexpressions lista Não Lista de Fórmulas de Validação da atividade Busca por Lista de Atividades /CenterWeb/api/{$apiKey}/activity.xml Se 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: /CenterWeb/api/{$apiKey}/activity.xml?description=Pedido Esta 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=" " link="/activity/ 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 /CenterWeb/api/{$apiKey}/activity/{$id}.xml 32

34 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> </id> <description>fechamento</description> <sections> <section id=" " link="/section/ xml"/> <section id=" " link="/section/ xml"/> </sections> <alternativeidentifier>id_fechamento</alternativeidentifier> <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=" " link="/mathexpression/ xml"/> </mathexpressions> <logicalexpressions> <logicalexpression id=" " link="/logicalexpression/ xml"/> </logicalexpressions> </activity> Usando identificador alternativo /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/ xml"/> 33

35 </sections> <alternativeidentifier>id_ativ</alternativeidentifier> <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=" " link="/mathexpression/ xml"/> </mathexpressions> <logicalexpressions> <logicalexpression id=" " link="/logicalexpression/ 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 (0 Opcional 1 Obrigatório) 34

36 useitem caracter 1 Não Indica como os itens estão vinculados a seção (0 Itens selecionados 1 Subgrupos de itens selecionados 2 Todos os itens cadastrados) finditemsbyidentifier true / false Não Habilita a busca de itens da seção pelo identificador alternativo. Pode receber valores "true" ou "false" itemfillmode caracter 1 Não Tipo de preenchimento de itens na seção (0 Permitir Preencher Quantos Forem Necessários 1 Apenas 1 Item Deve ser Preenchido 2 Todos os Itens Devem Ser Preenchidos) groupingitenstypeonmobile caracter 1 Não Forma de agrupamento de itens, grupo ou subgrupo no mobile (0 Não Exibir Agrupamento de Itens 1 Exibir Somente Subgrupo 2 Exibir Grupo e Subgrupo) activityhistoryreporttype caracter 1 Não Forma de visualização dos campos no relatório (H Horizontal V Vertical) displayitemsinmobile caracter 1 Não Filtro de itens no mobile (0 Itens Vinculados na Seção 1 Itens Vinculados no Local ou Tarefa) seeitemscollectedautomatically true / false Não Visualiza itens na tela de itens coletados automaticamente. Pode receber valores "true" ou "false" quizmode true / false Não Configuração para exibir campos aleatoriamente. Pode receber valores "true" ou "false" numberfieldsquiz numérico 10 Não Quantidade de campos exibidos no mobile quando ativado a opção para Exibir Campos Aleatoriamente locked true / false Não Indica se a atividade encontra se bloqueada para edição. Pode receber valores "true" ou "false" markcompletegroup true / false Não Exibe uma indicação ao se preencher todos itens de um subgrupo. A indicação também é exibida no grupo, quando seus subgrupos estão todos preenchidos documentation texto 500 Não Utilizado para registrar a 35

37 documentação do registro mathexpressions lista Não Lista de Fórmulas de Valor da atividade logicalexpressions lista Não Lista de Fórmulas de Validação da atividade Busca Por Lista de Seções /CenterWeb/api/{$apiKey}/section.xml Se 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: /CenterWeb/api/{$apiKey}/section.xml?activity.description={descrição da atividade} Esta requisição busca todas as seções contidas na atividade requisitada. 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>section</resourcename> <size>3</size> <entries> <entry id=" " link="/section/ xml"/> <entry id=" " link="/section/ xml"/> <entry id=" " link="/section/ 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 de uma Seção 36

38 Usando Identificador Interno /CenterWeb/api/{$apiKey}/section/{$id}.xml Este recurso serve para puxar todos os dados de uma seção específica do sistema. Veja o exemplo de retorno de uma entidade abaixo (considerando uma requisição feita em XML): <section> <id> </id> <description>total</description> <order>2</order> <sectionfields/> <alternativeidentifier/> <active>false</active> <mandatory>1</mandatory> <useitem>0</useitem> <finditemsbyidentifier>false</finditemsbyidentifier> <itemfillmode>0</itemfillmode> <groupingitemstypeonmobile>1</groupingitemstypeonmobile> <activityhistoryreporttype>v</activityhistoryreporttype> <displayitemsinmobile>0</displayitemsinmobile> <seeitemscollectedautomatically>false</seeitemscollectedautomatically> <quizmode>false</quizmode> <locked>false</locked> <markcompletegroup>false</markcompletegroup> <documentation>documentação</documentation> <mathexpressions> <mathexpression id=" " link="/mathexpression/ xml"/> </mathexpressions> <logicalexpressions> <logicalexpression id=" " link="/logicalexpression/ xml"/> </logicalexpressions> </section> Usando Identificador Alternativo /CenterWeb/api/{$apiKey}/section/alternativeIdentifier{$identificador alternativo} Este recurso serve para buscar todos os dados de uma seção 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): <section> <id> </id> 37