Feed XML de produtos (VRSync)

Visão geral

O arquivo deve seguir o VRSync, o padrão de XML de imóveis do Grupo Zap, documentado em developers.grupozap.com. O VRSync não é exclusivo de um portal: a maioria dos CRMs e sites imobiliários consegue exportá-lo.

A sincronização funciona com qualquer integração ativa da sua empresa, não só com o Grupo Zap.

O Imobilead usa só uma pequena parte do VRSync. Um feed completo do Grupo Zap funciona, e um feed mínimo, só com os três campos abaixo, também.

Estrutura do arquivo

<?xml version="1.0" encoding="UTF-8"?>
<ListingDataFeed xmlns="http://www.vivareal.com/schemas/1.0/VRSync"
                 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                 xsi:schemaLocation="http://www.vivareal.com/schemas/1.0/VRSync http://xml.vivareal.com/vrsync.xsd">
  <Header>...</Header>
  <Listings>
    <Listing>
      <ListingID>AP0042</ListingID>
      <Title><![CDATA[Apartamento 2 quartos no Centro]]></Title>
      <TransactionType>For Sale</TransactionType>
      <!-- Details, Location, Media, ContactInfo... são aceitos e ignorados -->
    </Listing>
  </Listings>
</ListingDataFeed>

Elemento	No Imobilead	Observações
ListingDataFeed	Obrigatório (raiz)	Sem ele a sincronização falha com “A url do xml é inválida!”. Use o namespace padrão: uma raiz com prefixo (<vr:ListingDataFeed>) não é lida.
Header	Ignorado	O Grupo Zap exige. Mantenha-o para que o mesmo arquivo continue valendo no portal.
Listings	Obrigatório	Contêiner dos imóveis. Vazio ou ausente significa nenhum produto importado.
Listing	Um por imóvel	Um único Listing ou vários são aceitos.

Campos lidos de cada imóvel

Apenas três campos são lidos. Espaços nas pontas são removidos, e valores acima de 500 caracteres são cortados.

Campo	Obrigatório	Regras
ListingID	Sim	Código do imóvel na origem. Precisa ser o mesmo código que o portal envia junto com os leads (no Grupo Zap, o clientListingId; na OLX, o adId): é por ele que o lead é ligado ao produto. Deve ser único no arquivo, pois o Imobilead não remove duplicados. O Grupo Zap limita a 1–50 caracteres.
Title	Sim	Vira o título do produto. Emojis são removidos. Com a opção “Adicionar o id do portal ao título do produto” ligada (padrão), o título fica <ListingID> - <Title>. O Grupo Zap limita a 10–100 caracteres, sem HTML, e recomenda CDATA.
TransactionType	Sim	Tipo de negócio. Valores reconhecidos: For Sale (Venda), For Rent (Aluguel) e Sale/Rent (Venda e Aluguel). Outro valor é gravado, mas o produto fica sem categoria.

Todos os outros elementos do Listing (PublicationType, Details, Location, Media, ContactInfo, preços) são ignorados.

Um imóvel com erro não derruba o arquivo: um Listing sem algum dos três campos é pulado e o resto é importado. O histórico mostra “N listings ignorados por falta de ListingID, Title ou TransactionType.”. Se nenhum imóvel for válido, a sincronização termina com erro (“Nenhum listing válido no xml.”).

Requisitos da URL

Regra	Detalhe
Protocolo	https://.
Caminho	Qualquer caminho; não precisa terminar em .xml. Query string é permitida.
Parâmetro timestamp	O Imobilead acrescenta ?timestamp=<ms> (ou &timestamp=<ms>) para evitar cache. Por isso URLs pré-assinadas (ex.: S3) não funcionam: o parâmetro extra invalida a assinatura.
Endereço público	A URL precisa apontar para um endereço público da internet. Endereços privados, locais ou internos são recusados. Redirecionamentos são seguidos até 5 vezes.
Tamanho da URL	Até 2048 caracteres.
Resposta	Acessível sem login, respondendo HTTP 2xx.
Quantidade	Até 50.000 imóveis por arquivo (limite do Grupo Zap).
Tamanho do arquivo	Até 250 MB (descompactado, se vier em gzip).
Tempo de download	Sem pausas acima de 20 segundos e arquivo completo em até 5 minutos.

