BETA

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.

ModoQuem disparaO que você precisa ter
você perguntaa sua integração, quando quisernada: uma chamada
o portal avisao portalum endpoint seu, e verificar a nossa assinatura
nós empurramosnóso 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 contao caminho normal: uma chamada traz as de todos os anúncios daquele cliente
Um imóvelquando 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.eventO que é
lead.createda conversa nasceu — aqui você abre o registro
lead.messageuma 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