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 dos métodos
| Qué trae | ||
|---|---|---|
| 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 |
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.
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.
{
"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
}
| Campo | Qué es |
|---|---|
id | el identificador del lead. Con esto lo reconocés si vuelve a aparecer |
propertyCode | el código del aviso en el portal |
name · email · phone · message | lo que dejó el interesado. Cualquiera puede venir null: el portal no exige todos |
date | la fecha, en milisegundos desde 1970 (epoch) |
portalMessageId · portalAdId · portalContactId · portalActionId | ids internos del portal. Te sirven para cruzar con sus reportes; no hace falta usarlos |
Nuestra sugerencia: reconocé un lead por el par portal + id, no por el id solo.
El id no lo generamos nosotros: es el que emite cada portal, en su propia numeración. Te lo pasamos
tal cual, sin agregarle nada. Como cada portal numera por su cuenta, dos portales distintos pueden usar el
mismo número para leads distintos — y el portal viene en la respuesta justamente para que puedas
distinguirlos.
No guardamos los leads
La API no almacena leads, en ninguna circunstancia. 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 base de datos de leads de tus clientes de nuestro lado.
Dos consecuencias prácticas, 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 el par
portal+id.
El cupo del portal
Cada consulta que hacés gasta una llamada del cupo mensual que el portal le da a esa inmobiliaria.
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) | con los dos métodos de esta sección |
| El resto | todavía no. Un pedido a un portal sin este servicio devuelve 501, diciendo cuál de los dos falta |
Cada portal decide qué ofrece: algunos permiten consultar, otros avisan por su cuenta cuando entra una consulta. A medida que incorporemos cada uno, esta tabla lo dice.
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.