BETA

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

portalobrigatóriozonapropapi
fromDatea partir de qual data. YYYYMMDD, ou opcionalmente YYYYMMDD HH:mm:ssse você não enviar, os últimos 7 dias
toDateaté qual data, mesmo formatosem limite
sizequantos leads por página100
maxPagesquantas páginas buscamos no máximo20

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": [
    {
      "eventId": "evt_src_322337250",
      "event": "lead.created",
      "occurredAt": "2026-11-15T03:07:08Z",
      "clientRef": "cliente-42",
      "source": {
        "source": "mapaprop",
        "case": "zonaprop",
        "subcase": "api",
        "ids": { "messageId": null, "adId": "56801168", "contactId": "49474924", "actionId": "10" }
      },
      "data": {
        "questionId": null,
        "messageId": "322337250",
        "direction": "incoming",
        "message": "Hola, quería coordinar una visita",
        "contact": { "name": "Lucía", "email": "lucia@ejemplo.com", "phone": "1156781234" },
        "customer": null,
        "property": { "propertyId": null, "paId": null, "code": "2605257___mapaprop" },
        "raw": null
      }
    }
  ],
  "total": 8,
  "quota": { "remaining": 1346, "limit": 1500 }
}

É a mesma forma do método por conta, mais o paId que você pediu.

Este método não existe para mapapropapi. Essa fonte é pedida apenas por conta, porque nem toda consulta que entra em uma conta Mapaprop é sobre um anúncio — 16,9 % não são — e pedi-las por imóvel deixaria de fora justamente as que não podem ser pedidas de outra forma. Capacidades diz isso com byProperty: false.

O objeto lead, campo por campo, está na introdução.

O to aparece apenas se você enviou o toDate, e traz o valor que foi realmente aplicado.

Um toDate sem hora é o final daquele dia. Se você enviar 20261013, tomamos como 20261013 23:59:59 para que o dia 13 entre, e informamos isso em warnings. O portal lê uma data sem hora como 00:00:00, então um puro teria deixado o dia inteiro de fora. Se você quiser outro corte, envie a hora (20261013 18:00:00) e respeitamos tal como está.

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

QuandoO que fazer
400 portal_requiredfalta o ?portal=envie-o
403falta a você o scope {portal}:leadspeça para concedermos
404 property_not_foundaquele paId não está no seu inventárioverifique o id. Não gasta cota: paramos antes de perguntar ao portal
409 portal_not_connectedaquela conta não está conectada àquele portalconecte-a
409 portal_account_unlinkedfoi desvinculada do lado do portalé preciso conectá-la de novo
429 portal_quota_exhausteda imobiliária esgotou a cota do mêsaguardar o mês seguinte. A cota é compartilhada com a publicação — ver a cota do Zonaprop
501 leads_not_supportedaquele portal ainda não oferece este serviço—
502 portal_rejectedo portal não respondeu ou rejeitou a consultatentar de novo é seguro

Antes de montar a chamada, veja qual modo esse portal suporta. Não todos oferecem este serviço, e assim você descobre como dado em vez de por um 501.