detalhamento das tags de integração

www.nossodesconto.com.br
Documentação para integrar Sites de Compra
Coletiva à plataforma NossoDesconto
Última atualização: 17/09/2010
Documentação para integração com a plataforma NossoDesconto
1) Objetivos desta documentação
O presente documento tem como objetivo principal fornecer instruções sobre como
padronizar o cadastro das ofertas do seu site de Compras Coletivas no NossoDesconto.
Também tem como escopo manter as informações das suas promoções sempre completas,
corretas e atualizadas.
2) Por que devo integrar meu site ao NossoDesconto?
O NossoDesconto é um agregador de ofertas de Compra Coletiva, com milhares de
visitantes que esperam encontrar diariamente as melhores promoções locais. Ao integrar
seu site à nossa plataforma, suas ofertas serão cadastradas de um jeito fácil e prático,
tornando-as disponíveis com mais agilidade e precisão.
3) E se eu não integrar meu site ao NossoDesconto?
Para agilizar o cadastramento e estabelecer uma padronização dos dados, daremos
prioridade à inserção de ofertas daqueles sites que aderirem a esta Integração.
Sites que não seguirem a Integração continuarão tendo suas promoções visíveis no
NossoDesconto. Porém, estarão sujeitos - em um futuro próximo e sem aviso prévio - a não
terem mais as suas ofertas listadas em nosso site.
4) Devo criar um arquivo dinâmico para cada cidade?
Sim, você deve criar um arquivo dinâmico para cada cidade, nos moldes do arquivo XML
“nossodesconto-ofertas-cidade.xml” que você recebeu junto com este documento. Este
arquivo dinâmico assemelha-se aos feeds RSS e deve estar sincronizado com suas ofertas
diárias para cada cidade.
5) Devo preencher todos os campos/tags nos arquivos dinâmicos?
Fica a seu critério preencher todas as tags, mas recomendamos que informe o maior
número possível de dados, até porque seus concorrentes farão isso. Lembre-se: esses
arquivos são a fonte das informações que serão mostradas aos nossos usuários. Quanto
mais detalhes você nos fornecer, mais completa será a descrição das suas ofertas.
6) Criei os arquivos para cada cidade. E agora?
Depois de criar os arquivos dinâmicos para cada cidade, seguindo todas as instruções
deste documento, entre em contato conosco, informando-nos as respectivas URLs de cada
um, através do seguinte endereço de e-mail: [email protected]
Exemplos:
São Paulo – http://www.site-exemplo.com.br/ofertas-sp.xml
Rio de Janeiro – http://www.site-exemplo.com.br/ofertas?cidade=rj
Belo Horizonte – http://www.site-exemplo.com.br/feed/ofertas-bh
7) Dúvidas, críticas ou sugestões?
Queremos sempre fortalecer nossos laços de parceria. Se quiser entrar em contato conosco
sobre assuntos relacionados à Integração, por favor envie uma mensagem para o seguinte
endereço de e-mail: [email protected]
2
Documentação para integração com a plataforma NossoDesconto
ANTES DE COMEÇAR
Algumas observações importantes, que você precisa ter conhecimento antes de começar a
criar seus arquivos dinâmicos de integração:
1. As tags que estão listadas nas próximas páginas que possuem * (asterisco) denotam
que seu preenchimento é obrigatório. Caso não sejam devidamente preenchidas
serão consideradas inválidas e a respectiva oferta não poderá ser cadastrada no
NossoDesconto.
2. Na primeira linha do arquivo dinâmico, defina qual o tipo de codificação está sendo
usada no seu documento.
Possíveis valores de codificação:
a) <?xml version="1.0" encoding="iso-8859-1"?>
b) <?xml version="1.0" encoding="utf-8"?>
3. Siga as instruções das próximas páginas e use como referência o arquivo
“nossodesconto-ofertas-cidade.xml”, que foi enviado junto com este documento.
3
Documentação para integração com a plataforma NossoDesconto
DETALHAMENTO DAS TAGS DE INTEGRAÇÃO
Tag-principal: <nossodesconto-ofertas>*
A tag-principal <nossodesconto-ofertas> é usada para englobar todo o conteúdo do seu
arquivo de integração com a plataforma do NossoDesconto.
Tag: <oferta>*
A tag <oferta> engloba todas as informações de cada oferta disponível na cidade em que
seu site atua.
Observação:
● Uma tag <oferta> para cada promoção que estiver atualmente disponível, na
presente cidade.
Tag: <id>*
A tag <id> deve ser preenchida com um nome único para identificar a oferta. Não pode
conter espaço nem caracteres especiais (exceto traço simples).
Caracteres permitidos:
[a-z][0-9][-]
Exemplo válido: oferta-do-restaurante-abc
Tag: <oferta_url>*
A tag <oferta_url> exibe a URL (link) da oferta, na qual ela poderá ser acessada
diretamente. Precisa ser a mesma URL onde o usuário pode vê-la através do
browser/navegador.
Exemplo válido: http://www.site-123.com.br/oferta-restaurante-ABC.html
Tag: <titulo>*
A tag <titulo> exibe o título ou chamada da oferta.
Exemplo válido: De R$100 por R$50 - Desconto de 50% no Restaurante ABC
4
Documentação para integração com a plataforma NossoDesconto
Tag: <resumo>
A tag <resumo> exibe um breve resumo da oferta.
Exemplo válido: Esta oferta é para os amantes da boa cozinha. Aproveite o melhor
restaurante da cidade, com este ótimo desconto de 45% no total da sua conta. O
Restaurante ABC tem petiscos a partir de R$5 e drinks especiais a partir de R$10. Não
perca!
Tag: <imagem_url>
A tag <imagem_url> indica o caminho completo (URL) para acessar a imagem principal da
oferta. A imagem precisa ter no mínimo 280px de largura e ter a extensão JPG, GIF ou
PNG.
Exemplo válido: http://www.seusite.com.br/ofertas/oferta-ABC-imagem.jpg
Tag: <estabelecimento>*
A tag <estabelecimento> exibe as informações sobre o estabelecimento que está realizando
a oferta.
Observações:
● Refere-se à loja e não ao seu site de Compras Coletivas.
Sub-Tag: <estabelecimento_nome>*
A sub-tag <estabelecimento_nome> exibe o nome do estabelecimento que está realizando
a oferta.
Observações:
● É o nome da loja. Não é o nome do seu site;
● Precisa estar obrigatoriamente dentro da tag <estabelecimento> (veja o arquivo XML
de exemplo).
Exemplo válido: Restaurante ABC
5
Documentação para integração com a plataforma NossoDesconto
Sub-Tag: <estabelecimento_url>
A sub-tag <estabelecimento_url> indica a URL do site do estabelecimento que está
realizando a oferta.
Observações:
● É a URL do site da loja. Não é o do seu site;
● Precisa estar obrigatoriamente dentro da tag <estabelecimento> (veja o arquivo XML
de exemplo).
Exemplo válido: http://www.restaurante-exemplo.com.br
Sub-Tag: <estabelecimento_enderecos>
A sub-tag <estabelecimento_enderecos> engloba cada detalhe referente ao(s) endereço(s)
físico(s) do estabelecimento.
Observações:
● Precisa estar obrigatoriamente dentro da tag <estabelecimento> (veja o arquivo XML
de exemplo).
Sub-Tag: <logradouro>
A sub-tag <logradouro> indica o endereço completo do estabelecimento.
Observações:
● Precisa estar obrigatoriamente dentro das tags <estabelecimento_enderecos> e
<endereco> (veja o arquivo XML de exemplo);
● Se houver mais de um endereço, preencha uma nova sub-tag <logradouro>;
● O preenchimento de cada sub-tag <logradouro> torna obrigatório o uso de 3 subtags adicionais: <bairro>, <coord_lat> e <coord_lng>.
Formato: Rua, Avenida etc. + Número + Complemento
Exemplo válido: R. do NossoDesconto, 123 – Conj. 15
Exemplo inválido 1: do NossoDesconto, 123
Exemplo inválido 2: Perto da Rua ABCD
6
Documentação para integração com a plataforma NossoDesconto
Sub-Tag: <bairro>
A sub-tag <bairro> indica o Bairro do respectivo endereço físico da loja.
Observações:
● Precisa estar obrigatoriamente dentro das tags <estabelecimento_enderecos> e
<endereco> (veja o arquivo XML de exemplo);
● Se houver mais de um endereço, preencha uma nova sub-tag <bairro>;
● Depende da sub-tag <logradouro>.
Caracteres permitidos: Somente letras (com ou sem acentos)
Exemplo válido: Morumbi
Sub-Tag: <coord_lat>
A sub-tag <coord_lat> indica a coordenada geográfica “Latitude” do respectivo endereço
físico da loja. Essa informação pode ser obtida através da API do Google Maps; e serve
para localizar com precisão o endereço do estabelecimento no mapa.
Observações:
● Precisa estar obrigatoriamente dentro das tags <estabelecimento_enderecos> e
<endereco> (veja o arquivo XML de exemplo);.
● Se houver mais de um endereço, preencha uma nova sub-tag <coord_lat>;
● Depende da sub-tag <logradouro>.
Caracteres permitidos: [0-9][-][.]
Exemplo válido: 37.0625
Sub-Tag: <coord_lng>
A sub-tag <coord_lng> indica a coordenada geográfica “Longitude” do respectivo endereço
físico da loja. Essa informação pode ser obtida através da API do Google Maps; e serve
para localizar com precisão o endereço do estabelecimento no mapa.
Observações:
● Precisa estar obrigatoriamente dentro das tags <estabelecimento_enderecos> e
<endereco> (veja o arquivo XML de exemplo);
● Se houver mais de um endereço, preencha uma nova sub-tag <coord_lng>;
● Depende da sub-tag <logradouro>.
Caracteres permitidos: [0-9][-][.]
Exemplo válido: -95.677068
7
Documentação para integração com a plataforma NossoDesconto
Tag: <categorias>*
A tag <categorias> engloba as categorias em que a oferta se encaixa.
Sub-Tag: <categoria>*
A sub-tag <categoria> exibe cada categoria em que a oferta se encaixa.
Observações:
● Precisa estar obrigatoriamente dentro da tag <categorias> (veja o arquivo XML de
exemplo);
● Se houver mais de uma categoria, preencha uma nova sub-tag <categoria>
Valores possíveis:
 Bares e Boates;
 Restaurantes;
 Barbearia;
 Bronzeamento;
 Cuidados com a Pele;
 Depilação;
 Massagem;
 Maquiagem;
 Salão de beleza;
 Spa;
 Academia;
 Pilates;
 Yoga;
 Roupas masculinas;
 Roupas femininas;
 Aluguel de veículos;
 Hotel;
 Turismo;
 Aventura;
 Cinema;
 Cursos e Aulas;
 Degustação;
 Esporte;
 Fotografia;
 Shows e Música;
 Teatro;
 Outros.
