Documentação Integração

Imóveis - versão 1.2

Última revisão: 02/2019
1. Introdução

Os dados serão enviados ao portal Chaves na Mão via arquivo XML. O

cliente deverá disponibilizar uma URL na internet para que seja efetuada a
leitura e/ou download deste arquivo. O arquivo deverá ficar disponível para
acesso a qualquer momento, onde o portal poderá baixar as informações e
atualizar os dados no sistema do portal.
De preferência, o XML gerado pelo sistema do cliente deverá ser
dinâmico, sendo atualizado automaticamente com os imóveis contido no
sistema do cliente. A leitura desse arquivo é realizada 1 (uma) vez por dia,
podendo ser durante o dia ou a noite, dependendo da fila de execução de
cada integração.

A data de atualização do anúncio é obrigatória. Somente os anúncios

com data de atualização posterior a data de última execução serão
atualizados.

Após o imóvel ser indexado pela primeira vez, ​as fotos serão
atualizadas quando​:
- data de atualização do anúncio for posterior a data de última
atualização ​E​:
- url da imagem for alterada
OU
- data de alteração da imagem for posterior a data de
última atualização;

2. Arquivo XML

O arquivo XML deverá estar com codificação de caracteres ​UTF-8​,

sendo extremamente necessário se prestar atenção neste detalhe, pois se o
arquivo for enviado com codificação diferente, poderão ocorrer problemas
com todos os caracteres acentuados contidos no arquivo, o que poderá fazer
com que o imóvel não seja alocado no bairro correto, cidade correta, tipo de
imóvel correto, entre outros problemas visuais e técnicos.

2.1 Estrutura Arquivo XML

O arquivo deve possuir a estrutura a seguir, sendo necessária a

utilização de todas as tags, mesmo que não sejam de preenchimento
obrigatório, deixando seu conteúdo vazio nesses casos.
As tags são “case sensitive”, ou seja, elas devem possuir os
caracteres em maiúsculo/minúsculo conforme apresentados nesse
documento para funcionarem corretamente.
 *Um arquivo XML de exemplo é encaminhado junto com este manual, favor
verificá-lo para maiores dúvidas, caso não tenha recebido este arquivo ou o mesmo não
tenha sanado suas dúvidas, entre em contato com nosso suporte.

TAG “XML”, indicando a versão do xml e a codificação de caracteres

