Recibir consultas
Las consultas (o leads) son lo que deja una persona interesada en un aviso. Es el único flujo de la API donde la dirección se invierte: en todos los demás vos mandás algo y nosotros lo llevamos al portal; acá el dato nace afuera y tiene que llegarte.
Eso cambia el diseño: no se trata de en qué orden llamar, sino de quién dispara y cada cuánto.
El camino
1 · ¿cómo funciona en este portal? GET …/leads/capabilities gratis. SE PREGUNTA PRIMERO
2 · según la respuesta:
· lo pedís vos GET …/leads (cada llamada cuesta)
· te llega solo ← tu endpoint + verificar nuestra firma
3 · deduplicás por el `eventId`
4 · repartís el lote a cada destino de tu lado, sin llamadas nuevas
5 · le respondés al interesado por tu canal, no por acá
1 · Preguntar primero cómo funciona en ese portal
…/leads/capabilities es gratis y es el paso que la mayoría
se saltea. Hay tres modos y no los elegís vos: los define el portal.
| Modo | Quién dispara | Qué tenés que tener |
|---|---|---|
| vos preguntás | tu integración, cuando quieras | nada: una llamada |
| el portal avisa | el portal | un endpoint tuyo, y verificar nuestra firma |
| nosotros te empujamos | nosotros | lo mismo: tu endpoint y la firma |
Por qué se pregunta en vez de asumir: si armás tu integración para pedir consultas y ese portal sólo las empuja, no vas a recibir nada — y no vas a ver ningún error, porque pedir algo que no hay devuelve una lista vacía con toda normalidad.
⚠️ Una lista vacía no significa "no hay consultas": puede significar "en este portal no se piden
así". Son dos cosas distintas y sólo capabilities las distingue.
2 · Traerlas, si en ese portal se piden
Hay dos alcances y la diferencia es de costo, no de contenido:
| Cuándo | |
|---|---|
| Toda la cuenta | el camino normal: una llamada te trae las de todos los avisos de ese cliente |
| Una propiedad | cuando ya sabés qué aviso te interesa |
🔴 No recorras tus propiedades pidiendo las consultas de cada una. Con 300 avisos son 300 llamadas del cupo de tu cliente para traer lo mismo que trae una. Es el error más caro de este flujo.
Si te llegan solas
Necesitás un endpoint propio, y declarárnoslo una vez con
PUT …/webhooks/lead. De ahí sale el secreto con el que firmamos
cada entrega — se devuelve una sola vez, así que guardalo en ese momento.
Después, verificá nuestra firma antes de confiar en el contenido: es lo que distingue un aviso nuestro de cualquiera que descubra tu URL. Y conviene que tu endpoint conteste rápido y guarde: procesar después es más robusto que procesar mientras contestás.
Si necesitás que las de un cliente puntual vayan a otra URL, se declara igual pero con su
x-client-ref.
3 · Deduplicar: no es opcional
Cada consulta trae un eventId, y es tu clave de deduplicación. Guardalo.
Sale del hecho, no del intento: un reenvío de la misma consulta llega con el mismo valor, así que
guardarlo alcanza. La única excepción está medida y es de Zonaprop —ahí el id del origen no es único—,
y se resuelve sumando occurredAt a la clave: el detalle está en
el objeto lead.
Hace falta porque la misma consulta puede llegarte dos veces por razones normales: pediste un rango que se solapa con el anterior, reintentaste, o el portal avisó y vos además preguntaste. Ninguna de esas es un error, y sin deduplicar se traducen en un contacto duplicado para tu usuario.
4 · Repartir el lote: pedí por cuenta, separá por aviso
Los dos pasos anteriores te dejan un lote de la inmobiliaria entera, y ahí está la buena práctica de este flujo: se trae junto y se reparte de tu lado.
Casi cada consulta te dice de qué aviso vino, así que el reparto no necesita ninguna llamada más — es una operación en tu base. Separalas en el momento de recibirlas y mandá cada una a donde tenga que leerse: la bandeja del aviso, la de la sucursal, la del asesor que lo captó.
🔴 Y tu reparto necesita una bandeja para las que no son de ningún aviso. El 16,9 % de las
consultas no es sobre una propiedad en particular —en MercadoLibre, el 34 %—: alguien escribe para
preguntar por una zona, por un presupuesto, por disponibilidad en general. Llegan con
data.property en null, son consultas igual de válidas, y un reparto que sólo sabe enrutar por aviso
las descarta sin que nada falle. Es el defecto más silencioso de este flujo.
Por qué el reparto va de tu lado y no del nuestro: la llamada por cuenta cuesta una y trae todo; pedir aviso por aviso para tenerlas ya separadas cuesta una por aviso y trae exactamente lo mismo. Con 300 avisos, es la diferencia entre 1 llamada y 300 del cupo de tu cliente, por el mismo dato. El agrupamiento es gratis; las llamadas no.
⚠️ El lote trae avisos que no son tuyos, y es normal. Viene con las consultas de todos los avisos de esa inmobiliaria en ese portal, incluidos los que ella publicó por otra vía. Los que no machean con ninguna de tus propiedades no son un error: son suyos, y lo correcto es ignorarlos. Cómo machear cada consulta con tu propiedad está en las consultas de toda la cuenta.
🔴 Y no uses el reparto como criterio de pertenencia. Que una consulta caiga en una bandeja tuya tiene que ser consecuencia de haberla macheado contra tu base — nunca de haber supuesto que todo lo que llegó en el lote es tuyo.
4-bis · Pegá los mensajes del mismo hilo
Una consulta puede tener varios mensajes: el interesado escribe, y después vuelve a escribir. Si abrís una ficha nueva por cada mensaje, tu usuario ve tres contactos donde hay una conversación.
Cuando el lead trae data.questionId, eso es la conversación: dos leads con el mismo valor son el
mismo hilo. Y el lead.event te dice qué es cada uno:
lead.event | Qué es |
|---|---|
lead.created | nació la conversación — acá abrís la ficha |
lead.message | un mensaje nuevo de una que ya existía — acá agregás al hilo |
questionId viene cuando la consulta pasó por la cuenta de Mapaprop de tu cliente
(portal: "mapapropapi"). Un lead que va derecho del portal a tu sistema no tiene hilo que
nombrar y lo trae en null: ahí cada consulta es una, y está bien tratarla así.
5 · Responderle al interesado
Por tu canal. Esta API te trae la consulta; la conversación con la persona no pasa por acá.
Qué cadencia elegir
Si en ese portal las consultas se piden, la cadencia la decidís vos y la paga tu cliente:
- Pedí por cuenta, no por propiedad (una llamada en vez de N).
- Elegí una frecuencia que se corresponda con cómo se usa el dato. Un lead que se mira cada mañana no necesita consultarse cada cinco minutos.
- Si el portal empuja, no hace falta preguntar además: estarías pagando por algo que ya te llegó.
- 🟢
mapapropapies la excepción a todo esto: no gasta cupo de nadie, así que la cadencia ahí no es una decisión de costo. Igual aplica lo de arriba: si ya te llega por webhook, pedirla además sólo te da trabajo duplicado.
Lo que puede venir vacío y no es un error
- Campos del interesado en blanco. El portal no exige todos los datos; una consulta puede venir sin teléfono o sin nombre. Tu sistema tiene que aceptarla igual.
- Una lista vacía. Puede ser que no haya consultas nuevas, o que ese portal no funcione así (paso 1).
Relacionado
- Leads — los métodos y el objeto que te devolvemos
- Qué modo soporta cada portal — el paso 1
- Webhooks — declarar a qué URL tuya te entregamos
- Publicación — los portales y qué cambia en cada uno