Cadastros e campos customizáveis (Custom Entity (Cadastro Customizável))
A API de Custom Entity é responsável pela manutenção de cadastros customizáveis e valores para os cadastros. É nela que vamos conseguir consultar os cadastros customizáveis, além de consultar, incluir e atualizar os registros dos cadastros customizáveis.
Descrição de um Cadastro Customizável
OBS: Para atualização de cadastro, somente o identificador alternativo é obrigatório.
Importante: Somente é possível consultar os cadastros customizáveis via API. Não é possível criar ou editar os cadastros customizáveis. Somente é possível incluir e editar os registros dos cadastros customizáveis.
Busca Por Lista de Cadastros Customizáveis
GET /CenterWeb/api/{$apiKey}/customEntity.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:
GET /CenterWeb/api/{$apiKey}/customEntity.xml?description=134
description: pesquisar por um determinado cadastro customizável com descrição = 134
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>customEntity</resourceName>
<size>6</size>
<entries>
<entry id="60026" link="/customEntity/60026.xml"/>
<entry id="44" link="/customEntity/44.xml"/>
<entry id="9" link="/customEntity/9.xml"/>
<entry id="33" link="/customEntity/33.xml"/>
<entry id="60025" link="/customEntity/60025.xml"/>
<entry id="25851" link="/customEntity/25851.xml"/>
</entries>
</result>
A resposta da requisição será uma mensagem contendo o total de registros retornados em 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 um Cadastro Customizável específico
GET /CenterWeb/api/{$apiKey}/customEntity/{$id}.xml
Esta operação serve para puxar informações de um cadastro customizável no sistema. Veja o exemplo de retorno de uma entidade abaixo (considerando uma requisição feita em XML):
<customEntity>
<id>60026</id>
<description>Pilotos</description>
<alternativeIdentifier>PILOTO</alternativeIdentifier>
<active>true</active>
<labelDescription>Nome</labelDescription>
<descriptionAlternativeIdentifier>ID</descriptionAlternativeIdentifier>
<customFields>
<customField>
<id>9850</id>
<fieldType>A</fieldType>
<description>Equipe do Piloto</description>
...
<customField>
<customField>
<id>9858</id>
<fieldType>N</fieldType>
<description>Número do carro</description>
...
<customField>
</customFields>
</customEntity>
Descrição de um Registro do Cadastro Customizável
Busca Por Lista de Registros do Cadastro Customizável
GET /CenterWeb/api/{$apiKey}/customEntity/{id cadastro}/customEntityEntry.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:
GET /CenterWeb/api/{$apiKey}/customEntity/{id cadastro}/customEntityEntry.xml?description=134
description: pesquisar por um determinado registro do cadastro customizável com descrição = 134.
Sempre deve ser informado o id do cadastro que deseja buscar os registros
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>customEntityEntry</resourceName>
<size>3</size>
<entries>
<entry id="2576" link="/customEntity/60026/customEntityEntry/2576.xml"/>
<entry id="2577" link="/customEntity/60026/customEntityEntry/2577.xml"/>
<entry id="2575" link="/customEntity/60026/customEntityEntry/2575.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. Nesse caso está retornando os registros do cadastro customizável = 60026.
Busca de um Registro do Cadastro Customizável específico
GET /CenterWeb/api/{$apiKey}/customEntity/{id cadastro}/customEntityEntry/{id cadastro}.xml
Esta operação serve para puxar informações de um cadastro customizável no sistema.
Veja o exemplo de retorno de uma entidade abaixo utilizando o id interno do cadastro e registro (considerando uma requisição feita em XML):
<customEntityEntry>
<id>2576</id>
<description>Alonso</description>
<alternativeIdentifier>2</alternativeIdentifier>
<active>true</active>
<customFields>
<NroKart>12</NroKart>
<Equipe>Ferrari</Equipe>
</customFields>
</customEntityEntry>
GET /CenterWeb/api/{$apiKey}/customEntity/alternativeIdentifier/{id alternativo cadastro}/customEntityEntry/alternativeIdentifier/{id alternativo cadastro}.xml
Esta operação serve para puxar informações de um cadastro customizável no sistema.
Veja o exemplo de retorno de uma entidade abaixo utilizando o id alternativo do cadastro e registro (considerando uma requisição feita em XML):
<customEntityEntry>
<id>56581534</id>
<description>123</description>
<alternativeIdentifier>123</alternativeIdentifier>
<active>true</active>
<customFields>
<numero__da__nota__fiscal>1234</numero__da__nota__fiscal>
</customFields>
</customEntityEntry>
Inclusão de um Registro do Cadastro Customizável
Utilizando id interno:
POST /CenterWeb/api/{$apiKey}/customEntity/{id cadastro}/customEntityEntry.xml
Utilizando identificador alternativo:
POST /CenterWeb/api/{$apiKey}/customEntity/alternativeIdentifier/{id alternativo cadastro}/customEntityEntry.xml
Esta operação serve para incluir um registro para o cadastro customizável no sistema. Existe um mínimo de informações que o sistema espera receber para poder realizar a criação de um novo registro no ambiente em questão. Confira a descrição de um registro de cadastro customizável para identificar os campos obrigatórios. Veja um exemplo da requisição com dados em XML:
<customEntityEntry>
<description>Vettel</description>
<alternativeIdentifier>1</alternativeIdentifier>
<customFields>
<NroKart>1</NroKart>
<Equipe>Red Bull</Equipe>
</customFields>
</customEntityEntry>
Neste caso, lendo o que está sendo pedido ao uMov.me é que seja criado um registro para um cadastro customizável, utilizando os custom fields NroKart e Equipe. Nesse caso, está sendo criado o cadastro de piloto Vettel.
Alteração de um Registro do Cadastro Customizável
Utilizando id interno:
POST /CenterWeb/api/{$apiKey}/customEntity/{id cadastro}/customEntityEntry/{id registro}.xml
Utilizando identificador alternativo:
POST /CenterWeb/api/{$apiKey}/customEntity/{id alternativo cadastro}/customEntityEntry/alternativeIdentifier/{id alternativo registro}.xml
Esta operação serve para alterar um registro do cadastro customizável no sistema.
Inclusão e atualização em Lote de Registro de Cadastro Customizável
POST /CenterWeb/api/{$apiKey}/batch/customEntity/alternativeIdentifier/{IdAlternativo}/customEntityEntries.xml
Esta operação serve para incluir ou atualizar vários registros para o cadastro customizável no sistema. Existe um mínimo de informações que o sistema espera receber para poder realizar a criação ou atualização de um registro no ambiente em questão. Confira a descrição de um registro de cadastro customizável para identificar os campos obrigatórios. Veja um exemplo da requisição com dados em XML:
data=
<customEntityEntries>
<customEntityEntry>
<active>true</active>
<description>Exemplo 1</description>
<alternativeIdentifier>exemplo_1</alternativeIdentifier>
<customFields>
<id_alternativo_custom_field>valor do custom field</id_alternativo_custom_field>
</customFields>
</customEntityEntry>
<customEntityEntry>
<active>true</active>
<description>Exemplo 2</description>
<alternativeIdentifier>exemplo_1</alternativeIdentifier>
<customFields>
<id_alternativo_custom_field>valor do custom field</id_alternativo_custom_field>
</customFields>
</customEntityEntry>
</customEntityEntries>