DEVELOPING

As consultas de um imóvel

GET /property-v1/properties/{paId}/leads?portal={portal}

Traz as consultas de um anúncio, o do imóvel que você indicar.

Para trazer tudo, use o método por conta. Percorrer os seus imóveis um por um gasta uma chamada da cota para cada um, e com o outro método vêm todas numa só. Este método é para quando você quer olhar apenas um — o detalhe de um anúncio no seu painel.

curl "https://property-api.mapaprop.com/property-v1/properties/01M41AQNXYG4W4SEEEEPHEDNX4/leads?portal=zonapropapi&fromDate=20260101" \
  -H "Authorization: Bearer $TOKEN" \
  -H "x-client-ref: cliente-42"

Os parâmetros


`portal`	obrigatório	`zonapropapi`
`fromDate`	a partir de qual data, `YYYYMMDD`	se você não enviar, os últimos 7 dias
`toDate`	até qual data, `YYYYMMDD`	aqui é aplicado
`size`	quantos leads no máximo	100

Envie o fromDate sempre que quiser mais do que o muito recente. Sem uma janela explícita o portal usa uma própria, bem estreita: o mesmo anúncio que devolve 8 consultas com fromDate de nove meses atrás devolve 1 sem o parâmetro. Se você não enviar, parece que o anúncio quase não teve consultas.

A resposta

{
  "portal": "zonaprop",
  "paId": "2605257",
  "from": "20260101",
  "to": "20260601",
  "leads": [
    {
      "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
    }
  ],
  "total": 8,
  "quota": { "remaining": 1346, "limit": 1500 }
}

É a mesma forma do método por conta, mais o paId que você pediu. O objeto lead, campo por campo, está na introdução.

O to aparece apenas se você enviou o toDate — e aparece porque aqui o filtro foi aplicado.

Se o anúncio não está no portal

Não é um erro: é 200, com a lista vazia e o motivo.

{
  "portal": "zonaprop",
  "paId": "01M41AQNXYG4W4SEEEEPHEDNX4",
  "from": "20260929",
  "leads": [],
  "total": 0,
  "notPublishedOnPortal": true,
  "detail": "Ese aviso no figura en esa inmobiliaria del portal, así que no tiene consultas. Puede que todavía no se haya publicado, que el portal lo haya dado de baja, o que esté publicado bajo otra cuenta.",
  "quota": { "remaining": 1346, "limit": 1500 }
}

O portal nos diz "esse anúncio não consta nesta imobiliária" e nada mais, então não podemos dizer a você qual das três razões é. Preferimos nomear as três a escolher uma e arriscar mandar você procurar onde não está.

O imóvel existe no seu inventário — se não existisse, a resposta seria um 404.

Os erros

	Quando	O que fazer
400 `portal_requerido`	falta o `?portal=`	envie-o
403	falta a você o scope `{portal}:leads`	peça para concedermos
404 `property_not_found`	aquele `paId` não está no seu inventário	verifique o id. Não gasta cota: paramos antes de perguntar ao portal
409 `portal_not_connected`	aquela conta não está conectada àquele portal	conecte-a
409 `portal_account_unlinked`	foi desvinculada do lado do portal	é preciso conectá-la de novo
429 `portal_quota_exhausted`	a imobiliária esgotou a cota do mês	aguardar o mês seguinte. A cota é compartilhada com a publicação — ver a cota do Zonaprop
501 `leads_no_soportado`	aquele portal ainda não oferece este serviço	—
502 `portal_rejected`	o portal não respondeu ou rejeitou a consulta	tentar de novo é seguro