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 te dice de qué aviso vino en data.property, así que no tenés que preguntar aviso por aviso.
Cómo leer el
data.property.code. Es el código con el que el aviso vive en el portal, y para los avisos que publicaste vos lo armamos con tu propiopaIdmás un sufijo de marca:01M416ACSSG7TXX172PDXSQFXF___mapapropes tu propiedad01M416ACSSG7TXX172PDXSQFXF. Para machearlo contra tu base, quitá el sufijo___mapaprop— no cortes en el primer_, porque tupaIdes el que vos elegiste y puede contener cualquier cosa.⚠️ El sufijo NO alcanza para saber si el aviso es tuyo. El método por cuenta trae las consultas de todos los avisos de esa inmobiliaria, y el sufijo
___mapaproplo llevan todos los que se publicaron por Mapaprop — no sólo los tuyos. La inmobiliaria pudo haber publicado avisos por otro camino, y esos códigos llevan el mismo sufijo con un id que no es tuyo.⇒ Macheá contra tu propia base, no contra el sufijo: quitale el sufijo y buscá el resultado en tus propiedades. Si no está, ese lead es de un aviso que la inmobiliaria publicó por otra vía — no es un error, y lo correcto es ignorarlo.
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 · mapapropapi (la fuente Mapaprop) |
fromDate | desde qué fecha. YYYYMMDD, u opcionalmente YYYYMMDD HH:mm:ss | si no lo mandás, los últimos 7 días |
toDate | hasta qué fecha, mismo formato | sin tope |
size | cuántos leads por página | 100, que es el máximo por pedido |
maxPages | cuántas páginas traemos como máximo | 20 |
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": [
{
"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 }
}
En esta fuente ninguno de los dos ids del portal identifica un mensaje, y está medido sobre una
cuenta entera (33 mensajes de agosto): source.ids.messageId llegó nulo en 23, y data.messageId
—que nunca viene nulo y por eso es el que usamos para armar el eventId— tuvo 31 valores distintos
para 33 mensajes, con dos pares genuinamente distintos compartiendo uno.
⇒ Dedupeá con eventId + occurredAt. Los dos pares que compartían id estaban a cinco días uno
del otro, así que la fecha los separa; si alguna vez te llegan dos con las dos cosas iguales,
compará el contenido antes de descartar.
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) |
to | el tope de la ventana que efectivamente se aplicó. Aparece sólo si mandaste toDate |
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 |
Las páginas, y lo que cada una cuesta
Los leads vienen de los más nuevos a los más viejos. Si en tu ventana hay más de los que entran en
una página, recorremos las páginas por vos hasta maxPages.
Cada página es una llamada del cupo mensual de tu cliente. El cupo es de la inmobiliaria y se
comparte con publicar, así que size y maxPages son decisiones de costo, no sólo de comodidad.
En Zonaprop el máximo por página son 100, así que maxPages: 20 son hasta 2.000 leads y hasta 20
llamadas.
Si llegamos al tope antes de traer todo, la respuesta te lo dice:
{
"portal": "zonaprop",
"from": "20240101",
"leads": [ "… los que entraron …" ],
"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 }
}
En la práctica: si consultás seguido —una vez por día, digamos— entra todo en una página 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.
Si paginás por tu cuenta en vez de usar maxPages, vas a recibir repetidos. El paginado de
Zonaprop solapa el borde: la página siguiente repite el último lead de la anterior. Nosotros lo
descartamos y te lo decimos en warnings cuando pasa.
toDate: sin hora, es el final de ese día
?fromDate=20261001&toDate=20261013
Si mandás toDate sin hora, lo tomamos como 20261013 23:59:59 — o sea que el 13 entra. El
campo to de la respuesta te devuelve el valor que se aplicó de verdad, y te lo avisamos:
{
"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."
]
}
El portal lee una fecha sin hora como las 00:00:00, así que toDate=20261013 a secas te habría
dejado afuera todo el día 13 sin que nada lo dijera. Si querés otro corte, mandá la hora
(20261013 18:00:00) y la respetamos tal cual.
Desde el 2026-10-15 toDate se aplica también en este listado. Antes el portal lo ignoraba acá
y lo documentábamos así: si filtrabas por fecha de tu lado para compensarlo, ya no hace falta.
La cuenta de Mapaprop (mapapropapi)
GET /property-v1/leads?portal=mapapropapi
No es un portal: son las consultas que entraron por la cuenta de Mapaprop de tu cliente — su sitio web, su chat, el portal de Mapaprop, o un portal que las deja ahí. Se lee con el mismo endpoint y la respuesta tiene la misma forma, así que no escribís una segunda lectura.
Las cuatro diferencias, y conviene tenerlas presentes:
| Un portal | mapapropapi | |
|---|---|---|
| Cupo | cada página es una llamada del cupo de la inmobiliaria | 🟢 no gasta cupo de nadie: la fuente es nuestra base |
quota | viene | no viene — mandarte un cero se leería como "no te queda nada" |
total | cuántos dice el portal que hay en la ventana | cuántos te trajimos. Contar la ventana duplicaría el costo de cada página, así que no lo inventamos: para saber si quedan más, mirá truncated |
| Defaults | size 100 · maxPages 20 | size 50 · maxPages 1 |
⚠️ Por defecto te traemos una sola página de 50. Si hay más en esa ventana la respuesta trae
truncated: true y un notices diciéndolo. Como paginar es gratis, subí maxPages con confianza —
el único límite es el tamaño de la respuesta.
Cómo identificás la propiedad en esta fuente
Con data.property.propertyId, que es el id de la propiedad en Mapaprop.
No con paId ni con code: esos dos son tuyos —el paId lo elegís vos al dar de alta por la
API— y existen sólo si esa propiedad nació por PropertyAPI. Las consultas de esta fuente llegan a
la cuenta de Mapaprop de tu cliente, y ahí la propiedad pudo haberse cargado a mano, importado de
otro sistema o venir de un portal. En esos casos nadie eligió un paId, así que viaja null:
"property": { "propertyId": 2617621, "paId": null, "code": null }
Si la propiedad sí la publicaste vos por la API, llegan los tres.
📌 Y hay consultas que no son sobre ninguna propiedad —alguien que escribe por la inmobiliaria,
no por un aviso—: ahí el bloque entero viene null. Convienen las dos ramas en tu código.
La ventana tiene tope: un año
{ "error": "window_too_wide", "detail": "La ventana no puede ser mayor a un año. Acotá `fromDate`/`toDate` y paginá.", "portal": "mapapropapi" }
Un 400. Es el único parámetro que esta fuente valida distinto que los portales.
Un pedido mal armado vuelve como 400, no como 502
{ "error": "invalid_request", "detail": "fromDate must be a date, as yyyy-MM-dd", "portal": "mapapropapi" }
El detail trae el motivo tal como lo dice la fuente, así que se lee y se arregla: reintentarlo
no cambia nada. El 502 mapaprop_unavailable queda para lo que de verdad significa —que no pudimos
hablar con Mapaprop—, y ése sí vale reintentarlo.
📌 La fecha se acepta en las dos formas: YYYYMMDD (la de la tabla de arriba) y yyyy-MM-dd.
Hoy sirve para TU cuenta, no para las de tus 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" }
Un 400, y querés saberlo antes de escribir el código: esta fuente resuelve la cuenta a partir de
tu token, así que funciona si tu token salió de una cuenta de Mapaprop. Si sos una plataforma cuyos
clientes tienen cuenta de Mapaprop, lo que te sirve hoy es
el webhook — por ahí sí te llegan las consultas de tus clientes,
sin que las tengas que pedir. Es la misma limitación que
branches, y la vamos a cerrar: escribinos a
dev@mapaprop.com si te bloquea.
Los errores
| Cuándo | Qué hacer | |
|---|---|---|
400 portal_required | 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_not_supported | 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.
Antes de armar la llamada, mirá qué modo soporta ese portal.
No todos ofrecen este servicio, y así te enterás como dato en vez de por un 501.