Itens e relacionados (Item (Item))
A API de item permite interagir com a parte "O Quê?" do uMov.me.
Descrição de um Item
OBS:
- Para atualização de cadastro, somente o identificador alternativo é obrigatório.
- Para a inclusão de campos customizáveis do tipo multivalorado, leia a sessão de Inclusão/Alteração em lote de valores de Campos Customizáveis do artigo Custom Field / Custom Field Value (Campo customizável / Valor campo customizável).
Busca por lista de Itens
GET /CenterWeb/api/{$apiKey}/item.xml
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}/item.xml?description=xyz&active=true
Esta requisição está pedindo todos os itens disponíveis cuja descrição tenha a palavra xyz presente (description=xyz) 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>item</resourceName>
<size>2</size>
<entries>
<entry id="5421" link="/item/2870.xml"/>
<entry id="5422" link="/item/2871.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.
GET /CenterWeb/api/{$apiKey}/item.xml?initialInsertDateTime=AAAA-MM-DD HH:MM:SS&finalInsertDateTime=AAAA-MM-DD HH:MM:SS
Esta requisição filtra todos os agentes que foram inseridos neste período de data e hora.
Busca por um Item específico
GET /CenterWeb/api/{$apiKey}/item/{$id}.xml
Este recurso serve para puxar dados de um item específico do sistema. Veja o exemplo de retorno de uma entidade abaixo
(considerando uma requisição feita em XML):
<item>
<id>390103</id>
<subGroup>
<id>1</id>
</subGroup>
<description>xyz</description>
<active>true</active>
<alternativeIdentifier>alternative_identifier</alternativeIdentifier>
<itemCategory>
<id>1</id>
</itemCategory>
<customFields>
<Estoque>200</Estoque>
<Preço>49.90</Preço>
...
</customFields>
</item>
Inclusão de um Item
POST /CenterWeb/api/{$apiKey}/item.xml
Este recurso serve para incluir um item no sistema. Existe um mínimo de informações que o sistema espera receber para poder realizar a criação de um novo subgrupo no ambiente em questão. Confira a descrição do item para identificar os campos obrigatórios. Veja um exemplo da requisição com dados em XML:
<item>
<subGroup><id>1*</id></subGroup>
<description>xyz</description>
<active>true</active>
<image>
<imageUrlImport>http://www.testeimagem.jpg</imageUrlImport>
</image>
<alternativeIdentifier>alternative_identifier</alternativeIdentifier>
<itemCategory><id>1**</id></itemCategory>
<customFields>
<Estoque>200</Estoque>
<Preço>49.90</Preço>
...
</customFields>
</item>
Neste caso, lendo o que está sendo pedido ao uMov.me é que seja criado um item com o campo obrigatório preenchido (descrição) e ainda, está sendo dito que o subgrupo em questão está sendo criado ativo e com o identificador dele no sistema de origem é 33456745.
*Este identificador interno é somente como exemplo. Você deve usar o subgrupo cadastrado em seu sistemas através do http://center.umov.me/CenterWeb/subGroup
**Este identificador interno é somente como exemplo. Você deve usar a categoria de ítem cadastrado em seu sistemas através do http://center.umov.me/CenterWeb/itemCategory
É possível também fazer a vinculação de categoria e subgrupo de itens através do identificador alternativo ao realizar a inclusão de um item, conforme descrito no exemplo abaixo:
<item>
<subGroup><alternativeIdentifier>Subgrupo 1</alternativeIdentifier></subGroup>
<description>xyz</description>
<active>true</active>
<image>
<imageUrlImport>http://www.testeimagem.jpg</imageUrlImport>
</image>
<alternativeIdentifier>alternative_identifier</alternativeIdentifier>
<itemCategory><alternativeIdentifier>Categoria 1</alternativeIdentifier></itemCategory>
<customFields>
<Estoque>200</Estoque>
<Preço>49.90</Preço>
...
</customFields>
</item>
Atualização de um Item específico
Este recurso serve para atualizar um item específico do sistema. Existe um mínimo de informações que o sistema espera receber para poder realizar a atualização de um item no ambiente em questão. Confira a descrição do item para identificar os campos obrigatórios. Veja os exemplos de requisições possíveis usando dados no formato XML:
Utilizando id interno
POST /CenterWeb/api/{$apiKey}/item/{$id}.xml
Utilizando identificador alternativo
POST/CenterWeb/api/{$apiKey}/item/alternativeIdentifier/{$alternativeIdentifier}.xml
<item>
<subGroup><id>1</id></subGroup>
<description>xyz</description>
<active>true</active>
<image>
<imageUrlImport>http://www.testeimagem.jpg</imageUrlImport>
</image>
<alternativeIdentifier>alternative_identifier</alternativeIdentifier>
<itemCategory><id>1</id></itemCategory>
<customFields>
<Estoque>200</Estoque>
<Preço>49.90</Preço>
...
</customFields>
</item>
Neste caso, lendo o que está sendo pedido ao uMov.me é que seja atualizada as informações do item, usando ou o id interno ou o identificador alternativo do item.
Selecionando valores de um custom fields do tipo lista.
POST /CenterWeb/api/{$apiKey}/item.xml
Basta declarar a tag alternativeIdentifier dentro do campo customizável e informar os valores separados por '|' (pipe).
ServiceLocal com campo de lista múltipla de status:
<serviceLocal>
<description>Local do capiroto</description>
<customFields>
<status>
<alternativeIdentifier>0|1</alternativeIdentifier>
</status>
</customFields>
Inclusão e atualização de itens em lote
POST /CenterWeb/api/{$apiKey}/batch/items.xml
Este recurso permite fazer a criação e atualização de itens em lote, sem que haja a necessidade de fazer inúmeras requisições para a api.
<items>
<item>
<subGroup><id>1</id></subGroup>
<description>abc</description>
<active>true</active>
<alternativeIdentifier>alternative_identifier1</alternativeIdentifier>
<itemCategory><id>1</id></itemCategory>
<customFields>
<Estoque>200</Estoque>
<Preço>49.90</Preço>
...
</customFields>
</item>
<item>
<subGroup><id>1</id></subGroup>
<description>xyz</description>
<active>true</active>
<alternativeIdentifier>alternative_identifier2</alternativeIdentifier>
<itemCategory><id>1</id></itemCategory>
<customFields>
<Estoque>200</Estoque>
<Preço>49.90</Preço>
...
</customFields>
</item>
</items>
A seção "<item></item>" representa cada item a ser inserido e pode ser replicada quantas vezes forem necessárias.
Caso algum erro ocorra, toda a operação será abortada e nenhum item será inserido.
Como retorno a esta chamada o sistema apresenta o link de acesso para cada item criado. No link é mostrado o id interno e o identificador alternativo de cada registro a fim de identificar melhor qual o ID gerado para cada item criado.
<result>
<resourceName>items</resourceName>
<size>2</size>
<entries>
<entry id="1401792" alternativeIdentifier="alternative_identifier1" link="/item/1401792.xml" />
<entry id="1401793" alternativeIdentifier="alternative_identifier2" link="/item/1401793.xml" />
</entries>
</result>
Busca por um Item específico através do identificador alternativo
GET /CenterWeb/api/{$apiKey}/item/alternativeIdentifier{$alternative identifier}.xml
Este recurso serve para puxar dados de um item específico do sistema. Veja o exemplo de retorno de uma entidade abaixo (considerando uma requisição feita em XML):
<item>
<id>1421216</id>
<subGroup>
<id>513496</id>
<description>sub1</description>
<alternativeIdentifier>sub_1</alternativeIdentifier>
<active>true</active>
</subGroup>
<description>itemTest</description>
<alternativeIdentifier>ID_item</alternativeIdentifier>
<customFields>
<Estoque>200</Estoque>
<Preço>49.90</Preço>
...
</customFields>
</item>