Prepare-se para o primeiro lead
Quando o seu cliente acrescenta a permissão de consultas à conta Mapaprop dele, as consultas que entram na caixa dele começam a chegar até você. Não há mais nada para ativar, nenhuma migração para rodar e nenhum botão para apertar: de um momento para o outro elas simplesmente começam a aparecer.
Esta página é o que vale a pena ter pronto antes desse momento.
Esta é a fonte mapapropapi, a que não é um portal: são as consultas que entram pelo site do
seu cliente, pelo chat dele, pelo portal da Mapaprop, ou por um portal que as deixa na caixa dele.
Os leads de portal continuam funcionando exatamente como antes.
O que acontece exatamente quando é ligado
hoje nada desta fonte chega até você
↓ a permissão é acrescentada à conta do seu cliente
a partir daí cada consulta nova chega pelo seu webhook, em segundos
Três coisas que vale saber sobre esse corte:
| Começa pelo que é novo | não reenviamos o histórico. A primeira que chega é a primeira que entra depois da permissão |
| Nada de antes se perde | está na conta do seu cliente, e você pode pedi-la por conta até um ano para trás |
| O seu cliente continua vendo tudo | as consultas não mudam de lugar: continuam na caixa de entrada dele na Mapaprop, e ele continua respondendo de lá |
As cinco coisas que precisam estar prontas antes
1 · O webhook registrado, e o segredo guardado
É declarado uma única vez com PUT …/webhooks/lead. É de lá que sai
o segredo com o qual assinamos cada entrega.
O segredo é devolvido UMA só vez. Guarde-o nesse momento: não conseguimos mostrá-lo de novo, e sem ele você não pode verificar que as entregas são nossas.
2 · Um endpoint que responda rápido e guarde
Guarde o envelope cru e responda 2xx; processe depois. Um endpoint que valida, enriquece e
escreve em três sistemas antes de responder é um endpoint que cai com mais frequência do que o que só
guarda — e você tem três tentativas, com cerca de 2 minutos entre uma e outra.
🟢 E aqui há uma rede que os leads de portal não têm: se o seu endpoint ficou fora do ar, as consultas desta fonte continuam existindo e você pode pedi-las de novo por conta. Você não depende só da entrega.
3 · Deduplique pelo eventId
É a chave, e vem do fato, não da tentativa: se reenviarmos a mesma consulta, ela chega com o mesmo
eventId. Guarde-o e pronto.
4 · Aceitar uma consulta sem imóvel
🔴 16,9 % das consultas não são sobre nenhum anúncio. Alguém escreve para perguntar sobre uma
região, sobre um orçamento, sobre disponibilidade em geral. Chegam com data.property como null.
Se o seu sistema só sabe guardar uma consulta pendurada em um imóvel, essas se perdem sem que nada falhe. É o mais caro de descobrir tarde. Você precisa de uma caixa para as que não são de nenhum anúncio.
5 · Juntar as mensagens da mesma thread
Uma consulta pode ter várias mensagens. Dois leads com o mesmo data.questionId são a mesma
conversa, e o lead.event diz o que cada um é:
lead.event | O que fazer |
|---|---|
lead.created | abrir o registro: a conversa nasceu |
lead.message | acrescentar à thread que já existe, não abrir outra |
Sem isso, o seu usuário vê três contatos onde há uma só pessoa escrevendo três vezes.
Dia 1: o que olhar
- Chegou alguma coisa? Peça as consultas da conta com
?portal=mapapropapi. É gratuito: esta fonte não gasta cota de nenhum portal. - Chegou pelo webhook e também está no
GET? Tem que ser o mesmoeventId. Se for, a cadeia está completa. - O
GETtraz consultas e o webhook não trouxe nenhuma? Então o problema está na entrega, não na origem: verifique se o seu endpoint responde2xxe se a URL registrada é a que você acha que é.
Antes de escrever para nós, essa ordem economiza metade dos casos: o GET diz se a consulta
existe do nosso lado. Separa "não entrou" de "não conseguimos entregar", que são dois problemas
diferentes com duas soluções diferentes.
Se algo não sair
Quando algo não sai tem o percurso completo. O que vale repetir aqui:
O suporte sobe pela cadeia: o seu cliente escreve para você, e você escreve para nós. Envie-nos
o reference do erro e o clientRef: com isso encontramos a sua chamada exata.
O que NÃO muda
- O seu cliente continua trabalhando igual. As consultas continuam chegando na caixa de entrada dele na Mapaprop e ele responde de lá. Isso não muda a tela dele nem tira nada do lugar.
- Os leads de portal continuam como estavam. Esta fonte se soma; não substitui nada.
- O que o seu cliente contrata com cada portal —a conta, o plano— é dele e direto, como sempre.
Veja também
- O objeto lead — o formato, campo por campo
- As consultas de toda a conta — incluindo a fonte
mapapropapi - Webhooks — declarar para onde entregamos
- Receber consultas — o fluxo completo
- Mudanças da API — o formato do lead mudou em 20 de novembro de 2026