As consultas de um imóvel
GET /property-v1/properties/{paId}/leads?portal={portal}
Traz as consultas de um anúncio, o do imóvel que você indicar.
Para trazer tudo, use o método por conta. Percorrer os seus imóveis um por um gasta uma chamada da cota para cada um, e com o outro método vêm todas numa só. Este método é para quando você quer olhar apenas um — o detalhe de um anúncio no seu painel.
curl "https://property-api.mapaprop.com/property-v1/properties/01M41AQNXYG4W4SEEEEPHEDNX4/leads?portal=zonapropapi&fromDate=20260101" \
-H "Authorization: Bearer $TOKEN" \
-H "x-client-ref: cliente-42"
Os parâmetros
portal | obrigatório | zonapropapi |
fromDate | a partir de qual data. YYYYMMDD, ou opcionalmente YYYYMMDD HH:mm:ss | se você não enviar, os últimos 7 dias |
toDate | até qual data, mesmo formato | sem limite |
size | quantos leads por página | 100 |
maxPages | quantas páginas buscamos no máximo | 20 |
Envie o fromDate sempre que quiser mais do que o muito recente. Sem uma janela explícita o portal usa
uma própria, bem estreita: o mesmo anúncio que devolve 8 consultas com fromDate de nove meses atrás
devolve 1 sem o parâmetro. Se você não enviar, parece que o anúncio quase não teve consultas.
A resposta
{
"portal": "zonaprop",
"paId": "2605257",
"from": "20260101",
"to": "20260601",
"leads": [
{
"eventId": "evt_src_322337250",
"event": "lead.created",
"occurredAt": "2026-11-15T03:07:08Z",
"clientRef": "cliente-42",
"source": {
"source": "mapaprop",
"case": "zonaprop",
"subcase": "api",
"ids": { "messageId": null, "adId": "56801168", "contactId": "49474924", "actionId": "10" }
},
"data": {
"questionId": null,
"messageId": "322337250",
"direction": "incoming",
"message": "Hola, quería coordinar una visita",
"contact": { "name": "Lucía", "email": "lucia@ejemplo.com", "phone": "1156781234" },
"customer": null,
"property": { "propertyId": null, "paId": null, "code": "2605257___mapaprop" },
"raw": null
}
}
],
"total": 8,
"quota": { "remaining": 1346, "limit": 1500 }
}
É a mesma forma do método por conta, mais o paId que você pediu.
Este método não existe para mapapropapi. Essa fonte é pedida apenas
por conta, porque nem toda consulta que entra em uma conta
Mapaprop é sobre um anúncio — 16,9 % não são — e pedi-las por imóvel deixaria de fora justamente
as que não podem ser pedidas de outra forma.
Capacidades diz isso com byProperty: false.
O objeto lead, campo por campo, está na introdução.
O to aparece apenas se você enviou o toDate, e traz o valor que foi realmente aplicado.
Um toDate sem hora é o final daquele dia. Se você enviar 20261013, tomamos como
20261013 23:59:59 para que o dia 13 entre, e informamos isso em warnings. O portal lê uma data sem
hora como 00:00:00, então um puro teria deixado o dia inteiro de fora. Se você quiser outro corte,
envie a hora (20261013 18:00:00) e respeitamos tal como está.
Se o anúncio não está no portal
Não é um erro: é 200, com a lista vazia e o motivo.
{
"portal": "zonaprop",
"paId": "01M41AQNXYG4W4SEEEEPHEDNX4",
"from": "20260929",
"leads": [],
"total": 0,
"notPublishedOnPortal": true,
"detail": "Ese aviso no figura en esa inmobiliaria del portal, así que no tiene consultas. Puede que todavía no se haya publicado, que el portal lo haya dado de baja, o que esté publicado bajo otra cuenta.",
"quota": { "remaining": 1346, "limit": 1500 }
}
O portal nos diz "esse anúncio não consta nesta imobiliária" e nada mais, então não podemos dizer a você qual das três razões é. Preferimos nomear as três a escolher uma e arriscar mandar você procurar onde não está.
O imóvel existe no seu inventário — se não existisse, a resposta seria um 404.
Os erros
| Quando | O que fazer | |
|---|---|---|
400 portal_required | falta o ?portal= | envie-o |
| 403 | falta a você o scope {portal}:leads | peça para concedermos |
404 property_not_found | aquele paId não está no seu inventário | verifique o id. Não gasta cota: paramos antes de perguntar ao portal |
409 portal_not_connected | aquela conta não está conectada àquele portal | conecte-a |
409 portal_account_unlinked | foi desvinculada do lado do portal | é preciso conectá-la de novo |
429 portal_quota_exhausted | a imobiliária esgotou a cota do mês | aguardar o mês seguinte. A cota é compartilhada com a publicação — ver a cota do Zonaprop |
501 leads_not_supported | aquele portal ainda não oferece este serviço | — |
502 portal_rejected | o portal não respondeu ou rejeitou a consulta | tentar de novo é seguro |
Antes de montar a chamada, veja qual modo esse portal suporta.
Não todos oferecem este serviço, e assim você descobre como dado em vez de por um 501.