BETA

As consultas de toda a conta

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

Traz as consultas de todos os anúncios daquela imobiliária naquele portal, numa única chamada. Cada lead informa de qual anúncio veio em data.property, então você não precisa perguntar anúncio por anúncio.

Como ler o data.property.code. É o código com que o anúncio existe no portal e, para os anúncios que você publicou, nós o montamos com o seu próprio paId mais um sufixo de marca: 01M416ACSSG7TXX172PDXSQFXF___mapaprop é a sua propriedade 01M416ACSSG7TXX172PDXSQFXF. Para casá-lo com a sua base, remova o sufixo ___mapaprop — não corte no primeiro _, porque o seu paId é o que você escolheu e pode conter qualquer coisa.

⚠️ O sufixo NÃO basta para saber se o anúncio é seu. O método por conta traz as consultas de todos os anúncios daquela imobiliária, e o sufixo ___mapaprop é levado por todos os que foram publicados pelo Mapaprop — não só pelos seus. A imobiliária pode ter publicado anúncios por outro caminho, e esses códigos levam o mesmo sufixo com um id que não é seu.

⇒ Case contra a sua própria base, não contra o sufixo: remova o sufixo e procure o resultado nas suas propriedades. Se não estiver, esse lead é de um anúncio que a imobiliária publicou por outra via — não é um erro, e o correto é ignorá-lo.

É o método que convém usar. Veja por quê na introdução.

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

Os parâmetros

portalobrigatóriozonapropapi · mapapropapi (a fonte Mapaprop)
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
maxPagesquantas páginas buscamos no máximo20
sizequantos leads você quer no máximo100, que é o teto do portal

O padrão de 7 dias é o de uma chamada sem parâmetros, para que um pedido sem data não tente trazer o histórico completo. Não é uma recomendação de frequência: a frequência você escolhe.

A resposta

{
  "portal": "zonaprop",
  "from": "20260101",
  "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": "01M416ACSSG7TXX172PDXSQFXF___mapaprop" },
        "raw": null
      }
    }
  ],
  "total": 12,
  "quota": { "remaining": 1346, "limit": 1500 }
}

Nesta fonte nenhum dos dois ids do portal identifica uma mensagem, e isso está medido sobre uma conta inteira (33 mensagens de agosto): o source.ids.messageId chegou nulo em 23, e o data.messageId —que nunca vem nulo e por isso é o que usamos para montar o eventId— teve 31 valores distintos para 33 mensagens, com dois pares genuinamente diferentes compartilhando um.

⇒ Deduplique com eventId + occurredAt. Os dois pares que compartilhavam o id estavam a cinco dias um do outro, então a data os separa; se algum dia chegarem dois com as duas coisas iguais, compare o conteúdo antes de descartar.

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

CampoO que é
froma janela que foi efetivamente usada (a sua, ou o padrão)
too limite superior da janela que foi efetivamente aplicado. Aparece apenas se você enviar toDate
leadsos leads. Pode vir vazio: significa que não houve consultas naquela janela
totalquantos o portal diz que existem naquela janela. Pode ser maior que leads.length — veja abaixo
quotao saldo que o portal informou nesta chamada

As páginas, e o que cada uma custa

Os leads vêm do mais novo para o mais antigo. Se na sua janela houver mais do que cabe em uma página, percorremos as páginas por você até maxPages.

Cada página é uma chamada da cota mensal do seu cliente. A cota é da imobiliária e é compartilhada com a publicação, então size e maxPages são decisões de custo, não apenas de conveniência. No Zonaprop o máximo por página são 100, então maxPages: 20 significa até 2.000 leads e até 20 chamadas.

Se chegarmos ao teto antes de trazer tudo, a resposta informa isso:

{
  "portal": "zonaprop",
  "from": "20240101",
  "leads": [ "… os que couberam …" ],
  "total": 900,
  "truncated": true,
  "truncatedReason": "partial_portal_cap",
  "detail": "Te devolvemos una parte, los más nuevos primero. Pedí el resto subiendo `maxPaginas` o acotando la ventana con `fromDate`/`toDate` — cada página es una llamada del cupo de la inmobiliaria.",
  "pagesFetched": 20,
  "quota": { "remaining": 1348, "limit": 1500 }
}

Na prática: se você consultar com frequência — uma vez por dia, digamos — tudo cabe em uma página e você nunca vai perder um lead. O teto só aparece quando você pede uma janela muito longa, por exemplo na primeira sincronização.

Se você paginar por conta própria em vez de usar maxPages, vai receber repetidos. A paginação do Zonaprop sobrepõe a borda: a página seguinte repete o último lead da anterior. Nós descartamos e informamos em warnings quando acontece.

toDate: sem hora, é o final daquele dia

?fromDate=20261001&toDate=20261013

