Base de Conhecimento

Descrição de um Custom Field

OBS: Para atualização de cadastro, somente o identificador alternativo é obrigatório.

Busca Por Lista de Campos Customizáveis

GET /CenterWeb/api/{$apiKey}/{nomeEntidade}/{idEntidade}/customField.xml

{nomeEntidade} = agent, serviceLocal, item ou schedule;

{idEntidade} = Identificador interno da entidade informada em {nomeEntidade}

Se ainda preferir, 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}/{nomeEntidade}/{idEntidade}/customField.xml?description=campo&active=true

Esta requisição está pedindo todos os campos customizáveis disponíveis cuja descrição tenha a palavra campo presente (description=campo) e que estejam ativos (active=true). 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>customField</resourceName>

<size>3</size>

<entries>

<entry id="1" link="/agent/1234/customField/1.xml"/>

<entry id="2" link="/agent/1234/customField/2.xml"/>

<entry id="3" link="/agent/1234/customField/3.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, o Id do registro no uMov.me e o link que pode ser usado para recuperar os dados específicos deste registro.

Busca de um Campo Customizável específico

Busca pelo ID:

GET /CenterWeb/api/{$apiKey}/{nomeEntidade}/{idEntidade}/customField/{$id}.xml

{nomeEntidade} = agent, serviceLocal, item ou schedule;

{idEntidade} = Identificador interno da entidade informada em {nomeEntidade}

{$id} = Identificador do campo customizável

Busca pelo Identificador Alternativo:

GET /CenterWeb/api/{$apiKey}/{nomeEntidade}/{idEntidade}/customField/alternativeIdentifier/{$idalternativo}.xml

{nomeEntidade} = agent, serviceLocal, item ou schedule;

{idEntidade} = Identificador interno da entidade informada em {nomeEntidade}

{$idalternativo} = Identificador alternativo do campo customizável

Este recurso serve para puxar dados de um agente/pessoa específica do sistema. Veja o exemplo de retorno de uma entidade abaixo (considerando uma requisição feita em XML):

<customField>

<id>1</id>

<fieldType>L</fieldType>

<alternativeIdentifier>identificadorAlternativo</alternativeIdentifier>

<description>descrição</description>

<size>1</size>

<active>true</active>

<entity>1</entity>

<viewQueryOnMobile>false</viewQueryOnMobile>

<customFieldValues>

<customFieldValue>

<internalValue>1</internalValue>

<externalValue>valor 1</externalValue>

</customFieldValue>

<customFieldValue>

<internalValue>2</internalValue>

<externalValue>valor 2</externalValue>

</customFieldValue>

</customFieldValues>

</customField>

Descrição de um Custom Field Value

Inclusão/Alteração de Valores de Campos Customizáveis

Usando o Id:

POST /CenterWeb/api/{$apiKey}/{nomeEntidade}/{idEntidade}/customField/{$id}.xml

{nomeEntidade} = agent, serviceLocal, item ou schedule;

{idEntidade} = Identificador interno da entidade informada em {nomeEntidade}

{$id} = Identificador do campo customizável

Usando o identificador alternativo:

POST /CenterWeb/api/{$apiKey}/{nomeEntidade}/{idEntidade}/customField/alternativeIdentifier/{$altId}.xml

{nomeEntidade} = agent, serviceLocal, item ou schedule;

{idEntidade} = Identificador interno da entidade informada em {nomeEntidade}

{$altId} = Identificador alternativo do campo customizável

Inclusão/Alteração em lote de Valores de Campos Customizáveis

Usando o Id:

POST /CenterWeb/api/{$apiKey}/batch/{nomeEntidade}/{idEntidade}/customFields.xml

{nomeEntidade} = agent, serviceLocal, item ou schedule;

{idEntidade} = Identificador interno da entidade informada em {nomeEntidade}

Usando o identificador alternativo:

POST /CenterWeb/api/{$apiKey}/batch/{nomeEntidade}/alternativeIdentifier/{idAltEntidade}/customFields.xml

{nomeEntidade} = agent, serviceLocal, item ou schedule;

{idAltEntidade} = Identificador alternativo da entidade informada em {nomeEntidade}

