Listar as propriedades de um cliente
GET /property-v1/properties
Devolve as propriedades que você cadastrou para o clientRef que pedir, de 50 em 50, com o
status de publicação de cada portal e o das suas imagens. É a leitura que você usa para
reconciliar a sua base com a nossa: o que ficou cadastrado, como chegou e onde está publicado.
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": 50,
"nextToken": "eyJzayI6IlBST1AjMDFNNzVERUhES1FLVzFOSkc0MUZQTkFSM0cjQ0FOT05JQ0FMIiwiaCI6ImE5ZjMxYzAwOGIyZSJ9",
"items": [
{
"paId": "01M75DEHDKQKW1NJG41FPNAR3G",
"code": "DEV-909181",
"title": "Casa de 4 quartos em San Lorenzo Chico",
"status": "active",
"createdAt": "2026-11-11T13:41:08.147Z",
"updatedAt": "2026-11-11T14:56:07.327Z",
"images": { "total": 29, "ready": 29, "status": "ready" },
"mapaprop": { "propertyId": 2619616, "state": "synced", "images": { "saved": 29, "failed": 0 } },
"verdictAt": "2026-11-11T14:56:04.956Z",
"portals": {
"zonaprop": {
"verdict": "fields_complete",
"remoteStatus": "published",
"itemId": "01M73AB0SYGTFWFB8W2Z19SYP7",
"portalItemId": 60676441,
"url": "https://www.zonaprop.com.ar/propiedades/-60676441.html",
"publishedAt": "2026-11-11T14:56:12.185Z"
},
"argenprop": { "verdict": "fields_complete", "remoteStatus": null },
"mercadolibre": { "verdict": "fields_complete", "remoteStatus": null },
"cabaprop": { "verdict": "out_of_coverage", "remoteStatus": null }
}
}
]
}
Os campos
| Campo | O que é |
|---|---|
clientRef | De quem é esta listagem. Vem na resposta para que você não precise lembrar com qual header perguntou |
total | Quantas vieram NESTA página, não quantas o cliente tem |
nextToken | Com o que você pede a página seguinte. Se não vier, você terminou — veja a nota abaixo |
items[].paId | O id com o qual você a pede, a edita e a publica |
items[].code | O seu código, aquele que você enviou no objeto. É a chave com a qual você cruza contra a sua base |
items[].title | O título, para que a listagem seja lida sem cruzar nada |
items[].status | active, ou deleted se você a excluiu (só aparece com includeDeleted=true) |
items[].deletedAt | Quando você a excluiu. Só vem nas excluídas — uma ativa não traz o campo |
items[].images | Como as imagens chegaram: total as que você enviou, ready as que ficaram publicáveis, e o status da ingestão. Um ready menor que total é uma propriedade que vai publicar com menos fotos do que você espera |
items[].mapaprop | Só se a sua conta publica no Mapaprop. Como a propriedade ficou na sua conta do Mapaprop: propertyId o id com o qual você a vê no aplicativo, state como ficou o cadastro, e images quantas fotos foram salvas e quantas foram recusadas. ⚠️ É outra etapa que images: ali está a nossa ingestão, aqui o que o Mapaprop aceitou |
items[].verdictAt | Quando foi tomado o veredicto que cada portal traz. ⚠️ É daquele dia: se depois corrigirmos um mapeamento, isto não sabe disso. O de hoje é dado pelo GET por paId |
items[].portals | Uma entrada para cada portal contra o qual esta propriedade foi mapeada. São os mesmos que você vê no GET por paId |
portals[].* — o status por portal
| Campo | O que é |
|---|---|
verdict | Se o objeto é suficiente para aquele portal: ok, fields_complete, out_of_coverage… |
blockers | Os campos que faltam ou não servem. Só vem se houver algum; o detalhe de cada um é dado pelo GET por paId |
remoteStatus | O que o portal diz do anúncio. Vem sempre: em null significa que nunca foi publicado |
itemId | O id da publicação do nosso lado |
portalItemId | O id do anúncio no portal, quando o portal o devolve ao publicar |
url | O anúncio publicado |
publishedAt · unpublishedAt | Quando foi publicado e quando foi retirado |
lastError | A última recusa do portal sobre este anúncio, se houve |
Os campos deste bloco —exceto verdict e remoteStatus— são omitidos quando não existem. Um
url em null afirmaria que o anúncio não tem URL; o certo é que ainda não foi publicado.
Os parâmetros
| Parâmetro | Padrão | O que faz |
|---|---|---|
limit | 50 | Quantas por página. O máximo é 50: um valor mais alto é cortado para 50, e um que não seja entendido é ignorado (não dá erro) |
nextToken | — | O nextToken da página anterior, tal e qual. É opaco: não o monte nem o edite |
includeDeleted | false | Inclui as que você excluiu |
include | — | include=canonical acrescenta items[].canonical, o objeto tal como você o enviou. ⚠️ Até 2026-12-19 ele também vem sem pedir; depois dessa data é preciso pedi-lo (Mudanças da API) |
# a primeira página
curl "https://property-api.mapaprop.com/property-v1/properties" …
# a seguinte
curl "https://property-api.mapaprop.com/property-v1/properties?nextToken=eyJzayI6…" …
# de 10 em 10, também as excluídas
curl "https://property-api.mapaprop.com/property-v1/properties?limit=10&includeDeleted=true" …
O percurso termina quando NÃO vem nextToken. Que total seja menor que o seu limit NÃO
significa que você terminou.
Uma página pode vir curta —até vazia— e trazer nextToken do mesmo jeito: acontece quando há
muitas propriedades excluídas seguidas e a página se gasta pulando-as. Se você cortar o percurso
por total < limit, fica sem parte do inventário e nada o avisa.
O laço correto é sempre o mesmo:
let token;
do {
const r = await get(`/property-v1/properties${token ? `?nextToken=${token}` : ''}`);
processar(r.items);
token = r.nextToken; // ← a condição é ESTA, não r.total
} while (token);
É uma leitura do nosso sistema: não custa nenhuma chamada da cota do seu cliente no portal, nem a primeira página nem a última. O que o portal diz de cada anúncio é trazido pela consulta de status, que custa 1 por propriedade.
O que devolve a mais do que o GET por paId
Nada: a listagem traz menos. É uma projeção pensada para percorrer, não para inspecionar.
| Listagem | GET /properties/{paId} | |
|---|---|---|
| O código, o título e as datas | ✅ | ✅ |
O status por portal (remoteStatus, url, portalItemId) | ✅ | ✅ |
| O resumo das imagens | ✅ {total, ready, status} | ✅ com o detalhe de cada uma |
| Como ficou na sua conta do Mapaprop | ✅ mapaprop | ✅ |
| O objeto que você postou | com ?include=canonical | ✅ |
| O veredicto de HOJE, recalculado | ❌ — o do dia do cadastro | ✅ |
O detalhe de cada blocker | ❌ — só o nome do campo | ✅ |
O detalhe da última publicação (lastPublish) | ❌ | ✅ |
Para reconciliar, a listagem é suficiente. Para entender uma propriedade, peça a propriedade.
Códigos de resposta
| Código | O que aconteceu |
|---|---|
200 | A página. Se o cliente não tiver nenhuma, total: 0, items: [] e sem nextToken |
400 | Falta o header x-client-ref, ou o nextToken não é válido ("error": "invalid_next_token") |
401 | Token ausente ou inválido |
403 | O seu token não tem o scope property-api-read |
Um nextToken inválido —mal copiado, cortado, ou de outra conta— é um 400 e não um 200 com a
primeira página: servir a primeira em silêncio faria você percorrer as mesmas propriedades para
sempre. Se você perdeu o token, comece de novo sem ele.
Um cliente sem propriedades devolve 200 com items: [], não um 404. O 404 significaria que
o cliente não existe, e isso é respondido pelo GET do cliente.
Relacionado
- Consultar uma propriedade — com o veredicto de hoje e as imagens
- Cadastro de propriedades · Modificar · Excluir
- Publicar — e é daí que sai o
portalsdesta listagem