Se você enviar toDate sem hora, tomamos como 20261013 23:59:59 — ou seja, o dia 13 entra. O campo to da resposta devolve o valor que foi realmente aplicado, e informamos isso:

{
  "from": "20261001",
  "to": "20261013 23:59:59",
  "warnings": [
    "Tomamos `toDate` como el final de ese día (`20261013 23:59:59`). Sin la hora, el portal lo lee como las 00:00:00 y habría excluido el día entero. Mandá la hora si querés otro corte."
  ]
}

O portal lê uma data sem hora como 00:00:00, então um toDate=20261013 puro teria deixado de fora o dia 13 inteiro sem que nada dissesse. Se você quiser outro corte, envie a hora (20261013 18:00:00) e respeitamos tal como está.

Desde 2026-10-15 o toDate também é aplicado nesta listagem. Antes o portal o ignorava aqui e nós documentávamos assim: se você filtrava por data do seu lado para compensar, já não é necessário.

A conta Mapaprop (mapapropapi)

GET /property-v1/leads?portal=mapapropapi

Não é um portal: são as consultas que entraram pela conta Mapaprop do seu cliente — o site dele, o chat dele, o portal da Mapaprop, ou um portal que as deixa lá. É lido com o mesmo endpoint e a resposta tem o mesmo formato, então você não escreve uma segunda leitura.

As quatro diferenças, e vale tê-las em mente:

Um portalmapapropapi
Cotacada página é uma chamada da cota da imobiliária🟢 não gasta cota de ninguém: a fonte é o nosso próprio banco de dados
quotavemnão vem — enviar um zero a você seria lido como "não resta nada"
totalquantos o portal diz que há na janelaquantos trouxemos a você. Contar a janela dobraria o custo de cada página, então não inventamos: para saber se restam mais, olhe o truncated
Padrõessize 100 · maxPages 20size 50 · maxPages 1

⚠️ Por padrão trazemos uma única página de 50. Se houver mais naquela janela, a resposta traz truncated: true e um notices informando. Como paginar é gratuito, aumente o maxPages com confiança — o único limite é o tamanho da resposta.

Como você identifica o imóvel nesta fonte

Com data.property.propertyId, que é o id do imóvel no Mapaprop.

Não com paId nem com code: esses dois são seus — o paId é você que escolhe ao cadastrar pela API — e só existem se aquele imóvel nasceu pelo PropertyAPI. As consultas desta fonte chegam à conta do Mapaprop do seu cliente, e lá o imóvel pode ter sido cadastrado à mão, importado de outro sistema ou vindo de um portal. Nesses casos ninguém escolheu um paId, então ele viaja como null:

"property": { "propertyId": 2617621, "paId": null, "code": null }

Se o imóvel foi você que publicou pela API, chegam os três.

📌 E há consultas que não são sobre nenhum imóvel — alguém que escreve para a imobiliária, não sobre um anúncio: aí o bloco inteiro vem como null. Vale ter os dois caminhos no seu código.

A janela tem um teto: um ano

{ "error": "window_too_wide", "detail": "La ventana no puede ser mayor a un año. Acotá `fromDate`/`toDate` y paginá.", "portal": "mapapropapi" }

Um 400. É o único parâmetro que esta fonte valida de forma diferente dos portais.

Um pedido mal formado volta como 400, não como 502

{ "error": "invalid_request", "detail": "fromDate must be a date, as yyyy-MM-dd", "portal": "mapapropapi" }

O detail traz o motivo tal como a fonte o diz, então dá para ler e corrigir: repetir não muda nada. O 502 mapaprop_unavailable fica para o que realmente significa — que não conseguimos falar com o Mapaprop — e esse sim vale a pena repetir.

📌 A data é aceita nas duas formas: YYYYMMDD (a da tabela acima) e yyyy-MM-dd.

Hoje serve para a SUA conta, não para as dos seus clientes

{ "error": "no_mapaprop_account", "detail": "Los leads de esta fuente son de una cuenta de Mapaprop, y este token no corresponde a ninguna.", "portal": "mapapropapi" }

Um 400, e você quer saber disso antes de escrever o código: esta fonte resolve a conta a partir do seu token, então funciona se o seu token veio de uma conta Mapaprop. Se você é uma plataforma cujos clientes têm conta Mapaprop, o que serve para você hoje é o webhook — por ali sim chegam as consultas dos seus clientes, sem que você precise pedi-las. É a mesma limitação de branches, e vamos resolvê-la: escreva para dev@mapaprop.com se isso bloquear você.

Os erros

QuandoO que fazer
400 portal_requiredfalta o ?portal=envie-o
403falta a você o scope {portal}:leadspeça para concedermos
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: consultar não modifica nada

Uma conta desativada não bloqueia esta consulta: os leads que já entraram são do seu cliente e podem ser recuperados do mesmo jeito.

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.