​ eve ser utf-8​):
(d
<?xml version="1.0" encoding="utf-8"?> 

TAG “Document”. Tag para indicar o início do documento, deve ser

finalizada ao término do arquivo.
<?xml version="1.0" encoding="utf-8"?> 
<Document> 
</Document> 

TAG “imóveis”. Essa tag informa o início da lista de imóveis do cliente,

deve ser finalizada quando terminado a lista de imóveis do cliente e deve
estar dentro da tag “Document”.
<?xml version="1.0" encoding="utf-8"?> 
<Document> 
<imoveis></imoveis> 
</Document> 

TAG “imovel”, Tag que informa o conteúdo de cada imóvel do cliente,

deve estar dentro da tag “imoveis” e ser finalizada a cada imóvel contido na
lista. Podem conter quantas tags “imovel” forem necessárias dentro da tag
“imoveis”.
<?xml version="1.0" encoding="utf-8"?> 
<Document> 
<imoveis> 
<imovel></imovel> 
<imovel></imovel> 
</imoveis> 
</Document> 

Dentro da TAG “imovel, deve ser colocado as tags referentes as

informações de cada imóvel do cliente. Esta tag suporta as seguintes tags
dentro dela. Tags destacadas em ​vermelho são novas tags acrescentadas ou
que sofreram alterações a partir desta documentação que podem e/ou devem
ser utilizadas a partir deste momento:
<?xml version="1.0" encoding="utf-8"?> 
<Document> 
<imoveis> 
<imovel> 
<referencia></referencia> 
<codigo_cliente></codigo_cliente> 
<link_cliente></link_cliente> 
<titulo></titulo> 
 <transacao></transacao> 
<transacao2></transacao2> 
<finalidade></finalidade> 
<finalidade2></finalidade2> 
<destaque></destaque> 
<tipo></tipo> 
<tipo2></tipo2> 
<valor></valor>  
<valor_locacao></valor_locacao>  
<valor_iptu></valor_iptu> 
<valor_condominio></valor_condominio> 
<area_total></area_total> 
<area_util></area_util> 
<conservacao></conservacao> 
<quartos></quartos> 
<suites></suites> 
<garagem></garagem> 
<banheiro></banheiro> 
<closet></closet> 
<salas></salas> 
<despensa></despensa> 
<bar></bar> 
<cozinha></cozinha> 
<quarto_empregada></quarto_empregada> 
<escritorio></escritorio> 
<area_servico></area_servico> 
<lareira></lareira> 
<varanda></varanda> 
<lavanderia></lavanderia> 
<estado></estado> 
<cidade></cidade> 
<bairro></bairro> 
<cep></cep> 
<endereco></endereco> 
<numero></numero> 
<complemento></complemento> 
<descritivo><![CDATA[ ##TEXTO## ]]></descritivo> 
<fotos_imovel> 
<foto> 
<url></url> 
<data_atualizacao></data_atualizacao> 
</foto> 
</fotos_imovel> 
<data_atualizacao></data_atualizacao> 
<latitude></latitude> 
<longitude></longitude> 
<video></video> 
<area_comum> 
<item></item> 
</area_comum> 
<area_privativa> 
<item></item> 
</area_privativa> 
<aceita_troca></ aceita_troca> 
<periodo_locacao></ periodo_locacao> 
</imovel> 
</imoveis> 
</Document> 
2.1.0 Especificações tags dados imóvel

NOME TAG OBRIGATÓRIO TIPO DESCRIÇÃO

referencia SIM string Código de referencia do
imóvel no sistema do cliente.
Utilizado para identificação do
imóvel na imobiliária e como
código de referencia de
integração no portal Chaves
na mão.
codigo_cliente NÃO string Código do imóvel no sistema
do cliente, pode ser o mesmo
utilizado na tag “referencia” ou
outro código de identificação
interna no sistema do cliente.
link_cliente NÃO string Link do imóvel no site do
cliente.
titulo NÃO string Título do imóvel colocado pelo
cliente.
transacao SIM char(1) Tipo de transação do imóvel
(venda ou locação). Utilizar V
para venda ou L para locação.
transacao2 NÃO char(1) Tipo de transação secundária
do imóvel (venda ou locação).
Utilizar V para venda ou L
para locação. Utilizar em
casos de imóveis disponíveis
tanto para venda quanto para
locação.
finalidade SIM char(2) Finalidade do imóvel
(residencial, comercial, rural).
Utilizar RE para residencial,
CO para comercial e RU para
rural.
finalidade2 NÃO char(2) Finalidade secundária do
imóvel (residencial,
comercial, rural). Utilizar RE
para residencial, CO para
comercial e RU para rural.
Utilizar em casos de imóveis
disponíveis para mais de uma
finalidade. Caso o imóvel não
possua duas finalidades
deixar este campo vazio.
destaque SIM integer(1) Informa se o imóvel deve
aparecer em destaque no
portal ou não. Utilizar 0 para
não e 1 para sim.
tipo SIM string Tipo do imóvel para a tag
“<finalidade>”. Ver lista de
 tipos de imóveis suportados
de acordo com sua finalidade
no item 2.2 deste documento.
tipo2 NÃO string Tipo do imóvel para a tag
“<finalidade2>”. Ver lista de
tipos de imóveis suportados
de acordo com sua finalidade
no item 2.2 deste documento.
Caso o imóvel possua não
possua duas finalidades,
deixar este campo vazio.
conservacao NÃO char(1) Estado de conservação do
imóvel. Utilizar N para novo
ou U para usado.
valor SIM float Valor do imóvel. Deve estar
em formato float, com ponto
(.) para casas decimais. Pode
ser utilizado para informar
tanto o valor de venda quanto
de locação, caso o imóvel
possua apenas um tipo de
transação. Caso possua dois
tipos de transações (venda ou
locação), este campo deve
ser utilizado para informar o
valor de venda.
valor_locacao NÃO float Valor de locação do imóvel.
Deve estar em formato float,
com ponto (.) para casas
decimais. Utilizar somente
caso o imóvel esteja
disponível tanto para venda
quanto para locação.
valor_iptu NÃO float Valor do IPTU do imóvel.
Deve estar em formato float,
com ponto (.) para casas
decimais.
valor_condominio NÃO float Valor do condomínio do
imóvel. Deve estar em
formato float, com ponto (.)
para casas decimais.
area_total NÃO float Área total do imóvel. Deve
estar em formato float, com
ponto (.) para casas decimais.
area_util NÃO float Área útil do imóvel. Deve
estar em formato float, com
ponto (.) para casas decimais.
quartos NÃO integer(3) Quantidade de quartos do
imóvel. Deve estar no formato
de número inteiro. Pode
possui até 3 caracteres.
suites NÃO integer(2) Quantidade de suítes do
imóvel. Deve estar no formato
de número inteiro. Pode
possui até 2 caracteres.
garagem NÃO integer(3) Quantidade de garagens do
imóvel. Deve estar no formato
de número inteiro. Pode
possui até 3 caracteres.
banheiro NÃO integer(3) Quantidade de banheiros do
imóvel. Deve estar no formato
de número inteiro. Pode
possui até 3 caracteres.
closet NÃO integer(2) Quantidade de closets do
imóvel. Deve estar no formato
de número inteiro. Pode
possui até 2 caracteres.
salas NÃO integer(2) Quantidade de salas do
imóvel. Deve estar no formato
de número inteiro. Pode
possui até 2 caracteres.
despensa NÃO integer(2) Quantidade de despensas do
imóvel. Deve estar no formato
de número inteiro. Pode
possui até 2 caracteres.
bar NÃO integer(2) Quantidade de bares do
imóvel. Deve estar no formato
de número inteiro. Pode
possui até 2 caracteres.
cozinha NÃO integer(2) Quantidade de cozinhas do
imóvel. Deve estar no formato
de número inteiro. Pode
possui até 2 caracteres.
quarto_empregada NÃO integer(2) Quantidade de quartos de
empregada do imóvel. Deve
estar no formato de número
inteiro. Pode possui até 2
caracteres.
escritorio NÃO integer(2) Quantidade de escritórios do
imóvel. Deve estar no formato
de número inteiro. Pode
possui até 2 caracteres.
area_servico NÃO integer(2) Quantidade de áreas de
serviço do imóvel. Deve estar
no formato de número inteiro.
Pode possui até 2 caracteres.
lareira NÃO integer(2) Quantidade de lareiras do
imóvel. Deve estar no formato
de número inteiro. Pode
possui até 2 caracteres.
varanda NÃO integer(2) Quantidade de varandas e/ou
sacadas do imóvel. Deve
estar no formato de número
inteiro. Pode possui até 2
caracteres.
lavanderia NÃO integer(2) Quantidade de lavanderias do
imóvel. Deve estar no formato
de número inteiro. Pode
possui até 2 caracteres.
estado SIM char(2) Estado (uf – unidade da
federação) do endereço do
imóvel. Deve estar abreviado
(com dois caracteres), como
utilizado de forma oficial pelo
Governo Federal. Ver item 2.3
deste documento.
cidade SIM string Nome da cidade do imóvel.
bairro SIM string Nome do bairro do imóvel.
cep NÃO string(9) CEP do endereço do imóvel,
pode conter somente
números, ou estar formato de
acordo com a formatação
oficial utilizada pelos Correios.
Máximo de 9 (nove)
caracteres.
endereco NÃO string(200) Endereço do imóvel, sem o
bairro, número e
complemento. Somente o
logradouro do imóvel deve ser
enviado neste campo. Máximo
de 200 (duzentos) caracteres.
numero NÃO string(10) Número do imóvel no
endereço. Máximo de 10 (dez)
caracteres.
complemento NÃO string(50) Complemento do número do
imóvel no endereço. Máximo
de 20 (vinte) caracteres.
descritivo SIM text Descrição do imóvel.
Tamanho máximo de 3000
caracteres.
fotos_imovel NÃO TAG Depende da tag <foto>, <url>
e <data_atualizacao> dentro
da mesma, ​ver
especificações de seu
conteúdo no item 2.1.0.0
data_atualizacao NÃO datetime Data de cadastro ou data da
última atualização do imóvel
no sistema do cliente.
Priorizar o informe da data de
última atualização, caso
 existente no sistema. Formato
data/hora suportado:
AAAA-MM-DD HH:MM:SS
(ex: 2014-09-09 12:00:00).
latitude NÃO string Coordenada geográfica
latitude do endereço do
imóvel. Deve ser informado no
padrão utilizado pelo Google
(ex: -49.1829).
longitude NÃO string Coordenada geográfica
longitude do endereço do
imóvel. Deve ser informado no
padrão utilizado pelo Google
(ex: -25.4026).
video NÃO string Link do vídeo no ​Youtube​,
Deve ser colocado o link para
acessar o vídeo normalmente
pelo navegador. ​Não pode
ser utilizado embed​.
area_comum NÃO TAG Deve ser colocado os itens de
área comum existentes no
imóvel. ​Ver especificações
de seu conteúdo no item
2.1.0.1
area_privativa NÃO TAG Deve ser colocado os itens de
área comum existentes no
imóvel. ​Ver especificações
de seu conteúdo no item
2.1.0.2
aceita_troca NÃO integer(1) Informa se o imóvel aceita
trocas ou não. 0 para não e 1
para sim. Caso não seja
informado será considerado
que o imóvel não aceita
trocas.
periodo_locacao NÃO integer(1) Período de locação
Apenas enviar campo quando
em caso de locação
informando os valores inteiros
em cada caso:
1 - Por Mês
2 - Por Dia
3 - Por Ano
4 - Por Semana
Exemplo: Caso periodo de
locação por dia:
<periodo_locacao>2</periodo
_locacao>

2.1.0.0 Especificações tag de fotos do imóvel

 A tag de fotos do imóvel contém uma lista de fotos do imóvel com
outras tags dentro, contendo a url da foto e a data da última atualização da
foto no sistema do cliente. Essa tag deve se encontrar dentro da tag de
dados do imóvel, contendo a seguinte estrutura:
<fotos_imovel>
<foto>
<url></url>
<data_atualizacao></data_atualizacao>
</foto>
</fotos_imovel>

Cada foto do imóvel deverá estar dentro da tag “<foto>”, com a

informação da url da imagem e a data de sua última atualização. A tag
“<foto>” pode se repetir quantas vezes forem necessárias para cada uma das
fotos do imóvel.
Existe um limite no número de fotos que cada imóvel suporta. O limite
hoje esta em ​30 (trinta) fotos por imóvel. As fotos enviadas a mais que esse
número serão ignoradas automaticamente pelo sistema.
Seguem especificações dos conteúdos que devem ser passado dentro
da tag de cada foto que está sendo enviada ao portal.

NOME TAG OBRIGATÓRIO TIPO DESCRIÇÃO

url SIM string Endereço URL da imagem
na internet. Deve ser um
endereço público onde o
sistema possa buscar a
imagem e salvar em nosso
servidor. ​Ideal que seja
alterado sempre que a
imagem seja atualizada.
data_atualizacao NÃO datetime Data de cadastro ou data da
última atualização da foto no
sistema do cliente. Priorizar
o informe da data de última
atualização, caso existente
no sistema. Formato
data/hora suportado:
AAAA-MM-DD HH:MM:SS
(ex: 2014-09-09 12:54:32)

2.1.0.1 Especificações tag de áreas comuns do imóvel

A tag de áreas comuns do imóvel contém uma lista de tags <item>

dentro, contendo o nome de cada item característico do imóvel. Essa tag
deve se encontrar dentro da tag de dados do imóvel, contendo a seguinte
estrutura:
<area_comum>
 <item></item>
</area_comum>

A lista de itens de áreas comuns suportadas deve ser consultada em:

http://www.chavesnamao.com.br/imoveis/integracao/areas_comuns​. Somente
os itens contidos nessa lista serão aceitos e cadastrados junto ao portal,
qualquer item enviado que não esteja contido nesta listagem será ignorado.
Seguem especificações dos conteúdos que devem ser passado dentro
da tag de item de área comum do imóvel que esta sendo enviada ao portal.

NOME TAG OBRIGATÓRIO TIPO DESCRIÇÃO

item SIM string Nome do item de área
comum característico do
imóvel. Consultar lista
suportada através do
endereço acima informado.

2.1.0.2 Especificações tag de áreas privativas do imóvel

A tag de áreas privativas do imóvel contém uma lista de tags <item>

dentro, contendo o nome de cada item característico do imóvel. Essa tag
deve se encontrar dentro da tag de dados do imóvel, contendo a seguinte
estrutura:
<area_privativa>
<item></item>
</area_privativa>

A lista de itens de áreas privativas suportadas deve ser consultada em:

http://www.chavesnamao.com.br/imoveis/integracao/areas_privativas​.
Somente os itens contidos nessa lista serão aceitos e cadastrados junto ao
portal, qualquer item enviado que não esteja contido nesta listagem será
ignorado.
Seguem especificações dos conteúdos que devem ser passado dentro
da tag de item de área comum do imóvel que esta sendo enviada ao portal.

NOME TAG OBRIGATÓRIO TIPO DESCRIÇÃO

item SIM string Nome do item de área
privativa característico do
imóvel. Consultar lista
suportada através do
endereço acima informado.

2.2 Tipos de Imóveis suportados

Os tipo de imóveis suportados hoje pelo portal Chaves na Mão

são definidos de acordo com a finalidade de cada imóvel
(Residencial/Comercial/Outros). Os nomes devem estar exatamente
iguais aos tipos suportados pelo portal.
Para obter a lista atualizada de tipos suportados por nosso portal,
acesse o endereço:
​http://www.chavesnamao.com.br/imoveis/integracao/tipos

Obs.: a partir desta versão, temos um novo tipo de imóvel que é o tipo
Consultório, válido para imóveis do tipo Comercial.

2.3 Estados suportados (UF – Unidades da Federação)

Deve ser utilizada somente a abreviação oficial, utilizada pelo Governo

Federal, de cada estado no XML quando informado o estado (uf – unidade da
federação) do endereço do imóvel.

NOME ESTADO ABREVIAÇÃO OFICIAL

Acre AC
Alagoas AL
Amapá AP
Amazonas AM
Bahia BA
Ceará CE
Distrito Federal DF
Espírito Santo ES
Goiás GO
Maranhão MA
Mato Grosso MT
Mato Grosso do Sul MS
Minas Gerais MG
Pará PA
Paraíba PB
Paraná PR
Pernambuco PE
Piauí PI
Rio de Janeiro RJ
Rio Grande do Norte RN
Rio Grande do Sul RS
Rondônia RO
Roraima RR
Santa Catarina SC
São Paulo SP
Sergipe SE
Tocantins TO