Receber consultas
As consultas (ou leads) são o que uma pessoa interessada num anúncio deixa. É o único fluxo da API em que a direção se inverte: em todos os outros você manda algo e nós o levamos ao portal; aqui o dado nasce fora e tem que chegar até você.
Isso muda o desenho: não se trata de em que ordem chamar, mas de quem dispara e a cada quanto tempo.
O caminho
1 · como funciona neste portal? GET …/leads/capabilities gratuito. PERGUNTA-SE PRIMEIRO
2 · conforme a resposta:
· você as pede GET …/leads (cada chamada custa)
· chegam sozinhas ← o seu endpoint + verificar a nossa assinatura
3 · você deduplica pelo id do lead
4 · você responde ao interessado pelo seu canal, não por aqui
1 · Perguntar primeiro como funciona naquele portal
…/leads/capabilities é gratuito e é o passo que a maioria
pula. Há três modos e não é você quem escolhe: quem define é o portal.
| Modo | Quem dispara | O que você precisa ter |
|---|---|---|
| você pergunta | a sua integração, quando quiser | nada: uma chamada |
| o portal avisa | o portal | um endpoint seu, e verificar a nossa assinatura |
| nós empurramos | nós | o mesmo: o seu endpoint e a assinatura |
Por que se pergunta em vez de supor: se você montar a sua integração para pedir consultas e aquele portal só as empurra, não vai receber nada — e não vai ver nenhum erro, porque pedir algo que não há devolve uma lista vazia com toda a normalidade.
⚠️ Uma lista vazia não significa "não há consultas": pode significar "neste portal elas não são
pedidas assim". São duas coisas distintas e só o capabilities as distingue.
2 · Trazê-las, se naquele portal elas são pedidas
Há dois alcances e a diferença é de custo, não de conteúdo:
| Quando | |
|---|---|
| Toda a conta | o caminho normal: uma chamada traz as de todos os anúncios daquele cliente |
| Um imóvel | quando você já sabe qual anúncio lhe interessa |
🔴 Não percorra os seus imóveis pedindo as consultas de cada um. Com 300 anúncios são 300 chamadas da cota do seu cliente para trazer o mesmo que uma traz. É o erro mais caro deste fluxo.
Se elas chegam sozinhas
Você precisa de um endpoint próprio e precisa verificar a nossa assinatura antes de confiar no conteúdo — é o que distingue um aviso nosso de qualquer um que descubra a sua URL. E convém que o seu endpoint responda rápido e guarde: processar depois é mais robusto do que processar enquanto responde.
3 · Deduplicar: não é opcional
Cada consulta traz um identificador, e ele é a sua chave de deduplicação. Guarde-o.
É necessário porque a mesma consulta pode chegar duas vezes por razões normais: você pediu um intervalo que se sobrepõe ao anterior, tentou de novo, ou o portal avisou e você também perguntou. Nenhuma dessas é um erro, e sem deduplicar elas se traduzem num contato duplicado para o seu usuário.
4 · Responder ao interessado
Pelo seu canal. Esta API traz a consulta; a conversa com a pessoa não passa por aqui.
Que cadência escolher
Se naquele portal as consultas são pedidas, a cadência é você quem decide e o seu cliente quem paga:
- Peça por conta, não por imóvel (uma chamada em vez de N).
- Escolha uma frequência que corresponda a como o dado é usado. Um lead que é olhado cada manhã não precisa ser consultado a cada cinco minutos.
- Se o portal empurra, não é preciso perguntar além disso: você estaria pagando por algo que já chegou.
O que pode vir vazio e não é um erro
- Campos do interessado em branco. O portal não exige todos os dados; uma consulta pode chegar sem telefone ou sem nome. O seu sistema tem que aceitá-la do mesmo jeito.
- Uma lista vazia. Pode ser que não haja consultas novas, ou que aquele portal não funcione assim (passo 1).
Relacionado
- Leads — os métodos e o objeto que devolvemos
- Que modo cada portal suporta — o passo 1
- Publicação — os portais e o que muda em cada um