BETA

Listar las propiedades de un cliente

GET /property-v1/properties

Devuelve las propiedades que cargaste para el clientRef que pidas, de a 50, con el estado de publicación de cada portal y el de sus imágenes. Es la lectura que usás para reconciliar tu base con la nuestra: qué quedó cargado, cómo llegó y dónde está publicado.

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

Respuesta 200:

{
  "clientRef": "cliente-42",
  "total": 50,
  "nextToken": "eyJzayI6IlBST1AjMDFNNzVERUhES1FLVzFOSkc0MUZQTkFSM0cjQ0FOT05JQ0FMIiwiaCI6ImE5ZjMxYzAwOGIyZSJ9",
  "items": [
    {
      "paId": "01M75DEHDKQKW1NJG41FPNAR3G",
      "code": "DEV-909181",
      "title": "Casa 4 dormitorios en 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 }
      }
    }
  ]
}

Los campos

CampoQué es
clientRefDe quién es este listado. Viene en la respuesta para que no tengas que acordarte con qué header preguntaste
totalCuántas vinieron en ESTA página, no cuántas tiene el cliente
nextTokenCon qué pedís la página siguiente. Si no viene, terminaste — ver la nota de abajo
items[].paIdEl id con el que la pedís, la editás y la publicás
items[].codeTu código, el que mandaste en el objeto. Es la clave con la que cruzás contra tu base
items[].titleEl título, para que el listado se lea sin cruzar nada
items[].statusactive, o deleted si la diste de baja (sólo aparece con includeDeleted=true)
items[].deletedAtCuándo la diste de baja. Sólo viene en las borradas — una activa no trae el campo
items[].imagesCómo llegaron las imágenes: total las que mandaste, ready las que quedaron publicables, y el status de la ingesta. Un ready menor que total es una propiedad que va a publicar con menos fotos de las que esperás
items[].mapapropSólo si tu cuenta publica en Mapaprop. Cómo quedó la propiedad en tu cuenta de Mapaprop: propertyId el id con el que la ves en la app, state en qué quedó el alta, e images cuántas fotos se guardaron y cuántas se rechazaron. ⚠️ Es otro paso que images: ahí está nuestra ingesta, acá lo que Mapaprop aceptó
items[].verdictAtCuándo se tomó el veredicto que trae cada portal. ⚠️ Es de ese día: si después arreglamos un mapeo, esto no lo sabe. El de hoy lo da el GET por paId
items[].portalsUna entrada por cada portal contra el que se mapeó esta propiedad. Son los mismos que ves en el GET por paId

portals[].* — el estado por portal

CampoQué es
verdictSi el objeto alcanza para ese portal: ok, fields_complete, out_of_coverage…
blockersLos campos que faltan o no sirven. Sólo viene si hay alguno; el detalle de cada uno lo da el GET por paId
remoteStatusQué dice el portal del aviso. Siempre viene: en null significa que nunca se publicó
itemIdEl id de la publicación del lado nuestro
portalItemIdEl id del aviso en el portal, donde el portal lo devuelve al publicar
urlEl aviso publicado
publishedAt · unpublishedAtCuándo se publicó y cuándo se bajó
lastErrorEl último rechazo del portal sobre este aviso, si hubo

Los campos de este bloque —salvo verdict y remoteStatus— se omiten cuando no existen. Un url en null afirmaría que el aviso no tiene URL; lo cierto es que todavía no se publicó.

Los parámetros

ParámetroDefaultQué hace
limit50Cuántas por página. El máximo es 50: un valor más alto se recorta a 50, y uno que no se entienda se ignora (no da error)
nextToken—El nextToken de la página anterior, tal cual. Es opaco: no lo armes ni lo edites
includeDeletedfalseIncluye las que diste de baja
include—include=canonical agrega items[].canonical, el objeto tal como lo mandaste. ⚠️ Hasta el 2026-12-19 viene también sin pedirlo; después hay que pedirlo (Cambios de la API)
# la primera página
curl "https://property-api.mapaprop.com/property-v1/properties" …

# la siguiente
curl "https://property-api.mapaprop.com/property-v1/properties?nextToken=eyJzayI6…" …

# de a 10, también las dadas de baja
curl "https://property-api.mapaprop.com/property-v1/properties?limit=10&includeDeleted=true" …

El recorrido termina cuando NO viene nextToken. Que total sea menor que tu limit NO significa que terminaste.

Una página puede venir corta —incluso vacía— y traer nextToken igual: pasa cuando hay muchas propiedades dadas de baja seguidas y la página se gasta saltándolas. Si cortás el recorrido por total < limit, te quedás sin parte del inventario y nada te avisa.

El bucle correcto es siempre el mismo:

let token;
do {
  const r = await get(`/property-v1/properties${token ? `?nextToken=${token}` : ''}`);
  procesar(r.items);
  token = r.nextToken;      // ← la condición es ÉSTA, no r.total
} while (token);

Es una lectura de nuestro sistema: no cuesta ninguna llamada del cupo de tu cliente en el portal, ni la primera página ni la última. Lo que el portal dice de cada aviso lo trae la consulta de estado, que sí cuesta 1 por propiedad.

Qué devuelve de más que el GET por paId

Nada: el listado trae menos. Es una proyección pensada para recorrer, no para inspeccionar.

ListadoGET /properties/{paId}
El código, el título y las fechas✅✅
El estado por portal (remoteStatus, url, portalItemId)✅✅
El resumen de las imágenes✅ {total, ready, status}✅ con el detalle de cada una
Cómo quedó en tu cuenta de Mapaprop✅ mapaprop✅
El objeto que posteastecon ?include=canonical✅
El veredicto de HOY, recalculado❌ — el del día del alta✅
El detalle de cada blocker❌ — sólo el nombre del campo✅
El detalle de la última publicación (lastPublish)❌✅

Para reconciliar, el listado alcanza. Para entender una propiedad, pedí la propiedad.

Códigos de respuesta

CódigoQué pasó
200La página. Si el cliente no tiene ninguna, total: 0, items: [] y sin nextToken
400Falta el header x-client-ref, o el nextToken no es válido ("error": "invalid_next_token")
401Token ausente o inválido
403Tu token no tiene el scope property-api-read

Un nextToken inválido —mal copiado, cortado, o de otra cuenta— es un 400 y no un 200 con la primera página: servirte la primera en silencio te haría recorrer las mismas propiedades para siempre. Si perdiste el token, empezá de nuevo sin él.

Un cliente sin propiedades devuelve 200 con items: [], no un 404. El 404 significaría que el cliente no existe, y eso lo contesta el GET del cliente.

Relacionado