BETA

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é traeScope
Las consultas de toda la cuentatodas las de esa inmobiliaria, de todos sus avisos{portal}:leads
Las consultas de una propiedadsólo las de ese aviso{portal}:leads
Qué modo soporta cada portalno trae consultas: te dice si en ese portal se piden o llegan solasproperty-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

CampoQué es
eventIdel identificador de este evento. Es estable: si te lo reenviamos, llega con el mismo. Es con lo que dedupeás
eventlead.created cuando nace la conversación · lead.message cuando llega un mensaje nuevo de una que ya existía
occurredAtcuándo pasó, en ISO-8601 UTC. Es la hora del origen, no la nuestra
clientRefde qué cliente tuyo es
sourcede dónde vino — ver abajo

De dónde vino

CampoQué es
source.casezonaprop, argenprop, mercadolibre, cabaprop, website, chat-ai, portal-mapaprop, network-search, network-site, feed
source.subcaseel 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.idslos ids que usa ese origen para el mismo mensaje. Te sirven para cruzar con sus reportes; no hace falta usarlos

La consulta

CampoQué es
questionIdla conversación. Dos mensajes con el mismo questionId son el mismo hilo — es lo que te permite pegarlos en vez de crear dos consultas
messageIdel mensaje dentro de esa conversación. Viaja null en un lead.created, porque ese evento es el nacimiento
directionincoming siempre que te llegue: sólo te mandamos lo que entró
messagelo que escribió el interesado
contactname, email, phone. Cualquiera puede venir null: no todos los orígenes exigen todos
customerla cuenta de Mapaprop, cuando ese cliente tiene una
propertyver abajo
rawreservado. Hoy viaja null

La propiedad, y qué significa que no venga

CampoQué es
property.propertyIdel id de la propiedad en Mapaprop
property.codeel código con el que el aviso vive en el portal
property.paIdtu id. Hoy viaja siempre null — ver abajo

🔴 Qué id te llega depende de la fuente, y la diferencia importa:

propertyIdcodepaId
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:

  1. 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.
  2. 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.

PortalEl cupoDónde está el detalle
Zonaprop1.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ásLlamadas al mesDel cupo
una vez por día~302 %
cada 6 horas~1208 %
una vez por hora~72048 %

Qué portales

PortalCó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 restotodaví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.