API & Documentação
A API (Interface de Programação de Aplicativos) da Lomadee é um conjunto de funções e padrões estabelecidos para criação de aplicativos customizados, em que há necessidade de uso da base de dados de produtos, ofertas e serviços oferecidos pela Lomadee.
Como funciona?
Para integrar à API da Lomadee é necessário primeiramente obter um ID para sua aplicação, que deverá ser usado em todas as requisições feitas ao serviço que for solicitado. É através deste ID que é feita a medição do rendimento da sua aplicação.
Todos os serviços utilizam a tecnologia REST no tratamento de requisições. Desta forma é possível construir facilmente uma URL para ser executada em seu navegador, linha de comando ou código.
A URL é constituída basicamente da seguinte forma:
Onde:
- HostName: URL principal do webservice
- ServiceName: Nome do serviço
- API: Nome da API
- ApplicationId: ID da aplicação
- CountryCode: Código do país
- Parameters: Parâmetros do serviço
O formato padrão de resposta é em XML, mas existe a opção de utilizar o JSON, que por sua vez ajuda na integração de tecnologias com JavaScript e Flash de maneira fácil e extremamente ágil.
Formato de requisição
A tecnologia REST é a única utilizada em todas os serviços da API da Lomadee no tratamento de requisições.
Visão Geral
Transferência de Estado Representacional (Representational State Transfer) ou somente REST é uma técnica de engenharia de software para sistemas distribuídos, que descreve uma interface web simples que utiliza XML, HTTP, JSON ou texto puro, sem abstrações adicionais dos protocolos baseados em padrões de troca de mensagem como o SOAP.
Exemplo de requisição usando REST
Na URL acima usamos o serviço findProductList da API da Lomadee, que permite pesquisar por uma lista de produtos através do ID da categoria final e/ou de um conjunto de palavras-chaves. O termo application_id refere-se ao ID da sua aplicação cadastrada para requisições à API da Lomadee e o parâmetro keyword é a palavra chave buscada entre os produtos.
Através desta URL de requisição, a API da Lomadee lhe retornará um XML com uma lista de produtos com a palavra-chave usada.
Formatos de retorno
Pode-se usar XML e/ou JSON como formatos de retorno da API da Lomadee.
Visão geral
XML (eXtensible Markup Language) é a linguagem de marcação padrão no retorno da API da Lomadee, pois com ela o desenvolvedor consegue lidar com os dados, independente da linguagem de programação. Também temos a opção de usar o JSON ( JavaScript Object Notation) que é um subconjunto da notação de objeto JavaScript, mas seu uso não requer JavaScript exclusivamente.
Exemplo de retorno no formato XML
Usando o serviço findProductList da API da Lomadee, buscaremos uma lista de produtos da categoria 77 que é referente a celulares.
Com a requisição acima, o seguinte XML é retornado:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Result xmlns="urn:buscape" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" match="all" page="1" totalPages="39" totalResultsReturned="16" totalResultsAvailable="617" xsi:schemaLocation="http://developer.buscape.com/admin/lomadee.xsd">
<details>
<applicationID>564771466d477a4458664d3d</applicationID>
<applicationVersion>1.0.0.0</applicationVersion>
<applicationPath>http://bws-apps.buscape.com/mobile/update</applicationPath>
<date>2010-10-19T14:09:05.997-03:00</date>
<elapsedTime>2</elapsedTime>
<status>success</status>
<code>0</code>
<message>success</message>
</details>
<category hasOffer="false" isFinal="true" parentCategoryId="6420" id="77">
<thumbnail url="http://imagem2.buscape.com.br/bp5/categorias/77.jpg"/>
<links>
<link type="category" url="http://compare.buscape.com.br/celular-e-smartphone.html?mdsrc=9262544"/>
<link type="xml" url="http://sandbox.buscape.com/service/findProductList/564771466d477a4458664d3d/?categoryId=77&sourceId=9262544"/>
</links>
<name>Celular e Smartphone</name>
</category>
<product id="235052" categoryId="77" totalSellers="2" fullDescription="false">
<productName>LG GT350 Cookie Messenger GSM Desbloqueado</productName>
<productShortName>LG GT350 Cookie Messenger Desbloqueado</productShortName>
<currency abbreviation="BRL"/>
<priceMin>399.00</priceMin>
<priceMax>399.00</priceMax>
<links>
<link type="product" url="http://compare.buscape.com.br/lg-gt350-cookie-messenger-gsm-desbloqueado.html?mdsrc=9262544"/>
<link type="specification" url="http://compare.buscape.com.br/prod_ficha?idu=235052"/>
<link type="xml" url="http://sandbox.buscape.com/service/findOfferList/564771466d477a4458664d3d/?productId=235052&sourceId=9262544"/>
</links>
<thumbnail url="http://imagem2.buscape.com.br/thumbs/ensopado/77/190x190_235052_1.jpg"/>
<rating>
<userAverageRating>
<numComments>36</numComments>
<rating>8.4</rating>
<links>
<link type="xml" url="http://sandbox.buscape.com/service/viewUserRatings/564771466d477a4458664d3d/?productId=235052&sourceId=9262544"/>
</links>
</userAverageRating>
</rating>
<specification>
<links>
<link type="xml" url="http://sandbox.buscape.com/service/viewProductDetails/564771466d477a4458664d3d/?productId=235052&sourceId=9262544"/>
</links>
<item label="Câmera">
<value>3.15 MP</value>
</item>
<item label="Funções Extras">
<value>Grava Video</value>
<value>Gravador de Voz</value>
<value>Java</value>
<value>MP3 Player</value>
<value>Rádio</value>
<value>Reproduz Video</value>
<value>Viva Voz</value>
</item>
<item label="Slots de Expansão">
<value>MicroSD</value>
</item>
<item label="Tipos de Conexão">
<value>Bluetooth</value>
<value>EDGE</value>
<value>GPRS</value>
<value>Micro-USB</value>
<value>WAP</value>
</item>
</specification>
</product>
</Result>
Exemplo de retorno no formato JSON
Para usar JSON como método de retorno da sua aplicação, deve-se utilizar o parâmetro &format=json para informar ao webservice o formato de retorno requerido.
Podemos também, em formato JSON, informar o nome de uma função JavaScript para ser executada assim que o webservice responder.
O parâmetro &callBack=_cb diz ao webservice para retornar _cb("resposta json"). Usar esse parâmetro não requer ao desenvolvedor utilizar a função eval("resposta json") do JavaScript para gerar o objeto. Com isso o desenvolvedor evita problemas de segurança relacionados ao uso do eval() caso o conteúdo da resposta não seja confiável.
Veja abaixo uma representação gráfica de uma aplicação JSON utilizando a função callBack:
- HTML executa o javascript.
- JavaScript faz um request do serviço de lista de categorias.
- Serviço recebe a requisição e busca a lista de categorias da Lomadee.
- Serviço retorna a lista de categorias no formato JSON para o javascript.
- Javascript executa a função _cb(obj).
- Função _cb(obj) retorna uma tabela HTML com a lista de nomes das categorias.
Filtros
Os filtros são opções dos produtos (PUs) que asseguram que neles contenham determinada característica, como por exemplo, um determinado processador ou sistema operacional para notebooks, uma marca para celular, etc.
A utilização do filtro é muito mais confiável do que filtro por palavra-chave (keywords).
A categoria precisa ser final e ter PU.
No XML, são exibidos todos os filtros disponíveis para cada categoria.
Exemplo – Filtros disponíveis para a categoria 77 – Celular:
<value value="Motorola" id="6325"/>
<value value="Samsung" id="6327"/>
<value value="LG" id="6328"/>
<value value="Nokia" id="6326"/>
<value value="Sony Ericsson" id="115882"/>
<value value="Desbloqueado" id="50873"/>
<value value="Tim" id="6443"/>
<value value="Vivo" id="6444"/>
<value value="Claro" id="6441"/>
<value value="Nextel" id="311071"/>
<value value="Oi" id="6442"/>
Para utilizar os filtros na listagem de produtos, adicionamos o parâmetro:
Para filtrar pela marca Nokia em celular, ficaria: specId1117=6326. Em que 1117 é o id do filtro “Marca” e 6326 é o id do value “Nokia”.
Exemplo – Listagem de produtos da categoria 77 – Celular, filtrados pela marca Nokia.
Nokia X2 GSM Desbloqueado
Nokia X2 Desbloqueado
<currency abbreviation="BRL"/>
313.66
399.00
Nokia N8 GSM Desbloqueado
Nokia N8 Desbloqueado
<currency abbreviation="BRL"/>
1249.99
1599.00
Produtos ECO
Define se o produto possui característica Eco Sustentável, como por exemplo TV de Tela LED com economia de energia. Inclusive alguns produtos possuem filtros por essa característica.
No XML, o produto possui uma tag “eco”, indicando true ou false;
Para filtrar pela característica Eco Sustentável em celular, ficaria: specId4660=303057. Onde 4660 é o id do filtro “Característica Eco Sustentável” e 303057 é o id do value “LCD sem mercúrio”
Exemplo – Listagem de produtos da categoria 77 – Celular, filtrados pela característica Eco e LCD sem mercúrio:
Apple iPhone 3Gs 16GB GSM Desbloqueado
Apple iPhone 3Gs 16GB Desbloqueado
<currency abbreviation="BRL"/>
1699.00
1699.00
Apple iPhone 4 16GB GSM Desbloqueado
Apple iPhone 4 16GB Desbloqueado
<currency abbreviation="BRL"/>
2199.00
2199.00
Conteúdo de outros países
A API da Lomadee oferece a opção de retornar conteúdo de um determinado país, desde que seja suportado pela API e pelo serviço utilizado.
Veja abaixo o formato da URL de requisição a ser usado:
No lugar de <country_code> coloque o código do países que deseja. Veja abaixo todos os países aceitos pela API.
Caso nenhum país seja informado, o conteúdo padrão será do Brasil.
Documentação
-
Aplicativos Oficiais Lomadee
Crie um sourceId (código) para o Publisher que deseja utiliza-lo. -
Lista de ofertas
Busque todas as ofertas de um determinado produto, filtrando-os por avaliação da loja, preço ou popularidade. -
Lista de produtos
Busque produtos por uma ou mais palavras-chaves ou ID da categoria. -
Anunciantes
Encontre na lista todas as empresas anunciantes da Lomadee.
Informações importantes
- O uso de codificação UTF-8 ajuda para que os acentos sejam exibidos corretamente.
- Por questão de segurança e performance, todas as aplicações estão limitadas a 2.000 consultas por IP em um período de 24 horas.
Infraestrutura de hospedagem de aplicativos
O Buscapé irá hospedar todos os aplicativos distribuídos dentro da Lomadee. Hoje já está disponível a hospedagem para aplicações Java e PHP.
Para hospedagem Java, é disponibilizado uma jvm dedicada com 70Mb de memória RAM, Java 6 e Tomcat 6.0.20.
Para hospedagem PHP, é disponibilizado o PHP 5.2.14.
