Locais e relacionados (ServiceLocal (Local de Atendimento))
A API de ServiceLocal permite interagir com a parte "Onde?" do uMov.me. Neste caso conseguimos criar ou atualizar dados de locais de atendimento de um determinado ambiente através de chamadas de API.
Descrição de um Local de Atendimento
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 Locais de Atendimento
GET /CenterWeb/api/{$apiKey}/serviceLocal.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}/serviceLocal.xml?country=Spain&active=true
Esta requisição está pedindo todos os locais de atendimento disponíveis cujo país seja a Espanha (country=Spain) 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>serviceLocal</resourceName>
<size>3</size>
<entries>
<entry id="115" link="/agent/115.xml"/>
<entry id="130" link="/agent/130.xml"/>
<entry id="132" link="/agent/132.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.
GET /CenterWeb/api/{$apiKey}/serviceLocal.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 de um Local de Atendimento específico
GET /CenterWeb/api/{$apiKey}/serviceLocal/{$id}.xml
Este recurso serve para puxar dados de um local de atendimento específico do sistema. Veja o exemplo de retorno de uma entidade abaixo (considerando uma requisição feita em XML):
<serviceLocal>
<id>132</id>
<description>Delivery Place Sample</description>
<geoCoordinate>41.3752007, 2.1529847</geoCoordinate>
<country>Spain</country>
<city>Barcelona</city>
<street>Avinguda del Paral. lel, 188</street>
<zipCode/>
<alternativeIdentifier>34</alternativeIdentifier>
<active>true</active>
<customFields>
<CNPJ>000000000/0000-00</CNPJ>
<Funcionários>200</Funcionários>
...
<customFields>
</serviceLocal>
Inclusão de um Local de Atendimento
POST /CenterWeb/api/{$apiKey}/serviceLocal.xml
Este recurso serve para incluir um local de atendimento 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 local de atendimento para identificar os campos obrigatórios. Veja um exemplo da requisição com dados em XML:
<serviceLocal>
<description>Delivery Place New</description>
<country>Spain</country>
<city>Barcelona</city>
<street>Avinguda del Paral. lel, 188</street>
<zipCode/>
<alternativeIdentifier>674</alternativeIdentifier>
<active>true</active>
<image>
<imageUrlImport>http://www.testeimagem.jpg</imageUrlImport>
</image>
<accountable>
<id>código_agente</id>
</accountable>
<itemsRelationship>
<item>
<alternativeIdentifier>identifier</alternativeIdentifier>
</item>
</itemsRelationship>
<customFields>
<CNPJ>000000000/0000-00</CNPJ>
<Funcionários>200</Funcionários>
...
<customFields>
</serviceLocal>
Neste caso, lendo o que está sendo pedido ao uMov.me é que seja criado um local de atendimento com descrição "Delivery Place New", no país Espanha, cidade Barcelona, na rua "Avinguda del Paral. lel, 188". Além disto, está sendo dito que o local de atendimento em questão está sendo criado ativo, que o identificador dele no sistema de origem é 674. Também está sendo dito que neste local será vinculado um item com identificador alternativo identifier.
Uma vez não informado altitude e longitude através do parâmetro(geoCoordinate) o uMov.me irá tentar obter tais coordenadas baseado no endereço cadastrado. Caso o endereço for inválido, a informação não será preenchida.
Inclusão e atualização de Locais de Atendimento em lote
POST /CenterWeb/api/{$apiKey}/batch/serviceLocals.xml
Este recurso permite fazer a criação e atualização de locais em lote, sem que haja a necessidade de fazer inúmeras requisições para a api.
<serviceLocals>
<serviceLocal>
<description>Delivery Place New</description>
<country>Spain</country>
<city>Barcelona</city>
<street>Avinguda del Paral. lel, 188</street>
<zipCode/>
<alternativeIdentifier>674</alternativeIdentifier>
<active>true</active>
<image>
<imageUrlImport>http://www.testeimagem.jpg</imageUrlImport>
</image>
<accountable>
<id>código_agente</id>
</accountable>
<itemsRelationship>
<item>
<alternativeIdentifier>identifier</alternativeIdentifier>
</item>
</itemsRelationship>
<customFields>
<CNPJ>000000000/0000-00</CNPJ>
<Funcionários>200</Funcionários>
...
<customFields>
</serviceLocal>
<serviceLocal>
<description>Delivery Place New</description>
<country>Spain</country>
<city>Barcelona</city>
<street>Avinguda del Paral. lel, 188</street>
<zipCode/>
<alternativeIdentifier>674</alternativeIdentifier>
<active>true</active>
<image>
<imageUrlImport>http://www.testeimagem.jpg</imageUrlImport>
</image>
<accountable>
<id>código_agente</id>
</accountable>
<itemsRelationship>
<item>
<alternativeIdentifier>identifier</alternativeIdentifier>
</item>
</itemsRelationship>
<customFields>
<CNPJ>000000000/0000-00</CNPJ>
<Funcionários>200</Funcionários>
...
<customFields>
</serviceLocal>
</serviceLocals>
Atualização de Locais de Atendimento em lote
Esse recurso permite apenas atualizar valores através da API em um custom field do tipo lista múltipla alimentado por dataset, utilizando o identificador alternativo do campo, em requisições batch.
POST /CenterWeb/api/{$apiKey}/batch/serviceLocals.xml
data=
<serviceLocals>
<serviceLocal>
<alternativeIdentifier>33</alternativeIdentifier>
<active>true</active>
<corporateName>BAR DO TOREZANI</corporateName>
<description>MARTA MARGARETTI DEPIANTE TOREZANI</description>
<country>Brasil</country>
<city>COLATINA</city>
<street>AV. ANTONIO PERUTTI, 143</street>
<streetComplement>PERTO DO MINI SUPER</streetComplement>
<cityNeighborhood>HONORIOFRAGA</cityNeighborhood>
<zipCode>29704-670</zipCode>
<phoneIdd>55</phoneIdd>
<cellphoneIdd>55</cellphoneIdd>
<email></email>
<cellphoneNumber></cellphoneNumber>
<phoneNumber>2737216261</phoneNumber>
<accountable><alternativeIdentifier>8828</alternativeIdentifier></accountable>
<customFields><CLI_TRANSP><alternativeIdentifier>1</alternativeIdentifier>
</CLI_TRANSP><CLI_TIPO_FRETE><alternativeIdentifier>1</alternativeIdentifier>
</CLI_TIPO_FRETE><CLI_FORMA_PAGTO><alternativeIdentifier>1</alternativeIdentifier>
</CLI_FORMA_PAGTO><LOC_PED><alternativeIdentifier>248812|34878|8251|8250</alternativeIdentifier></LOC_PED><CLI_NF>
<alternativeIdentifier>683089|681828|678061|677987</alternativeIdentifier>
</CLI_NF><TIPO_EMPRESA>B</TIPO_EMPRESA></customFields>
</serviceLocal>
</serviceLocals>
Atualização de um Local de Atendimento
Ambas as operações abaixo fazem com que os dados de um local de atendimento possam ser modificados no sistema. Desta forma é possível atualizar informações de um local de atendimento através do id interno ou então através do identificador alternativo. O xml de exemplo abaixo modifica apenas os dados desejados.
Utilizando id interno
POST /CenterWeb/api/{$apiKey}/serviceLocal/{$id}.xml
Utilizando identificador alternativo
POST /CenterWeb/api/{$apiKey}/serviceLocal/alternativeIdentifier/{$alternativeIdentifier}.xml
<serviceLocal>
<alternativeIdentifier>34</alternativeIdentifier>
<image>
<imageUrlImport>http://www.testeimagem.jpg</imageUrlImport>
</image>
<accountable>
<id>código_agente</id>
</accountable>
</serviceLocal>
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</description>
<customFields>
<status>
<alternativeIdentifier>0|1</alternativeIdentifier>
</status>
</customFields>
Operações usando HTTP POST
Ao criar ou atualizar um agente você precisa em sua requisição POST identificar os dados do agente utilizando um parametro com o nome data. Segue um exemplo disparando a requisição a partir de um formulário HTML:
<html>
<form method="POST" action="http://api.umov.me/CenterWeb/api/{$apiKey}/serviceLocal/{$id}.xml">
<input type="text" name="data" value="<serviceLocal><alternativeIdentifier>34</alternativeIdentifier></serviceLocal>" />
<input type="submit" />
</form>
</html>
Busca de um Local de Atendimento específico através do identificador alternativo
GET /CenterWeb/api/{$apiKey}/serviceLocal/alternativeIdentifier/{$alternativeIdentifier}.xml
Este recurso serve para bucar todos os dados de um local de atendimento específico do sistema através do seu identificador alternativo. Veja o exemplo de retorno de uma entidade abaixo (considerando uma requisição feita em XML):
<serviceLocal>
<id>1760479</id>
<description>GNU</description>
<active>false</active>
<alternativeIdentifier>gnu</alternativeIdentifier>
<corporateName>gremio</corporateName>
<country>Brasil</country>
<state>RS</state>
<city>Porto ALegre</city>
<cityNeighborhood>são joão</cityNeighborhood>
<streetType/>
<street/>
<streetComplement/>
<zipCode/>
<email/>
<observation/>
<geoCoordinate>-30.0277041, -51.228734599999996</geoCoordinate>
<origin>1</origin>
<insertDateTime>2013-04-17 17:44:19</insertDateTime>
<agentInsert>
<id>36324</id>
<name>lucas</name>
<login>lucas</login>
<active>true</active>
<alternativeIdentifier>kubiaki</alternativeIdentifier>
<validateClient>0</validateClient>
<centerwebUser>true</centerwebUser>
<centerwebUserRole>D</centerwebUserRole>
<mobileUser>true</mobileUser>
<biUser>true</biUser>
<biUserRole>0</biUserRole>
<inputWebAsAnotherUser>true</inputWebAsAnotherUser>
<observation/>
<country/>
<state/>
<city/>
<neighborhood/>
<streetType/>
<street/>
<streetComplement/>
<exportStatus>false</exportStatus>
<viewServiceLocal>false</viewServiceLocal>
<lockLoginInChangeImei>false</lockLoginInChangeImei>
</agentInsert>
<lastUpdateDateTime>2013-07-17 10:27:53</lastUpdateDateTime>
<agentLastUpdate>
<id>36324</id>
<name>lucas</name>
<login>lucas</login>
<active>true</active>
<alternativeIdentifier>kubiaki</alternativeIdentifier>
<validateClient>0</validateClient>
<centerwebUser>true</centerwebUser>
<centerwebUserRole>D</centerwebUserRole>
<mobileUser>true</mobileUser>
<biUser>true</biUser>
<biUserRole>0</biUserRole>
<inputWebAsAnotherUser>true</inputWebAsAnotherUser>
<observation/>
<country/>
<state/>
<city/>
<neighborhood/>
<streetType/>
<street/>
<streetComplement/>
<recordComplement1/>
<recordComplement2/>
<recordComplement3/>
<recordComplement4/>
<recordComplement5/>
<exportStatus>false</exportStatus>
<viewServiceLocal>false</viewServiceLocal>
<lockLoginInChangeImei>false</lockLoginInChangeImei>
</agentLastUpdate>
<customFields>
<CNPJ>000000000/0000-00</CNPJ>
<Funcionários>200</Funcionários>
...
<customFields>
</serviceLocal>