Leads
Cuando alguien ve un aviso de tu cliente en un portal y deja una consulta, eso es un lead: su nombre, su email, su teléfono y lo que escribió.
Esta API te los entrega. Vos elegís cuándo pedirlos — no hay nada que esperar ni un horario que cumplir.
Los métodos
| Qué trae | Scope | |
|---|---|---|
| Las consultas de toda la cuenta | todas las de esa inmobiliaria, de todos sus avisos | {portal}:leads |
| Las consultas de una propiedad | sólo las de ese aviso | {portal}:leads |
| Qué modo soporta cada portal | no trae consultas: te dice si en ese portal se piden o llegan solas | property-api-catalog |
El tercero lleva un scope distinto a propósito. Los dos primeros traen datos personales de los interesados, así que se otorgan portal por portal. El tercero no trae ninguna consulta —sólo dice cómo funciona cada portal— y habla de todos a la vez, así que usa el scope del catálogo, el mismo de las zonas y los atributos.
Empezá por el de toda la cuenta. Cada lead te dice de qué aviso vino, así que una sola llamada te trae todo: es el camino normal. El de una propiedad existe para cuando querés mirar una sola —el detalle de un aviso en tu panel— y no tiene sentido traerte el resto.
Y hay una fuente que no es un portal: mapapropapi. Son las consultas que llegan a la cuenta de
Mapaprop de tu cliente — por su sitio web, por su chat, o por un portal que las deja ahí. Se piden
igual (?portal=mapapropapi) y tienen una ventaja: no gastan cupo de ningún portal, porque no hay
portal de por medio. Podés paginar sin contar llamadas.
Lo que sí tiene es un límite de ventana: un año hacia atrás por consulta.
Nuestra sugerencia: no recorras tus avisos uno por uno. Con 500 avisos y una consulta por día serían 15.000 llamadas al mes; con el método por cuenta, lo mismo son ~30. En Zonaprop, cuyo cupo habitual es de 1.500 llamadas por mes por inmobiliaria (ver el cupo de Zonaprop), lo primero no entra y lo segundo usa el 2 %.
El cupo lo fija cada portal, así que el número cambia según el portal. Lo que no cambia es la proporción: una llamada por cuenta siempre va a costar mucho menos que una por aviso.
El objeto lead
Es el mismo en los dos métodos, y el mismo que te llega por webhook. Una sola forma para leer, sin importar de dónde vino la consulta ni por qué puerta la recibís.
{
"eventId": "evt_1622087_c",
"event": "lead.created",
"occurredAt": "2026-11-15T03:07:08Z",
"clientRef": "cliente-42",
"source": {
"source": "mapaprop",
"case": "zonaprop",
"subcase": "api",
"ids": {
"messageId": "322337250",
"adId": "56801168",
"contactId": "49474924",
"actionId": "10"
}
},
"data": {
"questionId": "1622087",
"messageId": null,
"direction": "incoming",
"message": "Hola, quería coordinar una visita",
"contact": { "name": "Lucía", "email": "lucia@ejemplo.com", "phone": "1156781234" },
"customer": { "customerId": 441 },
"property": { "propertyId": 2610019, "paId": null, "code": null },
"raw": null
}
}
El sobre
| Campo | Qué es |
|---|---|
eventId | el identificador de este evento. Es estable: si te lo reenviamos, llega con el mismo. Es con lo que dedupeás |
event | lead.created cuando nace la conversación · lead.message cuando llega un mensaje nuevo de una que ya existía |
occurredAt | cuándo pasó, en ISO-8601 UTC. Es la hora del origen, no la nuestra |
clientRef | de qué cliente tuyo es |
source | de dónde vino — ver abajo |
De dónde vino
| Campo | Qué es |
|---|---|
source.case | zonaprop, argenprop, mercadolibre, cabaprop, website, chat-ai, portal-mapaprop, network-search, network-site, feed |
source.subcase | el canal dentro de ese caso cuando hay más de uno (api o xml en Zonaprop y Argenprop). null si el caso tiene uno solo |
source.ids | los ids que usa ese origen para el mismo mensaje. Te sirven para cruzar con sus reportes; no hace falta usarlos |
La consulta
| Campo | Qué es |
|---|---|
questionId | la conversación. Dos mensajes con el mismo questionId son el mismo hilo — es lo que te permite pegarlos en vez de crear dos consultas |
messageId | el mensaje dentro de esa conversación. Viaja null en un lead.created, porque ese evento es el nacimiento |
direction | incoming siempre que te llegue: sólo te mandamos lo que entró |
message | lo que escribió el interesado |
contact | name, email, phone. Cualquiera puede venir null: no todos los orígenes exigen todos |
customer | la cuenta de Mapaprop, cuando ese cliente tiene una |
property | ver abajo |
raw | reservado. Hoy viaja null |
La propiedad, y qué significa que no venga
| Campo | Qué es |
|---|---|
property.propertyId | el id de la propiedad en Mapaprop |
property.code | el código con el que el aviso vive en el portal |
property.paId | tu id. Hoy viaja siempre null — ver abajo |
🔴 Qué id te llega depende de la fuente, y la diferencia importa:
propertyId | code | paId | |
|---|---|---|---|
Un portal (zonapropapi) | — | ✅ el código del aviso | — |
La cuenta de Mapaprop (mapapropapi) | ✅ | — | — |
⇒ No escribas tu machero contra un solo campo. Por portal cruzás por code
(cómo leerlo); por la cuenta de Mapaprop, por propertyId,
que es el mismo id que te devuelve el GET de la propiedad.
paId está en el contrato y hoy no se completa en ninguna de las dos: lo vas a ver llegar sin que
tengas que cambiar nada, y mientras tanto no te sirve para cruzar.
property: null significa que no preguntó por ninguna, no que no la pudimos resolver. Pasa
seguido: 16,9 % de las consultas no son sobre un aviso en particular, y en MercadoLibre son el
34 %. Son consultas igual de válidas — alguien que escribe para preguntar por la zona, por
ejemplo — y hay que poder recibirlas.
Para reconocer un lead: usá eventId
El eventId sale del hecho, no del intento. Si un reenvío te trae la misma consulta dos veces,
las dos llegan con el mismo eventId — así que guardándolo te alcanza para no duplicar.
La excepción: los leads que no pasan por una cuenta de Mapaprop. Ahí no hay una conversación
nuestra que nombrar, así que el eventId se arma con el id que manda el origen y llega con el prefijo
evt_src_. Y para Zonaprop ese id, medido, no es único: un mismo interesado escribiendo dos veces
sobre el mismo aviso en días distintos llega con el mismo número y distinto occurredAt.
⇒ Si recibís leads de esa clase, sumale occurredAt a la clave. Lo reconocés porque el eventId
empieza con evt_src_ y el questionId viene null.
Esta forma reemplazó a la anterior el 20 de noviembre de 2026. La de antes era plana (id,
propertyCode, name…). El detalle del cambio y la equivalencia campo por campo están en
Cambios de la API.
Qué queda guardado y qué no
La API no se queda con los leads de los portales. Le preguntamos al portal, te pasamos la respuesta y no nos queda nada: ni el nombre, ni el email, ni el teléfono, ni el mensaje. No hay una base de leads de portal de nuestro lado.
La fuente mapapropapi es distinta, y la diferencia es de origen. Esas consultas nacieron en
la cuenta de Mapaprop de tu cliente —por su sitio, su chat o el portal de Mapaprop—, así que viven en
su bandeja de entrada porque es ahí donde entraron: no las guardamos por traértelas. Son datos de tu
cliente, en su propia cuenta, y los sigue viendo y respondiendo desde Mapaprop.
⇒ La consecuencia práctica es buena: esas sí las podés volver a pedir siempre, hasta un año atrás.
Dos consecuencias prácticas de lo anterior, y conviene tenerlas presentes al diseñar tu integración:
- Guardarlos es tu trabajo. Si no los persistís cuando los recibís, se pierden — nosotros no los podemos volver a buscar en un historial nuestro, porque no existe.
- Podés volver a pedir lo mismo cuantas veces quieras. No llevamos la cuenta de qué te entregamos ya, así que pedir una ventana que ya pediste te devuelve los mismos leads. Es a propósito: si tu sistema pierde uno, lo podés volver a traer. Quien decide qué es nuevo sos vos, con la clave de arriba.
El cupo del portal
Cada consulta a un portal gasta una llamada del cupo mensual que ese portal le da a la inmobiliaria.
🟢 mapapropapi no gasta cupo de nadie — no hay portal de por medio, así que ahí podés paginar sin
contar llamadas y esta sección no te aplica.
Cada portal tiene su propio cupo, sus propias reglas y su propia página. Hoy el único con el servicio construido es Zonaprop; a medida que incorporemos otros, cada uno suma la suya.
| Portal | El cupo | Dónde está el detalle |
|---|---|---|
| Zonaprop | 1.500 llamadas por mes por inmobiliaria (cupo habitual) | Cupo mensual y límites |
El cupo se comparte con publicar. En Zonaprop, publicar un aviso, consultar su estado y traer estas consultas consumen por igual el mismo cupo. Si lo agotás trayendo leads, tu cliente no puede publicar hasta el mes siguiente. Qué consume y qué no, operación por operación, está en Cupo mensual y límites.
Cada respuesta te dice cómo viene el saldo:
"quota": { "remaining": 1346, "limit": 1500 }
Ese número es el que el portal informó en esa llamada, no un valor en vivo. Si la inmobiliaria además publica en el portal por fuera de tu sistema, el saldo real baja sin que ninguno de los dos se entere.
Una referencia para elegir tu frecuencia, con el método por cuenta:
| Cada cuánto consultás | Llamadas al mes | Del cupo |
|---|---|---|
| una vez por día | ~30 | 2 % |
| cada 6 horas | ~120 | 8 % |
| una vez por hora | ~720 | 48 % |
Qué portales
| Portal | Cómo se obtienen hoy |
|---|---|
Zonaprop (zonapropapi) | vas a buscarlas, con los dos métodos de esta sección |
Argenprop (argenpropapi) | te llegan, a la URL que declarás en Webhooks. No tiene los métodos de esta sección: un pedido acá devuelve 501 |
La cuenta de Mapaprop (mapapropapi) | las dos: vas a buscarlas con el método por cuenta, y además te llegan por webhook |
| El resto | todavía no, de ninguna de las dos formas |
No son dos niveles de lo mismo: son dos mecanismos distintos, y un portal puede tener uno y no el
otro. Si vas a buscar las consultas de un portal que sólo empuja, el 501 te dice cuál de los dos
servicios falta — pero preguntarlo no cuesta nada y es mejor que descubrirlo así:
Capacidades lo contesta para todos los portales de una, y es
el mismo dato que usa nuestro código.
El permiso
Los dos métodos piden el scope {portal}:leads — por ejemplo zonapropapi:leads.
Tener {portal}:publish no alcanza. Son permisos distintos a propósito: traer leads es acceder a
datos personales de terceros —la gente que consultó por un aviso—, y eso no se concede junto con
publicar. Si necesitás las dos cosas, se te otorgan los dos scopes.