As consultas de toda a conta
GET /property-v1/leads?portal={portal}
Traz as consultas de todos os anúncios daquela imobiliária naquele portal, numa única chamada. Cada
lead informa de qual anúncio veio em data.property, então você não precisa perguntar anúncio por
anúncio.
Como ler o
data.property.code. É o código com que o anúncio existe no portal e, para os anúncios que você publicou, nós o montamos com o seu própriopaIdmais um sufixo de marca:01M416ACSSG7TXX172PDXSQFXF___mapapropé a sua propriedade01M416ACSSG7TXX172PDXSQFXF. Para casá-lo com a sua base, remova o sufixo___mapaprop— não corte no primeiro_, porque o seupaIdé o que você escolheu e pode conter qualquer coisa.⚠️ O sufixo NÃO basta para saber se o anúncio é seu. O método por conta traz as consultas de todos os anúncios daquela imobiliária, e o sufixo
___mapapropé levado por todos os que foram publicados pelo Mapaprop — não só pelos seus. A imobiliária pode ter publicado anúncios por outro caminho, e esses códigos levam o mesmo sufixo com um id que não é seu.⇒ Case contra a sua própria base, não contra o sufixo: remova o sufixo e procure o resultado nas suas propriedades. Se não estiver, esse lead é de um anúncio que a imobiliária publicou por outra via — não é um erro, e o correto é ignorá-lo.
É o método que convém usar. Veja por quê na introdução.
curl "https://property-api.mapaprop.com/property-v1/leads?portal=zonapropapi&fromDate=20260101" \
-H "Authorization: Bearer $TOKEN" \
-H "x-client-ref: cliente-42"
Os parâmetros
portal | obrigatório | zonapropapi · mapapropapi (a fonte Mapaprop) |
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 |
maxPages | quantas páginas buscamos no máximo | 20 |
size | quantos leads você quer no máximo | 100, que é o teto do portal |
O padrão de 7 dias é o de uma chamada sem parâmetros, para que um pedido sem data não tente trazer o histórico completo. Não é uma recomendação de frequência: a frequência você escolhe.
A resposta
{
"portal": "zonaprop",
"from": "20260101",
"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": "01M416ACSSG7TXX172PDXSQFXF___mapaprop" },
"raw": null
}
}
],
"total": 12,
"quota": { "remaining": 1346, "limit": 1500 }
}
Nesta fonte nenhum dos dois ids do portal identifica uma mensagem, e isso está medido sobre uma
conta inteira (33 mensagens de agosto): o source.ids.messageId chegou nulo em 23, e o
data.messageId —que nunca vem nulo e por isso é o que usamos para montar o eventId— teve 31
valores distintos para 33 mensagens, com dois pares genuinamente diferentes compartilhando um.
⇒ Deduplique com eventId + occurredAt. Os dois pares que compartilhavam o id estavam a cinco
dias um do outro, então a data os separa; se algum dia chegarem dois com as duas coisas iguais,
compare o conteúdo antes de descartar.
O objeto lead, campo por campo, está na introdução.
| Campo | O que é |
|---|---|
from | a janela que foi efetivamente usada (a sua, ou o padrão) |
to | o limite superior da janela que foi efetivamente aplicado. Aparece apenas se você enviar toDate |
leads | os leads. Pode vir vazio: significa que não houve consultas naquela janela |
total | quantos o portal diz que existem naquela janela. Pode ser maior que leads.length — veja abaixo |
quota | o saldo que o portal informou nesta chamada |
As páginas, e o que cada uma custa
Os leads vêm do mais novo para o mais antigo. Se na sua janela houver mais do que cabe em uma página,
percorremos as páginas por você até maxPages.
Cada página é uma chamada da cota mensal do seu cliente. A cota é da imobiliária e é compartilhada
com a publicação, então size e maxPages são decisões de custo, não apenas de conveniência. No
Zonaprop o máximo por página são 100, então maxPages: 20 significa até 2.000 leads e até 20 chamadas.
Se chegarmos ao teto antes de trazer tudo, a resposta informa isso:
{
"portal": "zonaprop",
"from": "20240101",
"leads": [ "… os que couberam …" ],
"total": 900,
"truncated": true,
"truncatedReason": "partial_portal_cap",
"detail": "Te devolvemos una parte, los más nuevos primero. Pedí el resto subiendo `maxPaginas` o acotando la ventana con `fromDate`/`toDate` — cada página es una llamada del cupo de la inmobiliaria.",
"pagesFetched": 20,
"quota": { "remaining": 1348, "limit": 1500 }
}
Na prática: se você consultar com frequência — uma vez por dia, digamos — tudo cabe em uma página e você nunca vai perder um lead. O teto só aparece quando você pede uma janela muito longa, por exemplo na primeira sincronização.
Se você paginar por conta própria em vez de usar maxPages, vai receber repetidos. A paginação do
Zonaprop sobrepõe a borda: a página seguinte repete o último lead da anterior. Nós descartamos e
informamos em warnings quando acontece.
toDate: sem hora, é o final daquele dia
?fromDate=20261001&toDate=20261013
Se você enviar toDate sem hora, tomamos como 20261013 23:59:59 — ou seja, o dia 13 entra. O
campo to da resposta devolve o valor que foi realmente aplicado, e informamos isso:
{
"from": "20261001",
"to": "20261013 23:59:59",
"warnings": [
"Tomamos `toDate` como el final de ese día (`20261013 23:59:59`). Sin la hora, el portal lo lee como las 00:00:00 y habría excluido el día entero. Mandá la hora si querés otro corte."
]
}
O portal lê uma data sem hora como 00:00:00, então um toDate=20261013 puro teria deixado de fora o
dia 13 inteiro sem que nada dissesse. Se você quiser outro corte, envie a hora (20261013 18:00:00) e
respeitamos tal como está.
Desde 2026-10-15 o toDate também é aplicado nesta listagem. Antes o portal o ignorava aqui e nós
documentávamos assim: se você filtrava por data do seu lado para compensar, já não é necessário.
A conta Mapaprop (mapapropapi)
GET /property-v1/leads?portal=mapapropapi
Não é um portal: são as consultas que entraram pela conta Mapaprop do seu cliente — o site dele, o chat dele, o portal da Mapaprop, ou um portal que as deixa lá. É lido com o mesmo endpoint e a resposta tem o mesmo formato, então você não escreve uma segunda leitura.
As quatro diferenças, e vale tê-las em mente:
| Um portal | mapapropapi | |
|---|---|---|
| Cota | cada página é uma chamada da cota da imobiliária | 🟢 não gasta cota de ninguém: a fonte é o nosso próprio banco de dados |
quota | vem | não vem — enviar um zero a você seria lido como "não resta nada" |
total | quantos o portal diz que há na janela | quantos trouxemos a você. Contar a janela dobraria o custo de cada página, então não inventamos: para saber se restam mais, olhe o truncated |
| Padrões | size 100 · maxPages 20 | size 50 · maxPages 1 |
⚠️ Por padrão trazemos uma única página de 50. Se houver mais naquela janela, a resposta traz
truncated: true e um notices informando. Como paginar é gratuito, aumente o maxPages com confiança —
o único limite é o tamanho da resposta.
Como você identifica o imóvel nesta fonte
Com data.property.propertyId, que é o id do imóvel no Mapaprop.
Não com paId nem com code: esses dois são seus — o paId é você que escolhe ao cadastrar
pela API — e só existem se aquele imóvel nasceu pelo PropertyAPI. As consultas desta fonte chegam
à conta do Mapaprop do seu cliente, e lá o imóvel pode ter sido cadastrado à mão, importado de outro
sistema ou vindo de um portal. Nesses casos ninguém escolheu um paId, então ele viaja como
null:
"property": { "propertyId": 2617621, "paId": null, "code": null }
Se o imóvel foi você que publicou pela API, chegam os três.
📌 E há consultas que não são sobre nenhum imóvel — alguém que escreve para a imobiliária, não
sobre um anúncio: aí o bloco inteiro vem como null. Vale ter os dois caminhos no seu código.
A janela tem um teto: um ano
{ "error": "window_too_wide", "detail": "La ventana no puede ser mayor a un año. Acotá `fromDate`/`toDate` y paginá.", "portal": "mapapropapi" }
Um 400. É o único parâmetro que esta fonte valida de forma diferente dos portais.
Um pedido mal formado volta como 400, não como 502
{ "error": "invalid_request", "detail": "fromDate must be a date, as yyyy-MM-dd", "portal": "mapapropapi" }
O detail traz o motivo tal como a fonte o diz, então dá para ler e corrigir: repetir não muda
nada. O 502 mapaprop_unavailable fica para o que realmente significa — que não conseguimos falar
com o Mapaprop — e esse sim vale a pena repetir.
📌 A data é aceita nas duas formas: YYYYMMDD (a da tabela acima) e yyyy-MM-dd.
Hoje serve para a SUA conta, não para as dos seus clientes
{ "error": "no_mapaprop_account", "detail": "Los leads de esta fuente son de una cuenta de Mapaprop, y este token no corresponde a ninguna.", "portal": "mapapropapi" }
Um 400, e você quer saber disso antes de escrever o código: esta fonte resolve a conta a partir do
seu token, então funciona se o seu token veio de uma conta Mapaprop. Se você é uma plataforma cujos
clientes têm conta Mapaprop, o que serve para você hoje é
o webhook — por ali sim chegam as consultas dos seus clientes, sem
que você precise pedi-las. É a mesma limitação de
branches, e vamos resolvê-la: escreva para
dev@mapaprop.com se isso bloquear você.
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 |
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: consultar não modifica nada |
Uma conta desativada não bloqueia esta consulta: os leads que já entraram são do seu cliente e podem ser recuperados do mesmo jeito.
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.