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 id del lead
4 · 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 verificar 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.
3 · Deduplicar: no es opcional
Cada consulta trae un identificador, y es tu clave de deduplicación. Guardalo.
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 · 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ó.
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
- Publicación — los portales y qué cambia en cada uno