Manual de Integrao

Buscap XML

ndice #
1. Objetivo do documento ............................................................... 3 2. Pr-requisitos ................................................................................. 3 3. Para que serve? ............................................................................... 3 4. Como saber se um XML capturvel? ....................................... 3 5. Como deve ser a estrutura de um XML? ................................... 5 6. Campos extras ................................................................................. 9 7. Casos especiais Diviso de XML ............................................ 10

_Manual de Integrao
Buscap XML

1. Objetivo do documento
Fornecer todas as instrues para que um canal (ex. plataforma de lojas) realize a integrao com o Buscap para a gerao do arquivo XML contendo as ofertas do lojista no formato correto, de tal forma a habilit-la na sua base de lojas.

2. Pr-requisitos
_ Esta integrao se aplica somente a lojas que estiverem cadastradas no Buscap, atravs da Central de Negcios CN (http://negocios.buscapecompany.com.br/) que esto conguradas para captura automtica atravs de uma URL que aponta para o arquivo XML contendo as ofertas do lojista. _ Fornecer o contedo XML compacto. Zip, GZip ou compatvel.

3. Para que serve?

O XML possui diversas nalidades: Interagem com outras linguagens como JSP, em Banco de Dados, troca de informaes entre sistemas entre outras. Para o Buscap, o XML que o lojista ir fornecer possui informaes relacionadas OFERTA que ele quer publicar no site, onde o nosso rob - denominado Spider acessa e extrai todas as informaes necessrias das ofertas.

4. Como saber se um XML capturvel?

As informaes mnimas que devem ser fornecidas de uma oferta para que o XML seja capturvel so: 1 - Link de detalhes da oferta 2 - Preo (os centavos devem ser separados por vrgula e com duas casa decimais. Ex.: 10,00) 3 - Ttulo da oferta 4- URL imagem 5- Categoria na qual o oferta pertence

Este documento de propriedade do Buscap Company . Todos os direitos reservados. Documento Condencial.

_Manual de Integrao
Buscap XML
Para lojistas que vendem produtos de moda e acessrios, existem outros itens que so obrigatrios: 1- Cor 2- Tamanho Sendo opcionais: 1 - Parcelamento 2 - Id Oferta 3 - Modelo do produto 4 - Marca do produto O item de parcelamento deve estar no seguinte formato para que ele seja compreendido pelo nosso sistema: Exemplo, uma oferta no valor de R$ 100,00 parcelado em 10 prestaes: _ 10x de R$ 10,00 O item de Id oferta um campo que poder ser ou no alfanumrico, que possui duas nalidades: _ Utiliz-lo como um meio de diferenciar as ofertas; _ Colocao da oferta no PRODUTO NICO de maneira automtica, o que ns chamamos de vnculo. Quando utilizado com o intuito de diferenciar as ofertas, seu Id adicionado na descrio junto com a palavra cod..

Este documento de propriedade do Buscap Company . Todos os direitos reservados. Documento Condencial.

_Manual de Integrao
Buscap XML

5. Como deve ser a estrutura de um XML?

Para o Buscap, temos um modelo conceitual que deve ser seguido. Caso voc possua outro padro de XML, analisaremos para conrmar se est nos padres para a captura.
<?xml version=1.0 encoding=ISO-8859-1?> <!-- Generated at 2012-08-06T09:15:30GMT-3--> <lojaxyz> <produtos> <produto> . . . </produtos> </lojaxyz> <descricao>Nome/titulo do Oferta</descricao> <preco>Preo do Oferta</preco> <id_oferta>Cdigo nico da oferta, geralmente pertencente a uma nica <link_prod>Link de Detalhes</link_prod> <imagem>Link da imagem do Oferta</imagem> <categoria>Categoria da Oferta, o mais completo possvel e o mais relevante <parcelamento>Nmero de parcelas e o valor de cada parcela</ <disponibilidade>Quantidade desta oferta em estoque</disponibilidade>

oferta.</id_oferta>

possvel</categoria> parcelamento> </produto>

Este documento de propriedade do Buscap Company . Todos os direitos reservados. Documento Condencial.

_Manual de Integrao
Buscap XML
Para lojistas que vendem produtos de moda e acessrios, a estrutura do XML com as tags cor e tamanho ca da seguinte maneira:
<?xml version=1.0 encoding=ISO-8859-1?> <!-- Generated at 2012-08-06T09:15:30GMT-3--> <lojaxyz> <produtos> <produto> . . . </produtos> </lojaxyz> <descricao>Nome/titulo do Oferta</descricao> <preco>Preo do Oferta</preco> <id_oferta>Cdigo nico da oferta, geralmente pertencente a uma nica <link_prod>Link de Detalhes</link_prod> <imagem>Link da imagem do Oferta</imagem> <categoria>Categoria da Oferta, o mais completo possvel e o mais relevante <cor>Cor do produto ou acessrio<cor> <tamanho>Tamanho do produto ou acessrio</tamanho> <parcelamento>Nmero de parcelas e o valor de cada parcela</ <disponibilidade>Quantidade desta oferta em estoque</disponibilidade>

oferta.</id_oferta>

possvel</categoria>

parcelamento> </produto>

As tags no precisam estar necessariamente nessa ordem, mas devem conter as informaes j descritas anteriormente e estarem dentro de uma estrutura correta para um XML bem formatado. Como podemos observar, as informaes da oferta fazem parte do sub conjunto da tag <produto>. Sem essa estrutura no possvel realizar a captura, pois o sistema Spider no ir conseguir identicar onde comea e termina uma oferta.

Este documento de propriedade do Buscap Company . Todos os direitos reservados. Documento Condencial.

_Manual de Integrao
Buscap XML
EXEMPLO:
<?xml version=1.0 encoding=ISO-8859-1?> <!-- Generated at 2012-08-06T09:15:30GMT-3--> <lojaxyz> <produtos> <produto> <descricao>Cmera Digital Sony Cyber Shot ABC123</descricao> <preco>R$ 200,00</preco> <id_oferta>5896179</id_oferta> <link_prod>http://www.lojaxyz.com.br/prod/5896179/sony-cyber-shot<imagem>http://www.lojaxyz.com.br/imagem/5896179.jpg</imagem> <categoria>Eletrnicos > Cmera Digital </categoria> <parcelamento> 10x de R$ 20,00</parcelamento> <disponibilidade>25</disponibilidade>

abc123</link_prod>

</produto> <produto> . . . </produtos> <lojaxyz> <descricao>Filmadora Sony XYZ</descricao> <preco>R$ 1200,00</preco> <id_oferta>6789354</id_oferta> <link_prod>http://www.lojaxyz.com.br/prod/6789354/sony-XYZ</link_prod> <imagem>http://www.lojaxyz.com.br/imagem/6789354.jpg</imagem> <categoria>Eletrnicos > Filmadora</categoria> <parcelamento> 4x de R$ 300,00</parcelamento> <disponibilidade>12</disponibilidade> </produto>

IMPORTANTE: Apesar da exibilidade para a criao do XML, h um item que deve ser

Este documento de propriedade do Buscap Company . Todos os direitos reservados. Documento Condencial.

_Manual de Integrao
Buscap XML
obrigatoriamente inserido em todos os padres do arquivo, o timestamp. Este campo, nada mais do que a data e horrio da ltima modicao ou gerao feita em seu XML. Para sua insero, h algumas normas a serem seguidas: Para o formato do timestamp utilizaremos a ISO-8601, que segundo ela, o formato da data para representar, por exemplo, o dia, 06/08/2012 e o horrio 09h15m30s : 2012-08-06T09:15:30GMT-3 Sendo assim, esta data deve ser de quando o XML foi gerado ou alterado e no quando fazemos o request para o link do lojista. No Brasil temos 3 fusos horrios diferentes, portanto cabe ao lojista, em sua regio, identic-lo e represent-lo com seu time zone respectivo. YYYY-MM-DDTHH:MM:SS<time_zone> No XML, essa informao pode vir em forma de um comentrio dentro do XML conforme exemplo abaixo:
<?xml version=1.0 encoding=ISO-8859-1?> <!-- Generated at 2012-08-06T09:15:30GMT-3--> <lojaxyz> <produtos> <produto> <descricao>...</descricao> <preco>...</preco> <id_oferta>...</id_oferta> <link_prod>...</link_prod> <imagem>...</imagem> <categoria>...</categoria> <parcelamento>...</parcelamento> <disponibilidade>...</disponibilidade>

</produto> </produtos> </lojaxyz>

Este documento de propriedade do Buscap Company . Todos os direitos reservados. Documento Condencial.

_Manual de Integrao
Buscap XML
Nesta representao, o timestamp ca logo no inicio do XML antes da tag raiz inicial (<lojaxyz> neste exemplo acima).

6. Campos extras
Tambm possumos campos extras para suprir necessidades especiais, exemplicadas a seguir: _ Cdigo de barras: Cdigo numrico UPC/EAN/GTIN _ ISBN: 13 ou 10 dgitos _ Detalhes: Maiores informaes sobre a oferta _ Data estoque: no formato dd/mm/aaaa _ Id lial: Cdigo nico que identica a lial
<codigo_barra>Cdigo de Barra numrico, se mais de um, separar por vrgula</codigo_barra> <isbn>Cdigo do ISBN se for livro</isbn> <detalhes>Os sub-ns existentes nesse campo variam de acordo com cada caracterstica das ofertas</detalhes> <data_estoque>data de atualizao da informao do estoque desta oferta</dt_ estoque> <id_filial>Cdigo nico que identifica o filial, o mesmo usado no cadastro na CN</ id_filial>

Este documento de propriedade do Buscap Company . Todos os direitos reservados. Documento Condencial.

_Manual de Integrao
Buscap XML

7. Casos especiais Diviso de XML

Em alguns casos especiais, necessria a diviso das ofertas em partes menores para que a Spider consiga capturar o XML inteiro. No caso de XMLs com um volume superior a 10mb, necessria a diviso desse contedo em outras partes menores para que seja possvel processar todas as ofertas em partes, ao invs de um arquivo nico. Com essa diviso, espera-se que esses arquivos menores tenham no mximo 2000 (duas mil) ofertas, reduzindo assim a quantidade de itens a serem processados numa nica vez. Se seu XML for grande demais e sua plataforma ou voc no consiga divid- lo em partes menores, ns conseguimos fazer isso atravs de uma ferramenta interna. Porm, para isso necessrio que sejamos avisados desta necessidade. Para que o XML seja dividido em partes menores e que a Spider consiga acessar todas as outras partes, recomenda-se criar uma pgina inicial que indique onde esto cada uma das partes. Assim, em uma pgina inicial HTML simples, os links para os XMLs divididos devem estar conforme o formato do exemplo abaixo, formando um sumrio: <a href =http://www.minhaloja.com.br/xmls/meu_xml1.xml>1</a> <a href =http://www.minhaloja.com.br/xmls/meu_xml2.xml>2</a> <a href =http://www.minhaloja.com.br/xmls/meu_xml3.xml>3</a> <a href =http://www.minhaloja.com.br/xmls/meu_xml4.xml>4</a> <a href =http://www.minhaloja.com.br/xmls/meu_xml5.xml>5</a> <a href =http://www.minhaloja.com.br/xmls/meu_xml6.xml>6</a> No necessrio criar um ltimo item, indicando que nalizou-se as partes, basta garantir que todas as partes foram indicadas no sumrio e existam no endereo indicado.

Este documento de propriedade do Buscap Company . Todos os direitos reservados. Documento Condencial.

10