Guia · Publicar um imóvel

🏠

O que este guia faz

Publicar um imóvel pela API tem quatro passos: consultar o catálogo do convênio, montar o payload por nome, incluir o imóvel (que nasce em moderação) e, depois de aprovado internamente, ativar a situação.

Escopo necessário: imoveis:write (o catálogo aceita também imoveis:read)

1️⃣ Descubra os tipos de imóvel do convênio

Tipo, bairro, cidade e característica variam de um convênio para outro. Comece pelos tipos:

curl https://api.imoviewnext.com.br/pub/v1/schema/property-types \
  -H "Authorization: Bearer imn_seuconvenio_..."

Escolha um nome da lista (ex.: Apartamento).

2️⃣ Consulte as características daquele tipo

curl "https://api.imoviewnext.com.br/pub/v1/schema/properties?propertyType=Apartamento" \
  -H "Authorization: Bearer imn_seuconvenio_..."

A resposta traz as características do tipo, com o tipo de dado e as opções válidas. É a fonte da verdade: use esses nomes no payload.

📘

Por que por nome?

Assim a integração fica legível e independente dos ids internos do sistema. Nome que não existe no convênio devolve 422 dizendo qual valor não casou.

3️⃣ Inclua o imóvel

curl -X POST https://api.imoviewnext.com.br/pub/v1/properties \
  -H "Authorization: Bearer imn_seuconvenio_..." \
  -H "Content-Type: application/json" \
  -d '{
    "propertyType": "Apartamento",
    "transactionType": "sale",
    "city": "Belo Horizonte",
    "neighborhood": "Savassi",
    "salePrice": 780000,
    "characteristics": { "Quartos": 3, "Suítes": 1, "Vagas": 2 }
  }'

Regras importantes:

• Nasce em moderação. Todo imóvel criado por API entra como em_moderacao e não aparece em feed de portal até alguém do convênio liberar, dentro do produto.
• status não é aceito na inclusão.
• Características podem ir como objeto ({ "Quartos": 3 }) ou lista ([{ "name": "Quartos", "value": 3 }]).
• Valores inteiros em características number (3 sim, 3.5 não). Para fracionário, use os tipos decimal/currency/percent (o catálogo diz qual é qual).

🚧

Duplicidade por endereço

Se o endereço já existir, a resposta é 409 (DUPLICATE_ADDRESS) com a lista dos imóveis que casaram, para você alterar o existente em vez de criar outro.

4️⃣ Ative a situação (quando aprovado)

Depois que o imóvel for revisado, mude a situação com PATCH:

curl -X PATCH https://api.imoviewnext.com.br/pub/v1/properties/{id}/status \
  -H "Authorization: Bearer imn_seuconvenio_..." \
  -H "Content-Type: application/json" \
  -d '{ "status": "vendido" }'

O PATCH aceita: alugado, vendido, em_reforma, em_moderacao, desativado, em_desocupacao.

❗️

vago_disponivel não é aceito de propósito

É o único estado publicável, então liberar um imóvel para publicação é ação de gente, dentro do produto, não de uma chave de API.

✅ Depois de publicar

• Alterar: PUT /properties/{id} aceita o mesmo formato que a busca e o GET /{id} devolvem.
• Consultar: veja o guia de Buscar e sincronizar imóveis.
• Fotos: envie a URL pública da imagem em POST /properties/{id}/photos; o sistema baixa e processa a imagem (marca d'água e tamanhos do convênio). Altere, ordene e remova pelas rotas de fotos.
• Proprietários: vincule a pessoa ao imóvel em POST /properties/{id}/owners (a pessoa antes, em Cadastrar pessoas). A leitura traz só o vínculo (personId, percentual); os dados da pessoa ficam em GET /people/{id}.
• Etiquetas: POST e DELETE /properties/{id}/tags/{tagId}, com imoveis:write.
• Chaves: GET /properties/{id}/keys mostra os chaveiros e se a chave está emprestada (chaves:read).
• Lançamento: empreendimento com unidades tem rotas próprias em Lançamentos (lancamentos:write).