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
| Campo | Qué es |
|---|---|
clientRef | De quién es este listado. Viene en la respuesta para que no tengas que acordarte con qué header preguntaste |
total | Cuántas vinieron en ESTA página, no cuántas tiene el cliente |
nextToken | Con qué pedís la página siguiente. Si no viene, terminaste — ver la nota de abajo |
items[].paId | El id con el que la pedís, la editás y la publicás |
items[].code | Tu código, el que mandaste en el objeto. Es la clave con la que cruzás contra tu base |
items[].title | El título, para que el listado se lea sin cruzar nada |
items[].status | active, o deleted si la diste de baja (sólo aparece con includeDeleted=true) |
items[].deletedAt | Cuándo la diste de baja. Sólo viene en las borradas — una activa no trae el campo |
items[].images | Có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[].mapaprop | Só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[].verdictAt | Cuá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[].portals | Una 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
| Campo | Qué es |
|---|---|
verdict | Si el objeto alcanza para ese portal: ok, fields_complete, out_of_coverage… |
blockers | Los campos que faltan o no sirven. Sólo viene si hay alguno; el detalle de cada uno lo da el GET por paId |
remoteStatus | Qué dice el portal del aviso. Siempre viene: en null significa que nunca se publicó |
itemId | El id de la publicación del lado nuestro |
portalItemId | El id del aviso en el portal, donde el portal lo devuelve al publicar |
url | El aviso publicado |
publishedAt · unpublishedAt | Cuándo se publicó y cuándo se bajó |
lastError | El ú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ámetro | Default | Qué hace |
|---|---|---|
limit | 50 | Cuá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 |
includeDeleted | false | Incluye 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.
| Listado | GET /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 posteaste | con ?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ódigo | Qué pasó |
|---|---|
200 | La página. Si el cliente no tiene ninguna, total: 0, items: [] y sin nextToken |
400 | Falta el header x-client-ref, o el nextToken no es válido ("error": "invalid_next_token") |
401 | Token ausente o inválido |
403 | Tu 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
- Consultar una propiedad — con el veredicto de hoy y las imágenes
- Alta de propiedades · Modificar · Dar de baja
- Publicar — y de ahí sale el
portalsde este listado