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 configuradas 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 finalidades: 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 Confidencial.

_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
finalidades:
_ 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 Confidencial.

_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 confirmar 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>

<descricao>Nome/titulo do Oferta</descricao>

<preco>Preo do Oferta</preco>

<id_oferta>Cdigo nico da oferta, geralmente pertencente a uma nica

oferta.</id_oferta>

<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

possvel</categoria>

<parcelamento>Nmero de parcelas e o valor de cada parcela</

parcelamento>

<disponibilidade>Quantidade desta oferta em estoque</disponibilidade>

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

Este documento de propriedade do Buscap Company .

Todos os direitos reservados. Documento Confidencial.

_Manual de Integrao
Buscap XML

Para lojistas que vendem produtos de moda e acessrios, a estrutura do XML com
as tags cor e tamanho fica da seguinte maneira:
<?xml version=1.0 encoding=ISO-8859-1?>
<!-- Generated at 2012-08-06T09:15:30GMT-3--> <lojaxyz>
<produtos>
<produto>

<descricao>Nome/titulo do Oferta</descricao>

<preco>Preo do Oferta</preco>

<id_oferta>Cdigo nico da oferta, geralmente pertencente a uma nica

oferta.</id_oferta>

<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

possvel</categoria>

<cor>Cor do produto ou acessrio<cor>

<tamanho>Tamanho do produto ou acessrio</tamanho>

<parcelamento>Nmero de parcelas e o valor de cada parcela</

parcelamento>

<disponibilidade>Quantidade desta oferta em estoque</disponibilidade>

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

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 identificar onde comea e termina uma oferta.

Este documento de propriedade do Buscap Company .

Todos os direitos reservados. Documento Confidencial.

_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-

abc123</link_prod>

<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>

</produto>
<produto>

<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>

.
.
.
</produtos>
<lojaxyz>

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

Este documento de propriedade do Buscap Company .

Todos os direitos reservados. Documento Confidencial.

_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 modificao 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,
identific-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 Confidencial.

_Manual de Integrao
Buscap XML

Nesta representao, o timestamp fica 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, exemplificadas
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 filial: Cdigo nico que identifica a filial
<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 Confidencial.

_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 finalizou-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 Confidencial.

10