Exemplo válido: “Maquiagem”, “Salão de beleza”
Exemplo inválido: “Lazer”
8
Documentação para integração com a plataforma NossoDesconto
Tag: <status>*
A tag <status> indica se a promoção está aparecendo no seu site.
Valores possíveis:
● “true” (indica “sim”);
● “false” (indica “não”).
Exemplo válido: true
Tag: <data_inicio>*
A tag <data_inicio> mostra a data em que a oferta começou a ser divulgada no seu site.
Formato: aaaa-mm-dd hh:mm:ss FUSO +-hh:mm.
Observação: o atributo FUSO +- hh:mm deve ser o fuso horário atual em que sua oferta se
encontra, em relação ao horário GMT (Meridiano de Greenwich). Fuso de Brasília, fora do
horário de verão: -03:00.
Exemplo válido: 2010-12-28 23:59:59 -03:00
Exemplo válido: 2010-12-28
Tag: <data_fim>*
A tag <data_fim> mostra a data em que a oferta expira.
Formato: aaaa-mm-dd hh:mm:ss FUSO +-hh:mm.
Observação: o atributo (FUSO +- hh:mm) deve ser o fuso horário atual em que sua oferta
se encontra, em relação ao horário GMT (Meridiano de Greenwich). Fuso de Brasília, fora
do horário de verão: -03:00.
Exemplo válido: 2010-12-31 23:59:59 -03:00
Exemplo válido: 2010-12-31
Tag: <valido_apos_compras>
A tag <valido_apos_compras> informa a quantidade mínima de vendas para a oferta estar
valendo.
Caracteres permitidos: [0-9]
Exemplo válido: 10
9
Documentação para integração com a plataforma NossoDesconto
Tag: <valendo>
A tag <valendo> indica se a oferta atingiu o mínimo de compradores para estar valendo.
Valores possíveis:
● “true” (indica “sim”);
● “false” (indica “não”).
Exemplo válido: true
Tag: <esgotado>*
A tag <esgotado> indica se a oferta se esgotou, por falta de estoque.
Valores possíveis:
● “true” (indica “sim”);
● “false” (indica “não”).
Exemplo válido: false
Tag: <quantidade_vendida>
A tag <quantidade_vendida> indica a quantidade de cupons vendidos até o momento.
Caracteres permitidos: [0-9]
Exemplo válido: 2000
Exemplo inválido: 2.000
Tag: <preco_original>*
A tag <preco_original> exibe o preço original da oferta, sem o desconto. Use “ponto” para
separar as 2 casas decimais.
Caracteres permitidos: [0-9][.]
Exemplo válido: 60.00
Exemplo inválido: 60,00
10
Documentação para integração com a plataforma NossoDesconto
Tag: <preco_especial>*
A tag <preco_especial> exibe o preço especial da oferta, já com o desconto. Use “ponto”
para separar as 2 casas decimais.
Caracteres permitidos: [0-9][.]
Exemplo válido: 30.00
Exemplo inválido: 30,00
Tag: <valor_desconto>*
A tag <valor_desconto> exibe a quantia economizada com a oferta (em R$). Use “ponto”
para separar as 2 casas decimais.
Caracteres permitidos: [0-9][.]
Exemplo válido: 20.00
Exemplo inválido: 20,00
Tag: <percentual_desconto>*
A tag <percentual_desconto> exibe o percentual economizado (%) com a oferta. Use
“ponto” para separar as 2 casas decimais.
Caracteres permitidos: [0-9][.]
Exemplo válido: 50.00
Exemplo inválido: 50,00
Tag: <regras>
A tag <regras> engloba as informações sobre as condições para comprar a oferta.
Sub-Tag: <estoque>
A sub-tag <estoque> exibe a quantidade de cupons disponibilizados para venda.
Observação:
● Precisa estar obrigatoriamente dentro da tag <regras> (veja o arquivo XML de
exemplo).
Caracteres permitidos: [0-9]
Exemplo válido: 3000
Exemplo inválido: 3.000
11
Documentação para integração com a plataforma NossoDesconto
Sub-Tag: <compra_minima_pessoa>
A tag <compra_minima_pessoa> exibe a quantidade mínima de cupons que a pessoa
deverá comprar para adquirir a oferta.
Observação:
● Precisa estar obrigatoriamente dentro da tag <regras> (veja o arquivo XML de
exemplo).
Caracteres permitidos: [0-9]
Exemplo válido: 1
Sub-Tag: <compra_maxima_pessoa>
A tag <compra_maxima_pessoa> exibe a quantidade máxima de cupons que a pessoa
poderá comprar.
Observação:
● Precisa estar obrigatoriamente dentro da tag <regras> (veja o arquivo XML de
exemplo).
Caracteres permitidos: [0-9]
Exemplo válido: 3
Sub-Tag: <detalhes>
A sub-tag <detalhes> engloba cada detalhe adicional sobre a oferta.
Observação:
● Precisa estar obrigatoriamente dentro da tag <regras> (veja o arquivo XML de
exemplo).
Sub-Tag: <detalhe>
A sub-tag <detalhe> exibe informações adicionais da oferta.
Observações:
● Precisa estar obrigatoriamente dentro da tag <detalhes> (veja o arquivo XML de
exemplo);
● Se houver mais de um detalhe, preencha uma nova sub-tag <detalhe>
Exemplo válido: Promoção válida apenas novos clientes.
12
Documentação para integração com a plataforma NossoDesconto
Obrigado pela parceria!
Dúvidas, críticas ou sugestões?
Queremos sempre fortalecer nossos laços de parceria. Se quiser entrar em contato conosco
sobre assuntos relacionados à Integração, por favor envie uma mensagem para o seguinte
endereço de e-mail: [email protected]
Será sempre um prazer ajudar!
www.nossodesconto.com.br
13