DEVELOPING

Leads

Quando alguém vê um anúncio do seu cliente num portal e deixa uma consulta, isso é um lead: o nome, o e-mail, o telefone e o que a pessoa escreveu.

Esta API entrega esses dados a você. Você escolhe quando pedi-los — não há nada a esperar nem horário a cumprir.

Os dois métodos

	O que traz
As consultas de toda a conta	todas as dessa imobiliária, de todos os anúncios dela	`{portal}:leads`
As consultas de um imóvel	apenas as desse anúncio	`{portal}:leads`

Comece pelo de toda a conta. Cada lead informa de qual anúncio veio, então uma única chamada traz tudo: é o caminho normal. O de um imóvel existe para quando você quer olhar apenas um — o detalhe de um anúncio no seu painel — e não faz sentido trazer o resto.

A nossa sugestão: não percorra os seus anúncios um por um. Com 500 anúncios e uma consulta por dia seriam 15.000 chamadas por mês; com o método por conta, o mesmo dá ~30. No Zonaprop, cuja cota habitual é de 1.500 chamadas por mês por imobiliária (ver a cota do Zonaprop), o primeiro não cabe e o segundo usa 2 %.

A cota é definida por cada portal, portanto o número muda dependendo do portal. O que não muda é a proporção: uma chamada por conta sempre vai custar muito menos que uma por anúncio.

O objeto lead

É o mesmo nos dois métodos.

{
  "id": "322337250",
  "propertyCode": "2605257___mapaprop",
  "name": "Lucía",
  "email": "lucia@ejemplo.com",
  "phone": "1156781234",
  "message": "Hola, quería coordinar una visita",
  "date": 1790878040000,
  "portalMessageId": null,
  "portalAdId": 56801168,
  "portalContactId": 49474924,
  "portalActionId": 10
}

Campo	O que é
`id`	o identificador do lead. Com ele você o reconhece se aparecer de novo
`propertyCode`	o código do anúncio no portal
`name` · `email` · `phone` · `message`	o que o interessado deixou. Qualquer um pode vir `null`: o portal não exige todos
`date`	a data, em milissegundos desde 1970 (epoch)
`portalMessageId` · `portalAdId` · `portalContactId` · `portalActionId`	ids internos do portal. Servem para cruzar com os relatórios dele; não é preciso usá-los

A nossa sugestão: reconheça um lead pelo par portal + id, não pelo id sozinho.

O id não é gerado por nós: é o que cada portal emite, na sua própria numeração. Nós o repassamos tal como vem, sem acrescentar nada. Como cada portal numera por conta própria, dois portais diferentes podem usar o mesmo número para leads diferentes — e o portal vem na resposta justamente para que você possa distingui-los.

Não armazenamos os leads

A API não armazena leads em nenhuma circunstância. Perguntamos ao portal, passamos a resposta a você e nada fica conosco: nem o nome, nem o e-mail, nem o telefone, nem a mensagem. Não existe um banco de dados de leads dos seus clientes do nosso lado.

Duas consequências práticas, que vale ter em mente ao desenhar a sua integração:

Armazená-los é trabalho seu. Se você não os persistir ao recebê-los, eles se perdem — não podemos buscá-los novamente num histórico nosso, porque ele não existe.
Você pode pedir o mesmo quantas vezes quiser. Não controlamos o que já entregamos, então pedir uma janela que você já pediu devolve os mesmos leads. É de propósito: se o seu sistema perder um, você pode trazê-lo de novo. Quem decide o que é novo é você, com o par portal + id.

A cota do portal

Cada consulta que você faz gasta uma chamada da cota mensal que o portal concede àquela imobiliária.

Cada portal tem a sua própria cota, as suas próprias regras e a sua própria página. Hoje o único com o serviço construído é o Zonaprop; à medida que incorporarmos outros, cada um acrescenta a sua.

Portal	A cota	Onde está o detalhe
Zonaprop	1.500 chamadas por mês por imobiliária (cota habitual)	Cota mensal e limites

A cota é compartilhada com a publicação. No Zonaprop, publicar um anúncio, consultar o status dele e trazer estas consultas consomem a mesma cota. Se você esgotá-la trazendo leads, o seu cliente não consegue publicar até o mês seguinte. O que consome e o que não, operação por operação, está em Cota mensal e limites.

Cada resposta informa como está o saldo:

"quota": { "remaining": 1346, "limit": 1500 }

Esse número é o que o portal informou naquela chamada, não um valor ao vivo. Se a imobiliária também publicar no portal fora do seu sistema, o saldo real cai sem que nenhum dos dois perceba.

Uma referência para escolher a sua frequência, com o método por conta:

De quanto em quanto tempo você consulta	Chamadas por mês	Da cota
uma vez por dia	~30	2 %
a cada 6 horas	~120	8 %
uma vez por hora	~720	48 %

Quais portais

Portal	Como as consultas são obtidas hoje
Zonaprop (`zonapropapi`)	com os dois métodos desta seção
Os demais	ainda não. Um pedido a um portal sem este serviço devolve 501, dizendo qual dos dois falta

Cada portal decide o que oferece: alguns permitem consultar, outros avisam por conta própria quando entra uma consulta. À medida que incorporarmos cada um, esta tabela vai informar.

A permissão

Os dois métodos exigem o scope {portal}:leads — por exemplo zonapropapi:leads.

Ter {portal}:publish não basta. São permissões diferentes de propósito: trazer leads é acessar dados pessoais de terceiros — as pessoas que consultaram sobre um anúncio — e isso não é concedido junto com a publicação. Se você precisar das duas coisas, os dois scopes são concedidos.