Camada de Integração de Dados

Atualizado em 31 Jan 2014
Atenção: Este documento está em desenvolvimento.

A documentação aqui contida poderá sofrer mudanças nos próximos dias. Fique atento para estas alterações. Se desejar ser notificado quando publicarmos alguma alteração, envie uma mensagem para contato@epungo.com.br com seu endereço de email. Retornaremos para confirmar a solicitação.

Índice

Este artigo documenta o arquivo XML de integração utilizado pelo Epungo para a importação de dados. O artigo está dividido em 5 seções, conforme o índice abaixo.



Este documento está em desenvolvimento. Se tiver dúvidas ou desejar relatar um bug, queira por gentileza contactar-nos usando o email contato@epungo.com.br. Obrigado!

Estrutura básica do XML: Elemento <root> e atributos obrigatórios

A importação de dados é feita através de um arquivo XML disponibilizado em uma URL. É importante que seja gerada uma URL para cada anunciante. No arquivo devem estar contidos os dados de todos os imóveis, bem como informações de o que fazer com os imóveis. O arquivo pode também conter imagens e outras mídias referentes aos imóveis. Estas mídias podem estar presentes de duas formas:

  1. URL. Links para imagens, vídeos e faixas de audio em um servidor web (recomendado).
  2. Binário. Dados binários codificados em base64.

A estrutura do XML de integração é bastante simples. Há um único elemento root que contém todos os demais. O elemento root contém um elemento obrigatório xml_epng que indica tratar-se de um documento de integração feito específicamente para integração de dados com o Epungo. Este elemento deve conter o valor "1".





O elemento root pode conter também mais dois elementos opcionais: version, que indica a versão do documento, e locale, que indica a localização do documento como um todo. A definição de localização indica a língua do conteúdo textual, moeda em que os valores se encontram, quais devem ser os separadores decimal e de milhares, o padrão de unidades de medida, etc... Na falta de uma declaração de localização, toma-se como padrão o valor "en-us".

O Exemplo 1 a seguir mostra a declaração básica do arquivo XML na versão 1, localizado para "pt-br". Neste caso, o sistema espera que o conteúdo textual esteja na língua Portuguesa do Brasil, a moeda seja o BRL (Real Brasileiro), os separadores sejam o "." para milhares e a "," para decimais, o sistema de medidas seja o internacional (métrico), etc...

Note que o elemento listings está vazio, ou seja, não há imóveis neste XML.



Exemplo 1: Declaração mínima, válida, de um XML de integração localizado para pt-br.

Bloco de dados: Elemento <listings>

Todos os imóveis contidos no documento devem estar dentro do elemento listings. Cada imóvel é representado por um elemento listing.

É possível sobrescrever a localização para cada imóvel. Para isso, usamos o elemento opcional locale dentro de um elemento listing. Esta sobreposição vale somente para o imóvel em que ela é feita.

O Exemplo 2 a seguir ilustra um XML que contém 5 imóveis. O documento está localizado para "pt-br". Contudo, os dois primeiros imóveis estão localizados para "en-us", ou seja, somente para estes dois imóveis, os textos são esperados em Inglês/EUA, a moeda é o USD (Dólar americano), e as medidas são esperadas no sistema americano.

Note também que omitimos o elemento version. Neste caso, o sistema supõe a versão estável mais recente.



Exemplo 2: Ilustra um XML contendo 5 imóveis.

Estrutura de um imóvel: Elemento <listing>

O elemento listing representa um imóvel. Ele é o elemento mais complexo do XML. Cada listing deve conter uma série de campos obrigatórios. Cada um pode opcionalmente conter um número grande (mais de 100) de campos opcionais.

Controle de ação e Endereço

O primeiro grupo de campos obrigatórios define a ação a ser tomada e o endereço do imóvel. Os campos obrigatórios estão listados abaixo. Para mais detalhes, consulte a Especificação detalhada de campos do XML do Epungo.



Campos obrigatórios de Ação e Endereço

Definição de valores

O elemento listing também deve conter uma ou mais informações de preço. É possível registrar múltiplas informações de preço se estiver, por exemplo, disponível para Aluguel e Venda. O conteúdo dos campos de preço (e dos campos numéricos em geral) são esperados no padrão internacional, ou seja, tendo o "." como separador decimal e livre de qualquer formatação.


Cuidado!

Um imóvel com <sale_price>1.000.000</sale_price> será considerado como USD$ 1.00 (um dólar).
Um imóvel com <sale_price>R$ 1,000,000.00</sale_price> será considerado inválido (caracteres não-numéricos).

A forma correta para representar um imóvel com valor de venda de Um milhão é:
<sale_price>1000000.00</sale_price> ou <sale_price>1000000</sale_price>


Um dos elementos abaixo deve estar obrigatoriamente declarado.

Multimídia

Finalmente, o elemento listing pode conter informações em diversas mídias. Você pode juntar ao imóvel imagens, vídeo ou áudio, sendo cada tipo contido no seu respectivo elemento: pictures, videos e audio. Cada item de mídia deve estar dentro do grupo correspondente. Os itens podem ser, respectivamente: picture, video e track.


O Exemplo 3, a seguir, ilustra um bloco midia contendo 3 fotos, sendo as duas primeiras disponíveis via uma URL remota, e a terceira codificada em base64. O exemplo também mostra um vídeo, disponível numa URL.


Exemplo 3: Declaração de elementos de mídia.

Exemplo completo de um elemento <listing>

O Exemplo 4 abaixo explica em maior detalhe o conteúdo dos campos obrigatórios. Note que os campos lat, lng e complement estão declarados, apesar de não serem obrigatórios.

Para uma lista detalhada dos campos suportados e sua especificação, consulte o documento Especificação detalhada de campos do XML do Epungo.



Exemplo 4: Configuração mínima de um imóvel.

Especificação detalhada de campos

Este modelo de integração prevê mais de 100 campos de detalhamento do imóvel. Para uma explicação detalhada dos campos previstos nesta especificação, consulte o documento Especificação detalhada de campos do XML do Epungo.