Property API
Publique os seus imóveis em vários portais imobiliários com um único modelo. A Mapaprop já implementou as APIs de cada portal, então, em vez de integrar uma por uma, você nos envia o objeto uma vez e nós o traduzimos.
📋 Antes de ir para produção, veja Mudanças da API — e depois, de vez em quando. É a lista do que mudou, com a sua data: um campo que saiu, um novo, um comportamento diferente. É curta de propósito: só entra o que te obriga a fazer algo.
property-v1 não muda de versão, então essa é a única forma de saber se algo se moveu desde que
você escreveu a sua integração.
Antes de tudo: as suas credenciais
Para chamar qualquer endpoint desta seção você precisa de um access token, e para isso a sua aplicação tem que estar registrada.
Primeiros passos com OAuth2 — você registra a sua aplicação, nós lhe damos as suas credenciais e com elas você obtém o token
Três coisas de lá que convém ter claras antes de seguir:
| O token vence | em 14 dias. Um 403 inesperado costuma ser isso, não um problema de permissões |
| Você não envia um identificador da sua app | ele viaja dentro do token e nós o resolvemos. Não há nada a configurar nem nenhum id para guardar |
| O da sua app e o de cada cliente são dois níveis | hoje a única coisa que se configura no nível da sua app são os webhooks. Todo o resto — o cadastro do cliente, as contas de portal dele, os imóveis dele — vai por cliente, com o header x-client-ref |
Há duas formas de chegar aqui, e o token é obtido de maneira diferente em cada uma.
Se você é um integrador —o seu aplicativo publica o inventário de outras imobiliárias— você
registra o seu aplicativo e obtém o token com client_id/client_secret, como descrito acima.
Se você é cliente da Mapaprop e quer automatizar a sua própria conta, você não registra nada: contrata a Property API e ativa o seu Token de API com um clique a partir de Configurações > API Token. É o mesmo token para todos os seus serviços de API, e ele não expira. Como fazer: Property API Token.
Boas práticas — os fluxos completos
Esta página lista a API por recurso: o que cada endpoint faz. Se o que você precisa é a ordem —o que vem antes do quê, o que você decide em cada passo e o que custa— essa é a outra metade da documentação, e convém começar por ali.
Boas práticas — as quatro regras que valem para todos os fluxos: o que se faz uma vez e o que cada vez, o que é gratuito e o que gasta cota, o que guardar do seu lado e o que acontece se você tentar de novo
Cadastrar um cliente — uma única vez por cliente, e a única bifurcação real: link ou credencial, conforme o portal
Publicar um anúncio — o caso base, de ponta a ponta
Publicar um empreendimento — as unidades vêm antes do empreendimento; aqui a ordem é o conteúdo
Receber consultas — o único fluxo em que você não empurra, recebe
Dar baixa — baixar um anúncio, desconectar uma conta e apagar um cliente são três coisas distintas
Quando algo não sai — por onde começar a olhar, do gratuito ao caro
1. Comece por aqui
Nesta ordem: primeiro você entende o modelo, depois monta o objeto e o testa, e só então declara o seu cliente e conecta as contas de portal dele. Sem uma conta conectada não é possível publicar.
O modelo de imóvel — por que as chaves são as mesmas em todos os países
O objeto JSON do imóvel — os campos, as suas regras e quais são obrigatórios
POST /properties/verify — verifique o seu objeto antes de publicar. Não cria nem publica nada
Clientes — declare-a uma vez; os imóveis dela herdam o nome, o telefone e o e-mail
Conectar as contas de portal dele — Argenprop, Cabaprop e MercadoLibre: você guarda o token que já tem
Conectar com um link — Zonaprop: o seu cliente autoriza a partir de um link que você envia
Consultar e desconectar — o estado das conexões do seu cliente, e desvincular
POST /properties — o cadastro: salva o imóvel, devolve o paId e guarda suas imagens nos nossos servidores
1B. Empreendimentos imobiliários
Um edifício na planta, um condomínio fechado, uma torre em construção. São enviados pelo mesmo endpoint que um imóvel —não há um modelo novo a aprender— e devolvemos os números calculados das unidades: disponibilidade, comercialização separando venda de locação, m², faixa de preços por moeda e distribuição por tipologia.
O objeto JSON do empreendimento — o grupo development, seus campos e como as unidades são declaradas
Verificar e cadastrar um empreendimento — o fluxo, a ordem que funciona e o que validamos a mais
developmentStats — os números calculados das unidades, campo por campo
2. Catálogo
Os dados de referência de que você precisa para mapear o seu sistema contra o nosso. São baixados uma vez e armazenados: não são endpoints para chamar a cada cadastro de imóvel.
Zonas — como mapear as suas contra as nossas, e qual é o formato do código
GET /property-catalog-v1/zones — a lista completa de um país, paginada
A cascata: zones1 / zones2 / zones3 — as mesmas zonas, um nível por vez
GET /property-attributes — tipos, operações, status e comodidades
3. Publicar
Publicar em um portal — publique um imóvel já cadastrado no portal do seu cliente
Despublicar de um portal — retirar o anúncio. É idempotente
Consultar o estado no portal — a URL do anúncio, se continua online e as visitas. ⚠️ gasta uma chamada da cota do cliente
A chave publication — a configuração por portal
GET /properties/{paId} — consultar um imóvel
GET /properties — listar todos os de um cliente, com o estado de cada portal
PUT /properties/{paId} — modificar: substituição total, com diff do que mudou
DELETE /properties/{paId} — excluir. Não dá baixa nos seus anúncios nos portais
4. Leads
Leads — o que é um lead, o objeto que devolvemos, a cota compartilhada e por que não os armazenamos
As consultas de toda a conta — uma chamada traz as de todos os anúncios. É o caminho normal
As consultas de um imóvel — as de um anúncio específico
Qual modo cada portal suporta — se nesse portal as consultas são solicitadas ou chegam sozinhas. Leia em vez de supor