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 vem com o seu propertyCode, então você sabe de qual anúncio é sem precisar perguntar anúncio por
anúncio.
É 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 |
fromDate | a partir de qual data, formato YYYYMMDD | se você não enviar, os últimos 7 dias |
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": [
{
"id": "322337250",
"propertyCode": "2605257___mapaprop",
"name": "Lucía",
"email": "lucia@ejemplo.com",
"phone": "1156781234",
"message": "Hola, quería coordinar una visita",
"date": 1790878040000,
"portalMessageId": null,
"portalAdId": 56801168,
"portalContactId": 49474924,
"portalActionId": 10
}
],
"total": 12,
"quota": { "remaining": 1346, "limit": 1500 }
}
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) |
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 |
O teto por pedido é definido pelo portal
No Zonaprop são 100 por pedido, entregues do mais novo para o mais antigo. Cada portal define o seu: quando incorporarmos outros, esta seção acrescenta o caso deles.
Se na sua janela houver mais de 100, entregamos os 100 mais novos e a resposta informa isso:
{
"portal": "zonaprop",
"from": "20240101",
"leads": [ "… 100 leads …" ],
"total": 386,
"truncated": true,
"truncatedReason": "parcial_tope_del_portal",
"detail": "Te devolvemos los más nuevos. Para ver los anteriores, mové `fromDate`: el portal no permite pedir la página siguiente de este listado.",
"warnings": [
"El portal informa 386 mensajes en esa ventana y devuelve como máximo 100 por pedido, los más nuevos primero. Para ver los anteriores, mové `fromDate`."
],
"quota": { "remaining": 1348, "limit": 1500 }
}
Não existe "página seguinte" nesta listagem: o portal não a oferece. Para ver os anteriores aos 100
que você recebeu, mova o fromDate para trás e faça outra consulta.
O que isso significa na prática: se você consultar com frequência — uma vez por dia, digamos — nunca vai chegar a 100 e nunca vai perder um lead. O teto só aparece quando você pede uma janela muito longa, por exemplo na primeira sincronização.
toDate: o portal ignora nesta listagem
Se você enviar, não aplicamos e informamos em warnings:
"warnings": [
"Zonaprop ignora `toDate` cuando se piden los mensajes de toda la cuenta: el filtro no se aplicó. Acotá con `fromDate`."
]
Preferimos avisar a você do que repassar ao portal e ele descartar em silêncio: se fizéssemos isso, você
acreditaria que a sua janela foi respeitada e receberia leads posteriores ao seu toDate.
Para limitar o limite superior, filtre do seu lado com o campo date de cada lead. No
método por imóvel, o toDate funciona.
Os erros
| Quando | O que fazer | |
|---|---|---|
400 portal_requerido | 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_no_soportado | 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.