Leads
Quando alguém vê um anúncio do seu cliente num portal e deixa uma consulta, isso é um lead: o nome, o e-mail, o telefone e o que a pessoa escreveu.
Esta API entrega esses dados a você. Você escolhe quando pedi-los — não há nada a esperar nem horário a cumprir.
Os métodos
| O que traz | Scope | |
|---|---|---|
| As consultas de toda a conta | todas as dessa imobiliária, de todos os anúncios dela | {portal}:leads |
| As consultas de um imóvel | apenas as desse anúncio | {portal}:leads |
| Qual modo cada portal suporta | não traz consultas: informa se nesse portal elas são solicitadas ou chegam sozinhas | property-api-catalog |
O terceiro tem um scope diferente de propósito. Os dois primeiros trazem dados pessoais dos interessados, por isso são concedidos portal por portal. O terceiro não traz nenhuma consulta — apenas informa como cada portal funciona — e fala sobre todos ao mesmo tempo, por isso usa o scope do catálogo, o mesmo das zonas e dos atributos.
Comece pelo de toda a conta. Cada lead informa de qual anúncio veio, então uma única chamada traz tudo: é o caminho normal. O de um imóvel existe para quando você quer olhar apenas um — o detalhe de um anúncio no seu painel — e não faz sentido trazer o resto.
E há uma fonte que não é um portal: mapapropapi. São as consultas que chegam na conta Mapaprop
do seu cliente — pelo site dele, pelo chat dele, ou por um portal que as deixa lá. São pedidas da
mesma forma (?portal=mapapropapi) e têm uma vantagem: não gastam cota de nenhum portal, porque
não há portal no meio. Você pode paginar sem contar chamadas.
O que elas têm é um limite de janela: um ano para trás por consulta.
A nossa sugestão: não percorra os seus anúncios um por um. Com 500 anúncios e uma consulta por dia seriam 15.000 chamadas por mês; com o método por conta, o mesmo dá ~30. No Zonaprop, cuja cota habitual é de 1.500 chamadas por mês por imobiliária (ver a cota do Zonaprop), o primeiro não cabe e o segundo usa 2 %.
A cota é definida por cada portal, portanto o número muda dependendo do portal. O que não muda é a proporção: uma chamada por conta sempre vai custar muito menos que uma por anúncio.
O objeto lead
É o mesmo nos dois métodos, e o mesmo que chega a você pelo webhook. Um único formato para ler, não importa de onde veio a consulta nem por qual porta você a recebeu.
{
"eventId": "evt_1622087_c",
"event": "lead.created",
"occurredAt": "2026-11-15T03:07:08Z",
"clientRef": "cliente-42",
"source": {
"source": "mapaprop",
"case": "zonaprop",
"subcase": "api",
"ids": {
"messageId": "322337250",
"adId": "56801168",
"contactId": "49474924",
"actionId": "10"
}
},
"data": {
"questionId": "1622087",
"messageId": null,
"direction": "incoming",
"message": "Hola, quería coordinar una visita",
"contact": { "name": "Lucía", "email": "lucia@ejemplo.com", "phone": "1156781234" },
"customer": { "customerId": 441 },
"property": { "propertyId": 2610019, "paId": null, "code": null },
"raw": null
}
}
O envelope
| Campo | O que é |
|---|---|
eventId | o identificador deste evento. É estável: se o reenviarmos, chega com o mesmo. É com ele que você deduplica |
event | lead.created quando a conversa nasce · lead.message quando chega uma mensagem nova de uma que já existia |
occurredAt | quando aconteceu, em ISO-8601 UTC. É a hora da origem, não a nossa |
clientRef | de qual cliente seu é |
source | de onde veio — veja abaixo |
De onde veio
| Campo | O que é |
|---|---|
source.case | zonaprop, argenprop, mercadolibre, cabaprop, website, chat-ai, portal-mapaprop, network-search, network-site, feed |
source.subcase | o canal dentro desse caso quando há mais de um (api ou xml no Zonaprop e no Argenprop). null se o caso tem apenas um |
source.ids | os ids que essa origem usa para a mesma mensagem. Servem para cruzar com os relatórios dela; você não precisa usá-los |
A consulta
| Campo | O que é |
|---|---|
questionId | a conversa. Duas mensagens com o mesmo questionId são a mesma thread — é o que permite juntá-las em vez de criar duas consultas |
messageId | a mensagem dentro dessa conversa. Chega como null em um lead.created, porque esse evento é o nascimento |
direction | sempre incoming quando chega a você: só enviamos o que entrou |
message | o que a pessoa interessada escreveu |
contact | name, email, phone. Qualquer um pode vir como null: nem toda origem exige todos |
customer | a conta Mapaprop, quando esse cliente tem uma |
property | veja abaixo |
raw | reservado. Hoje chega como null |
O imóvel, e o que significa quando ele não vem
| Campo | O que é |
|---|---|
property.propertyId | o id do imóvel na Mapaprop |
property.code | o código com o qual o anúncio vive no portal |
property.paId | o seu id. Hoje chega sempre como null — veja abaixo |
🔴 Qual id chega a você depende da fonte, e a diferença importa:
propertyId | code | paId | |
|---|---|---|---|
Um portal (zonapropapi) | — | ✅ o código do anúncio | — |
A conta Mapaprop (mapapropapi) | ✅ | — | — |
⇒ Não escreva o seu cruzamento com base em um único campo. Em um portal você cruza por code
(como lê-lo); na conta Mapaprop, por propertyId, que é o
mesmo id que o GET do imóvel devolve.
O paId está no contrato e hoje não é preenchido por nenhuma das duas: você vai vê-lo chegar sem
precisar mudar nada, e enquanto isso ele não serve para cruzar.
property: null significa que a pessoa não perguntou por nenhum, nunca que não conseguimos
resolvê-lo. Acontece com frequência: 16,9 % das consultas não são sobre um anúncio em
particular, e no MercadoLibre são 34 %. São consultas igualmente válidas — alguém que escreve para
perguntar sobre a região, por exemplo — e é preciso poder recebê-las.
Para reconhecer um lead: use o eventId
O eventId vem do fato, não da tentativa. Se um reenvio trouxer a mesma consulta duas vezes, as
duas chegam com o mesmo eventId — então guardá-lo já é suficiente para não duplicar.
A exceção: os leads que não passam por uma conta Mapaprop. Ali não há uma conversa nossa para
nomear, então o eventId é montado com o id que a origem envia e chega com o prefixo evt_src_. E no
Zonaprop esse id, medido, não é único: a mesma pessoa escrevendo duas vezes sobre o mesmo anúncio
em dias diferentes chega com o mesmo número e um occurredAt diferente.
⇒ Se você recebe leads desse tipo, acrescente o occurredAt à chave. Você os reconhece porque o
eventId começa com evt_src_ e o questionId vem como null.
Este formato substituiu o anterior em 20 de novembro de 2026. O de antes era plano (id,
propertyCode, name…). O detalhe da mudança e a equivalência campo por campo estão em
Mudanças da API.
O que fica guardado e o que não
A API não guarda os leads dos portais. Perguntamos ao portal, passamos a resposta a você e nada fica conosco: nem o nome, nem o e-mail, nem o telefone, nem a mensagem. Não existe um banco de dados de leads de portal do nosso lado.
A fonte mapapropapi é diferente, e a diferença é de origem. Essas consultas nasceram na
conta Mapaprop do seu cliente — pelo site dele, pelo chat dele ou pelo portal da Mapaprop —, então
vivem na caixa de entrada dele porque foi ali que entraram: não as guardamos para trazê-las a você.
São dados do seu cliente, na conta dele, e ele continua vendo-as e respondendo-as a partir da Mapaprop.
⇒ A consequência prática é boa: essas você pode pedir de novo sempre, até um ano para trás.
Duas consequências práticas do que foi dito acima, que vale ter em mente ao desenhar a sua integração:
- Armazená-los é trabalho seu. Se você não os persistir ao recebê-los, eles se perdem — não podemos buscá-los novamente num histórico nosso, porque ele não existe.
- Você pode pedir o mesmo quantas vezes quiser. Não controlamos o que já entregamos, então pedir uma janela que você já pediu devolve os mesmos leads. É de propósito: se o seu sistema perder um, você pode trazê-lo de novo. Quem decide o que é novo é você, com a chave acima.
A cota do portal
Cada consulta a um portal gasta uma chamada da cota mensal que esse portal concede à imobiliária.
🟢 O mapapropapi não gasta cota de ninguém — não há portal no meio, então ali você pode paginar
sem contar chamadas e esta seção não se aplica a você.
Cada portal tem a sua própria cota, as suas próprias regras e a sua própria página. Hoje o único com o serviço construído é o Zonaprop; à medida que incorporarmos outros, cada um acrescenta a sua.
| Portal | A cota | Onde está o detalhe |
|---|---|---|
| Zonaprop | 1.500 chamadas por mês por imobiliária (cota habitual) | Cota mensal e limites |
A cota é compartilhada com a publicação. No Zonaprop, publicar um anúncio, consultar o status dele e trazer estas consultas consomem a mesma cota. Se você esgotá-la trazendo leads, o seu cliente não consegue publicar até o mês seguinte. O que consome e o que não, operação por operação, está em Cota mensal e limites.
Cada resposta informa como está o saldo:
"quota": { "remaining": 1346, "limit": 1500 }
Esse número é o que o portal informou naquela chamada, não um valor ao vivo. Se a imobiliária também publicar no portal fora do seu sistema, o saldo real cai sem que nenhum dos dois perceba.
Uma referência para escolher a sua frequência, com o método por conta:
| De quanto em quanto tempo você consulta | Chamadas por mês | Da cota |
|---|---|---|
| uma vez por dia | ~30 | 2 % |
| a cada 6 horas | ~120 | 8 % |
| uma vez por hora | ~720 | 48 % |
Quais portais
| Portal | Como as consultas são obtidas hoje |
|---|---|
Zonaprop (zonapropapi) | você vai buscá-las, com os dois métodos desta seção |
Argenprop (argenpropapi) | elas chegam até você, na URL que você declara em Webhooks. Não tem os métodos desta seção: um pedido aqui devolve 501 |
A conta Mapaprop (mapapropapi) | as duas: você vai buscá-las com o método por conta, e além disso elas chegam por webhook |
| Os demais | ainda não, de nenhuma das duas formas |
Não são dois níveis da mesma coisa: são dois mecanismos diferentes, e um portal pode ter um e não o
outro. Se você for buscar as consultas de um portal que apenas empurra, o 501 diz qual dos dois
serviços falta — mas perguntar não custa nada e é melhor do que descobrir assim:
Capacidades responde isso para todos os portais de uma vez, e
é o mesmo dado que o nosso próprio código usa.
A permissão
Os dois métodos exigem o scope {portal}:leads — por exemplo zonapropapi:leads.
Ter {portal}:publish não basta. São permissões diferentes de propósito: trazer leads é acessar
dados pessoais de terceiros — as pessoas que consultaram sobre um anúncio — e isso não é concedido
junto com a publicação. Se você precisar das duas coisas, os dois scopes são concedidos.