Las consultas de toda la cuenta
GET /property-v1/leads?portal={portal}
Trae las consultas de todos los avisos de esa inmobiliaria en ese portal, en una sola llamada. Cada
lead viene con su propertyCode, así que sabés de qué aviso es sin tener que preguntar aviso por aviso.
Es el método que conviene usar. Ver por qué en la introducción.
curl "https://property-api.mapaprop.com/property-v1/leads?portal=zonapropapi&fromDate=20260101" \
-H "Authorization: Bearer $TOKEN" \
-H "x-client-ref: cliente-42"
Los parámetros
portal | obligatorio | zonapropapi |
fromDate | desde qué fecha, formato YYYYMMDD | si no lo mandás, los últimos 7 días |
size | cuántos leads querés como máximo | 100, que es el techo del portal |
El default de 7 días es el de una llamada sin parámetros, para que un pedido sin fecha no intente traer el historial completo. No es una recomendación de frecuencia: la frecuencia la elegís vos.
La respuesta
{
"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 }
}
El objeto lead, campo por campo, está en la introducción.
| Campo | Qué es |
|---|---|
from | la ventana que efectivamente se usó (la tuya, o el default) |
leads | los leads. Puede venir vacío: significa que no hubo consultas en esa ventana |
total | cuántos dice el portal que hay en esa ventana. Puede ser mayor que leads.length — ver abajo |
quota | el saldo que el portal informó en esta llamada |
El tope por pedido lo fija el portal
En Zonaprop son 100 por pedido, y los entrega de los más nuevos a los más viejos. Cada portal fija el suyo: cuando incorporemos otros, esta sección suma su caso.
Si en tu ventana hay más de 100, te damos los 100 más nuevos y la respuesta te lo dice:
{
"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 }
}
No hay "página siguiente" en este listado: el portal no la ofrece. Para ver los anteriores a los 100
que recibiste, mové fromDate hacia atrás y hacé otra consulta.
Qué significa esto en la práctica: si consultás seguido —una vez por día, digamos— nunca vas a llegar a 100 y nunca vas a perder un lead. El tope sólo aparece cuando pedís una ventana muy larga, por ejemplo al sincronizar por primera vez.
toDate: el portal lo ignora en este listado
Si lo mandás, no lo aplicamos y te lo decimos en warnings:
"warnings": [
"Zonaprop ignora `toDate` cuando se piden los mensajes de toda la cuenta: el filtro no se aplicó. Acotá con `fromDate`."
]
Preferimos decírtelo antes que pasárselo al portal y que lo descarte en silencio: si lo hiciéramos,
creerías que tu ventana se respetó y recibirías leads posteriores a tu toDate.
Para acotar hacia adelante, filtralo de tu lado con el campo date de cada lead. En
el método por propiedad toDate sí funciona.
Los errores
| Cuándo | Qué hacer | |
|---|---|---|
400 portal_requerido | falta ?portal= | mandalo |
| 403 | te falta el scope {portal}:leads | pedinos que te lo otorguemos |
409 portal_not_connected | esa cuenta no está conectada a ese portal | conectala |
409 portal_account_unlinked | la desvincularon del lado del portal | hay que volver a conectarla |
429 portal_quota_exhausted | la inmobiliaria agotó su cupo del mes | esperar al mes siguiente. El cupo se comparte con publicar — ver el cupo de Zonaprop |
501 leads_no_soportado | ese portal todavía no ofrece este servicio | — |
502 portal_rejected | el portal no contestó o rechazó la consulta | reintentar es seguro: consultar no modifica nada |
Una cuenta dada de baja no bloquea esta consulta: los leads que ya entraron son de tu cliente y los puede recuperar igual.