As requisições do Imobilead se identificam com os cabeçalhos abaixo. Se o seu servidor bloqueia robôs desconhecidos, libere este User-Agent:

User-Agent: Mozilla/5.0 (compatible; imobilead-xmlsync/1.0; +https://imobilead.me)
Accept: application/xml, text/xml, */*

Como configurar

1. Abra Integrações → aba Produtos → “Sincronizar XML” (ou “Produtos” no card de uma integração ZAP).
2. Selecione uma das integrações ativas da empresa. Os produtos criados ficam vinculados a ela.
3. Cole a URL do XML e defina se o código do portal deve ir no título do produto.
4. Clique em “Sincronizar agora!” ou aguarde a rodada diária. Acompanhe pelo botão “Ver histórico”.

Quando o arquivo é lido

• Diariamente, às 02:00 (horário de Brasília).
• Manualmente, pelo botão “Sincronizar agora!”. Ele fica bloqueado por 24 horas após a última rodada, exceto quando a última sincronização terminou com erro.
• A partir da segunda rodada, se o arquivo não mudou (mesma data de modificação e mesmo tamanho), o download é pulado e o histórico mostra “Nenhuma alteração detectada no arquivo!”. Se o seu servidor não envia o cabeçalho Last-Modified, o arquivo é baixado sempre.

Como os imóveis viram produtos

• ListingID novo: cria um produto vinculado à integração.
• ListingID já conhecido (em qualquer integração da empresa): atualiza título e tipo de negócio. O produto mantém a integração original.
• Primeira sincronização: todos os imóveis do arquivo são criados como produtos, mesmo que já exista um produto com o mesmo código.
• Imóvel removido do arquivo: o produto não é apagado nem bloqueado.

Mensagens de erro mais comuns

Mensagem no histórico	O que fazer
A url do xml é inválida!	Confira se a URL abre no navegador e se a raiz do arquivo é ListingDataFeed (formato VRSync).
XML inválido na linha X, coluna Y: …	O arquivo tem um erro de sintaxe nessa posição. Corrija na origem e valide no validador do Grupo Zap.
Nenhum listing válido no xml.	Nenhum imóvel tem os três campos obrigatórios. Revise ListingID, Title e TransactionType.
Não foi encontrado nenhum produto novo ou para atualizar!	Listings está vazio ou ausente.
O xml passou do limite de 50.000 imóveis e não foi importado.	Divida o feed em mais de um arquivo, em integrações diferentes.
O xml passou do limite de 250 MB e não foi importado.	Remova elementos desnecessários ou divida o arquivo.
O download do xml demorou demais e foi interrompido.	O servidor ficou mais de 20 s sem enviar dados ou passou de 5 minutos. Verifique a hospedagem do arquivo.
URL não permitida: use um endereço público.	A URL aponta para um endereço interno ou privado. Publique o arquivo em um endereço acessível pela internet.
Não foi possível conectar ao endereço do xml.	O servidor recusou a conexão. Confira se ele está no ar e se não bloqueia o User-Agent do Imobilead.
Esta integração não está mais ativa!	A integração vinculada foi desativada. Reative-a ou configure o XML em outra integração.

Checklist

• Arquivo no formato VRSync, com raiz ListingDataFeed sem prefixo.
• Todo Listing com ListingID, Title e TransactionType.
• ListingID igual ao código que o portal envia nos leads.
• URL pública, sem login e sem assinatura temporária.
• Até 50.000 imóveis e 250 MB.
• User-Agent do Imobilead liberado no servidor.

Referências

Grupo Zap: Formatos XML, Listing, Exemplos e Validador XML.

Suporte: em caso de dúvida, entre em contato com nossa equipe.