BETA

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 trazScope
As consultas de toda a contatodas as dessa imobiliária, de todos os anúncios dela{portal}:leads
As consultas de um imóvelapenas as desse anúncio{portal}:leads
Qual modo cada portal suportanão traz consultas: informa se nesse portal elas são solicitadas ou chegam sozinhasproperty-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

CampoO que é
eventIdo identificador deste evento. É estável: se o reenviarmos, chega com o mesmo. É com ele que você deduplica
eventlead.created quando a conversa nasce · lead.message quando chega uma mensagem nova de uma que já existia
occurredAtquando aconteceu, em ISO-8601 UTC. É a hora da origem, não a nossa
clientRefde qual cliente seu é
sourcede onde veio — veja abaixo

De onde veio

CampoO que é
source.casezonaprop, argenprop, mercadolibre, cabaprop, website, chat-ai, portal-mapaprop, network-search, network-site, feed
source.subcaseo 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.idsos 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

CampoO que é
questionIda conversa. Duas mensagens com o mesmo questionId são a mesma thread — é o que permite juntá-las em vez de criar duas consultas
messageIda mensagem dentro dessa conversa. Chega como null em um lead.created, porque esse evento é o nascimento
directionsempre incoming quando chega a você: só enviamos o que entrou
messageo que a pessoa interessada escreveu
contactname, email, phone. Qualquer um pode vir como null: nem toda origem exige todos
customera conta Mapaprop, quando esse cliente tem uma
propertyveja abaixo
rawreservado. Hoje chega como null

O imóvel, e o que significa quando ele não vem

CampoO que é
property.propertyIdo id do imóvel na Mapaprop
property.codeo código com o qual o anúncio vive no portal
property.paIdo seu id. Hoje chega sempre como null — veja abaixo

🔴 Qual id chega a você depende da fonte, e a diferença importa:

propertyIdcodepaId
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:

  1. 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.
  2. 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.

PortalA cotaOnde está o detalhe
Zonaprop1.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ê consultaChamadas por mêsDa cota
uma vez por dia~302 %
a cada 6 horas~1208 %
uma vez por hora~72048 %

Quais portais

PortalComo 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 demaisainda 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.