DEVELOPING

Listar os imóveis de um cliente

GET /property-v1/properties

Devolve todos os imóveis que você carregou para o clientRef que pedir, com o estado de publicação de cada portal. É a leitura que você usa para reconciliar a sua base com a nossa: o que ficou carregado, o que foi publicado e onde.

curl https://property-api.mapaprop.com/property-v1/properties \
  -H "Authorization: Bearer $TOKEN" \
  -H "x-client-ref: cliente-42"

Resposta 200:

{
  "clientRef": "cliente-42",
  "total": 42,
  "items": [
    {
      "paId": "01M4BS9DR88PCN2WNR5WSH82D4",
      "status": "active",
      "createdAt": "2026-10-07T13:21:04.118Z",
      "updatedAt": "2026-10-07T20:41:55.902Z",
      "canonical": { "code": "DEV-V3-909181", "type": 1, "title": "Depto en Palermo", "...": "..." },
      "verdictAtCreation": { "...": "..." },
      "portals": {
        "zonaprop": { "remoteStatus": "published", "itemId": "...", "url": "https://..." }
      }
    }
  ]
}

Campo	O que é
`clientRef`	De quem é esta lista. Vem na resposta para que você não tenha que lembrar com qual header perguntou
`total`	Quantos vieram NESTA resposta, não quantos o cliente tem. Veja a nota abaixo
`items[].paId`	O id com o qual você o pede, edita e publica
`items[].status`	`active`, ou `deleted` se você deu baixa nele (só aparece com `includeDeleted=true`)
`items[].deletedAt`	Quando você deu baixa. Só nos que estão baixados — um ativo não traz o campo
`items[].canonical`	O objeto exatamente como você enviou
`items[].portals`	O estado por portal: `{}` se você nunca o publicou
`items[].verdictAtCreation`	O veredito do dia em que você o carregou. ⚠️ É daquele dia: se depois corrigimos um mapeamento, isto não sabe. O de hoje vem no `GET` por `paId`

Os dois parâmetros

Parâmetro	Default	O que faz
`limit`	sem limite	Corta nos primeiros N
`includeDeleted`	`false`	Inclui os que você deu baixa

# os 2 primeiros
curl "https://property-api.mapaprop.com/property-v1/properties?limit=2" …

# também os baixados
curl "https://property-api.mapaprop.com/property-v1/properties?includeDeleted=true" …

Não há paginação com cursor. Sem limit devolvemos todo o inventário desse cliente em uma resposta, e total é quantos vieram — não quantos há. Ou seja, total sem limit é de fato o inventário completo, mas com limit é o teto que você pediu e você não sabe quantos ficaram de fora.

Se você gerencia carteiras grandes, peça sem limit e processe a resposta inteira. Se precisar paginar de verdade, escreva para dev@mapaprop.com: o cursor não existe porque ninguém precisou dele ainda.

É uma leitura do nosso sistema: não custa nenhuma chamada da cota do seu cliente no portal. O que o portal diz de cada anúncio vem da consulta de estado, que custa 1 por imóvel.

O que devolve além do `GET` por `paId`

Nada: a lista devolve menos. É uma projeção pensada para percorrer, não para inspecionar.

	Lista	`GET /properties/{paId}`
O objeto e o estado por portal	✅	✅
O veredito de HOJE, recalculado	❌ — o da criação	✅
O estado das imagens (`images`)	❌	✅
O detalhe da última publicação (`lastPublish`)	❌	✅

Para reconciliar, a lista basta. Para entender um imóvel, peça o imóvel.

Códigos de resposta

Código	O que aconteceu
`200`	A lista. Se o cliente não tem nenhum, `total: 0` e `items: []`
`400`	Falta o header `x-client-ref`
`401`	Token ausente ou inválido
`403`	O seu token não tem o scope `property-api-read`

Um cliente sem imóveis devolve 200 com items: [], e não um 404. O 404 significaria que o cliente não existe, e isso é respondido pelo GET do cliente.

Relacionado

Consultar um imóvel — com o veredito de hoje e as imagens
Cadastro de imóveis · Modificar · Dar baixa
Publicar — e é de lá que sai o portals desta lista

Listar os imóveis de um cliente

Os dois parâmetros

O que devolve além do GET por paId

Códigos de resposta

Relacionado

O que devolve além do `GET` por `paId`