Paginação na consulta e inclusão de campos customizáveis via API uMov.me

Um recurso muito utilizado nas integrações entre a plataforma uMov.me e outros sistemas é a API. Ela visa facilitar as operações de consulta, atualização e inclusão de dados no uMov.me.

Paginação nas consultas dos cadastros

Buscando tornar a API ainda mais completa, foi implementada a paginação nas consultas dos cadastros.

Isso é necessário, pois a consulta via API retorna um número máximo de 100 registros. Com a paginação, o sistema retorna 100 a cada página, permitindo assim fazer uma interação nas páginas da consulta e buscar todos os registros do cadastro. Veja abaixo um exemplo de busca dos registros de tarefas (schedule) em 2 páginas.

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

Manutenção dos cadastros informando os campos customizáveis

Outro recurso disponibilizado é a manutenção dos cadastros informando os campos customizáveis. A partir disso, é possível consultar, alterar ou incluir um cadastro customizável, um local, um item, uma pessoa ou uma tarefa informando os campos customizáveis. Esses campos customizáveis devem ser informados dentro da tag <customFields> e cada campo deve ser representado pelo seu identificador alternativo. Veja abaixo um exemplo de inclusão de um item informando campos customizáveis.

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

<item>
     <description>Produto ABC</description>
     <subGroup>
           <id>1</id>
     </subGroup>
     <alternativeIdentifier>ABC</alternativeIdentifier> 
     <customFields>
          <Estoque>200</Estoque>
          <Preço>49.90</Preço>
     </customFields>
</item>

Inclusão ou atualização de uma tarefa pelo identificador alternativo

Um nova possibilidade existente na API é a inclusão ou atualização de uma tarefa informado o identificador alternativo do local e da pessoa. Antes era necessário fazer uma busca na pessoa e no local para encontrar o ID interno do cadastro, para posteriormente vincular esses ID’s na tarefa. Agora é possível informar diretamente o local e a pessoa através de seus identificadores alternativos, conforme apresentado abaixo. Importante ressaltar que para isso funcionar, os locais e pessoas não poderão ter registros com identificadores alternativos duplicados. Se isso ocorrer, a API retornará erro na inclusão ou alteração da tarefa.

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

<schedule>
    <agent>
          <alternativeIdentifier>AGENTE X</alternativeIdentifier>
    </agent>
    <serviceLocal>
          <alternativeIdentifier>LOCAL Y</alternativeIdentifier>
    </serviceLocal>
    <activitiesOrigin>4</activitiesOrigin>
    <date>2015–03–20</date>
    <hour>08:00</hour>
    <activityRelationship>
         <activity>
              <alternativeIdentifier>ATIVIDADE ABC</alternativeIdentifier>
         </activity>
     </activityRelationship>
     <customFields>
         <Nro_OS>9854</Nro_OS>
         <Contato>Fulano de tal</Contato>
     </customFields>
</schedule>