BETA

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

CampoO que é
clientRefDe quem é esta listagem. Vem na resposta para que você não precise lembrar com qual header perguntou
totalQuantas vieram NESTA página, não quantas o cliente tem
nextTokenCom o que você pede a página seguinte. Se não vier, você terminou — veja a nota abaixo
items[].paIdO id com o qual você a pede, a edita e a publica
items[].codeO seu código, aquele que você enviou no objeto. É a chave com a qual você cruza contra a sua base
items[].titleO título, para que a listagem seja lida sem cruzar nada
items[].statusactive, ou deleted se você a excluiu (só aparece com includeDeleted=true)
items[].deletedAtQuando você a excluiu. Só vem nas excluídas — uma ativa não traz o campo
items[].imagesComo 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[].mapapropSó 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[].verdictAtQuando 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[].portalsUma 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

CampoO que é
verdictSe o objeto é suficiente para aquele portal: ok, fields_complete, out_of_coverage…
blockersOs campos que faltam ou não servem. Só vem se houver algum; o detalhe de cada um é dado pelo GET por paId
remoteStatusO que o portal diz do anúncio. Vem sempre: em null significa que nunca foi publicado
itemIdO id da publicação do nosso lado
portalItemIdO id do anúncio no portal, quando o portal o devolve ao publicar
urlO anúncio publicado
publishedAt · unpublishedAtQuando foi publicado e quando foi retirado
lastErrorA ú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âmetroPadrãoO que faz
limit50Quantas 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
includeDeletedfalseInclui 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.

ListagemGET /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ê postoucom ?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ódigoO que aconteceu
200A página. Se o cliente não tiver nenhuma, total: 0, items: [] e sem nextToken
400Falta o header x-client-ref, ou o nextToken não é válido ("error": "invalid_next_token")
401Token ausente ou inválido
403O 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