Este recurso permite fazer a inclusão/alteração de valores de campos customizados em lote para um determinada entidade, sem que haja a necessidade de fazer inúmeras requisições para a api. Abaixo segue exemplo da estrutura do xml a ser enviado:

<customFields>

<customField>

<alternativeIdentifier>identificadoralternativo1</alternativeIdentifier>

<customFieldValues>

<customFieldValue>

<internalValue>valorinterno1</internalValue>

<externalValue>valorexterno1</externalValue>

</customFieldValue>

</customFieldValues>

</customField>

...

<customField>

<alternativeIdentifier>identificadoralternativo2</alternativeIdentifier>

<customFieldValues>

<customFieldValue>

<internalValue>valorinterno2</internalValue>

<externalValue>valorexterno2</externalValue>

</customFieldValue>

</customFieldValues>

</customField>

</customFields>

Ambos as chamadas servem para incluir/alterar os valores de um campo customizável no sistema. Existe um mínimo de informações que o sistema espera receber para poder realizar a operação em questão. Confira a descrição do custom field para identificar os campos obrigatórios. Veja um exemplo da requisição com dados em XML:

<customField>

<customFieldValues>

<customFieldValue>

<internalValue>1</internalValue>

<externalValue>Valor 1</externalValue>

</customFieldValue>

<customFieldValue>

<internalValue>2</internalValue>

<externalValue>Valor 2</externalValue>

</customFieldValue>

</customFieldValues>

</customField>

OBS: O envio acima serve especialmente para a utilização com campos multivalorados.

Neste caso, lendo o que está sendo pedido ao uMov.me é que sejam criados/alterados os valores de um custom field com os campos obrigatórios preenchidos (internalValue e externalValue). É importante lembrar que ao solicitar a criação/alteração de valores de campos customizáveis, todos os valores existentes serão substituídos pelos novos valores, ou seja, se for passado dois valores e haviam três, o campo customizável ficará com dois valores, mesmo que estes sejam diferentes.

Inclusão/Alteração de Valores no formato XML de Campos Customizáveis I

Este recurso serve para incluir/alterar os valores de um campo XML customizável no sistema. Existe um mínimo de informações que o sistema espera receber para poder realizar a operação em questão. Para incluir um XML como valor de um campo customizável é necessario inserir dentro de uma tag especial chamada CDATA. Veja um exemplo da requisição com valores em XML:

<customField>

<customFieldValues>

<customFieldValue>

<internalValue>

<![CDATA[

<agent>

<nome>umov.me</nome>

</agent>

]]>

</internalValue>

<externalValue>

<![CDATA[

<agent>

<nome>umov.me</nome>

</agent>

]]>

</externalValue>

</customFieldValue>

</customFieldValues>

</customField>

Neste caso, lendo o que está sendo pedido ao uMov.me é que sejam criados/alterados os valores de um custom field com os campos obrigatórios preenchidos (internalValue e externalValue) com valores no formato XML. É importante lembrar do uso da tag especial CDATA para que o sistema consiga realizar a criação/alteração do valor. Toda vez que ao solicitar a criação/alteração de valores de campos customizáveis, todos os valores existentes serão substituídos pelos novos valores, ou seja, se for passado dois valores e haviam três, o campo customizável ficará com dois valores, mesmo que estes sejam diferentes.

Operações usando HTTP POST

Ao criar ou atualizar um valor de campo customizável você precisa em sua requisição POST identificar os dados do campo customizável utilizando um parametro 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, {nomeEntidade} pelo nome da entidade que se quer alterar o customField (agent, serviceLocal, item ou schedule), {idEntidade} id da entidade escilhida em nomeEntidade e {$id} pelo código do campo customizável que está sendo modificado. Neste exemplo estamos incluindo/alterando o valor do campo customizável {$id}. Veja a base do form HTML.

<html>

<form method="POST" action="http://api.umov.me/CenterWeb/api/{$apiKey}/{nomeEntidade}/{idEntidade}/customField/{$id}.xml">

<input type="text" name="data" value="<customField><customFieldValues><customFieldValue><internalValue>1</internalValue><externalValue>Valor 1</externalValue></customFieldValue></customFieldValues></customField>" />

<input type="submit" />

</form>

</html>

Custom Field / Custom Field Value (Campo customizável / Valor campo customizável)

OBS: Para atualização de cadastro, somente o identificador alternativo é obrigatório.