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 `eventId`
4 · você distribui o lote por destino do seu lado, sem chamadas novas
5 · 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 declará-lo para nós uma vez com
PUT …/webhooks/lead. É de lá que sai o segredo com o qual
assinamos cada entrega — ele é devolvido uma única vez, portanto guarde-o nesse momento.
Depois, verifique 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.
Se você precisa que as de um cliente específico vão para outra URL, declara-se da mesma forma, mas
com o x-client-ref dele.
3 · Deduplicar: não é opcional
Cada consulta traz um eventId, e ele é a sua chave de deduplicação. Guarde-o.
Ele vem do fato, não da tentativa: um reenvio da mesma consulta chega com o mesmo valor, então
guardá-lo é suficiente. A única exceção está medida e é do Zonaprop — ali o id da origem não é único — e
se resolve acrescentando o occurredAt à chave: o detalhe está em
o objeto lead.
É 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 · Distribuir o lote: peça por conta, separe por anúncio
Os dois passos anteriores deixam você com um lote da imobiliária inteira, e é aí que está a boa prática deste fluxo: traz-se junto e distribui-se do seu lado.
Quase toda consulta diz de qual anúncio veio, então a distribuição não precisa de nenhuma chamada a mais — é uma operação na sua base. Separe-as no momento de recebê-las e mande cada uma para onde tem que ser lida: a caixa do anúncio, a da filial, a do corretor que o captou.
🔴 E a sua distribuição precisa de uma caixa para as que não são de nenhum anúncio. 16,9 % das
consultas não são sobre um imóvel em particular — no MercadoLibre, 34 %: alguém escreve para
perguntar sobre uma região, sobre um orçamento, sobre disponibilidade em geral. Chegam com
data.property como null, são consultas igualmente válidas, e uma distribuição que só sabe rotear por
anúncio as descarta sem que nada falhe. É o defeito mais silencioso deste fluxo.
Por que a distribuição é do seu lado e não do nosso: a chamada por conta custa uma e traz tudo; pedir anúncio por anúncio para já tê-las separadas custa uma por anúncio e traz exatamente a mesma coisa. Com 300 anúncios, é a diferença entre 1 chamada e 300 da cota do seu cliente, pelo mesmo dado. O agrupamento é gratuito; as chamadas não.
⚠️ O lote traz anúncios que não são seus, e isso é normal. Vem com as consultas de todos os anúncios daquela imobiliária naquele portal, incluindo os que ela publicou por outra via. Os que não casam com nenhuma das suas propriedades não são um erro: são dela, e o correto é ignorá-los. Como casar cada consulta com a sua propriedade está em as consultas de toda a conta.
🔴 E não use a distribuição como critério de pertencimento. Uma consulta cair em uma caixa sua tem que ser consequência de tê-la casado contra a sua base — nunca de ter suposto que tudo o que chegou no lote é seu.
4-bis · Junte as mensagens da mesma thread
Uma consulta pode ter várias mensagens: a pessoa interessada escreve, e depois escreve de novo. Se você abrir um registro novo para cada mensagem, o seu usuário vê três contatos onde há uma conversa.
Quando o lead traz o data.questionId, isso é a conversa: dois leads com o mesmo valor são a mesma
thread. E o lead.event diz o que cada um é:
lead.event | O que é |
|---|---|
lead.created | a conversa nasceu — aqui você abre o registro |
lead.message | uma mensagem nova de uma que já existia — aqui você acrescenta à thread |
O questionId vem desde que a consulta tenha passado pela conta Mapaprop do seu cliente
(portal: "mapapropapi"). Um lead que vai direto do portal para o seu sistema não tem thread para
nomear e o traz como null: ali cada consulta é uma, e está certo tratá-la assim.
5 · 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
mapapropapié a exceção a tudo isso: não gasta cota de ninguém, então a cadência ali não é uma decisão de custo. O ponto acima continua valendo: se já chega a você por webhook, pedi-la além disso só gera trabalho duplicado.
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
- Webhooks — declarar para qual URL sua entregamos
- Publicação — os portais e o que muda em cada um