BETA

POST /properties

Es el mismo objeto y la misma respuesta que POST /properties/verify, con dos diferencias: acá la propiedad queda guardada y te devolvemos un identificador para operar con ella después.

Si el verify dice que un portal puede publicar tu propiedad, el alta dice lo mismo. No hay sorpresas entre los dos.

No publica en ningún portal. El alta guarda la propiedad y prepara todo; publicar es un paso aparte.

Para qué sirve

Para cargar la propiedad una sola vez y quedarte con un identificador que usás para consultarla, actualizar sus imágenes o borrarla.

Las imágenes las mandás como URLs y nosotros las descargamos: a partir del alta quedan en nuestros servidores.

Resource URL

POST https://property-api.mapaprop.com/property-v1/properties

Autenticación

Igual que el resto de la API: Authorization: Bearer <tu token>.

curl -X POST https://property-api.mapaprop.com/property-v1/properties \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @propiedad.json

🔑 clientRef — de QUÉ cliente es esta propiedad

Va junto con el token, de cualquiera de estas tres formas:

x-client-ref: cliente-42          ← header (recomendado)
?clientRef=cliente-42             ← query
{ "clientRef": "cliente-42", … }  ← body

Es el id del CLIENTE, no de la propiedad. El mismo clientRef para todas las propiedades de ese cliente tuyo.

Es lo que agrupa el inventario: GET /properties te devuelve las de un clientRef, y es lo que separa a un cliente tuyo de otro. Si mandás el id de cada propiedad, cada una queda en su propio grupo y el listado te devuelve una sola.

El valor lo elegís vos y es opaco para nosotros: tu id interno, un UUID, lo que uses — siempre que identifique al cliente. Es el mismo clientRef con el que registrás sus conexiones a portales.

El cuerpo de la petición

El cliente se declara UNA vez, no en cada propiedad. Antes de tu primera alta, declarala con POST /property-v1/customers: te devuelve el customerId que le asigna Mapaprop, y desde ahí todas tus propiedades heredan su nombre, teléfono, email, dirección y sucursal. Sin ella el alta responde 400 con rule: account_required.

Cambiarle un dato después es un PUT a la misma ruta. ⚠️ Alcanza a las propiedades nuevas: las que ya cargaste conservan el contacto con el que se dieron de alta, que es el registro de cómo se publicaron.

⚠️ Si mandás customer dentro del objeto, se ignora (como propertyId, customerId y branchId).

Exactamente el mismo que el verify: el objeto va en canonical.

{
  "canonical": { "…el objeto de la propiedad…" },
  "branchRef": "norte"
}
ClaveTipoObligatorioQué es
canonicalobjectsíEl objeto de la propiedad
portalsarraynoA qué portales la querés verificar
optionsobjectnoOpciones por portal
branchRefstringnoCon qué sucursal del cliente sale publicada — ver abajo

branchRef — con qué sucursal sale publicada

Si tu cliente tiene varias sucursales declaradas en branches, branchRef dice con cuál sale esta propiedad: su nombre, su teléfono y su email son los que el portal publica como contacto del aviso.

  • Si no lo mandás, sale con la sucursal por defecto (branch).
  • Si tu cliente declara branches y no tiene branch, es obligatorio: sin sucursal por defecto no hay forma de saber cuál querés, y no elegimos por vos.
  • Si mandás una referencia que no existe, la respuesta es 400 y te dice cuáles son las válidas.
  • Si la sucursal ya existe en Mapaprop, mandá su branchId (un número) y no hace falta declararla en la ficha: "branchRef": 777.

La sucursal se congela en la propiedad al darla de alta. Es el registro de con qué datos se publicó, y cambiarla después es un 409: se borra la propiedad y se vuelve a postear. Cambiar los datos de la sucursal en la ficha, en cambio, alcanza a las propiedades nuevas.

Los campos, sus reglas y cuáles son obligatorios están en El objeto JSON de la propiedad. La configuración de publicación por portal, en La clave publication.

Probá el objeto con /properties/verify antes de dar de alta. No crea nada y te dice lo mismo que va a decir el alta.

La respuesta

201 Created. Es la respuesta del verify más estas cinco claves:

{
  "paId": "01M3PTZ8YBMM5DSNW03WP8VD9E",
  "saved": true,
  "savedAt": "2026-09-29T15:01:46.059Z",
  "status": "active",
  "images": {
    "status": "processing",
    "total": 4,
    "processed": 0,
    "message": "Procesando 4 imágenes…"
  },
  "mapaprop": { "state": "pending" },

  "object":  { "…igual que el verify…" },
  "portals": { "…igual que el verify…" },
  "summary": { "…igual que el verify…" }
}
ClaveQué es
clientRefDe qué cliente es. El mismo que mandaste en el sobre — te lo devolvemos para que puedas cruzarlo con tu base sin recordar con qué preguntaste
paIdEl identificador de la propiedad en nuestra API. Es tu handle para todo lo que venga después
savedQuedó guardada
savedAtCuándo
statusactive, o deleted si la borraste
imagesEl estado de tus imágenes — ver abajo
mapapropSólo si sos cliente de Mapaprop: el estado del alta en tu cuenta — ver abajo

Los bloques object, portals y summary son los mismos del verify y están explicados ahí.

🔑 Guardá el paId

Es el único identificador de esa propiedad de nuestro lado. Guardalo en tu sistema junto al id que uses vos. Sin él no hay forma de consultarla, actualizarle las imágenes ni borrarla.

No lo generás vos y no podés elegirlo. Si volvés a postear el mismo objeto, se crea una propiedad nueva con otro paId: el alta no deduplica.

Las imágenes: qué pasa después del 201

Al responderte arrancamos la descarga de tus imágenes. Es lo único del alta que no es inmediato.

201  →  images.status: "processing"   …bajando tus imágenes…
        images.status: "ready"        listo
                    o "partial"       algunas no se pudieron bajar

Mientras están en processing, la propiedad no se puede modificar, borrar ni publicar. Cualquier llamada te devuelve 409 diciéndote cuántas van.

El estado se consulta con GET /property-v1/properties/{paId}. Suele tardar pocos segundos.

Esperá 2-3 segundos entre consultas. Con volúmenes normales alcanzan 3 o 4: medido, 40 imágenes tardaron 9 segundos. Consultar en un bucle sin pausa no te va a dar la respuesta antes.

Qué hacer con cada estado

images.statusQué significaQué hacés
processingEstamos bajándolasEsperás y volvés a consultar
readyTodas en nuestros servidoresSeguís
partialAlgunas no se pudieron bajarMirás assets y reintentás

Cuando algo falla: assets

El GET trae una entrada por imagen, con la URL que falló y el motivo:

"assets": [
  { "n": 1, "slot": "image", "source": "https://tu-cdn.com/frente.jpg",
    "url": "https://…/image-1.jpg", "ok": true },
  { "n": 2, "slot": "image", "source": "https://tu-cdn.com/living.jpg",
    "error": "el host del origen no existe (DNS no resuelve) [ENOTFOUND]", "ok": false }
]

Los motivos más comunes:

MotivoQué mirar
el host del origen no existe (DNS no resuelve)La URL está mal escrita, o el dominio ya no existe
el origen rechazó la conexiónTu servidor no aceptó la conexión
HTTP 403Tu CDN nos bloqueó, o el archivo no está ahí — ver abajo
HTTP 404La imagen no está en esa URL
el origen no respondió en 15sDemasiado lenta
el certificado del origen está vencidoProblema de HTTPS de tu lado

Un HTTP 403 de tu propio bucket de S3 casi siempre significa que el archivo NO ESTÁ. Si el bucket no expone el listado —lo normal— S3 responde 403 en vez de 404 para no revelar qué claves existen. Así que antes de revisar permisos, verificá que la URL apunte a un archivo que siga ahí.

Si te da partial, la propiedad igual quedó guardada con las imágenes que sí pudimos bajar. Arreglás las URLs que fallaron y reintentás; no hace falta dar de alta otra vez.

El alta en tu cuenta de Mapaprop

Si sos cliente de Mapaprop y generaste tu token desde la app (Mapaprop > App y Token), esta misma llamada hace algo más: la propiedad se da de alta sola en tu cuenta, como si la hubieras cargado desde la app. No hay nada que pedir.

Pasa cuando termina la ingesta de las imágenes, no en el 201: una propiedad llega a tu cuenta con sus fotos ya cargadas. Por eso el bloque mapaprop de la respuesta suele decir pending.

{ "mapaprop": { "state": "synced", "propertyId": 2619527, "branchId": 1, "message": "…" } }
statequé pasóqué hacer
pendingtodavía no corrió: la ingesta no terminóesperar
syncedla propiedad existe en tu cuenta, con el propertyId de Mapapropnada
rejectedalgo del objeto no se pudo guardar. El bloque nombra el campocorregir con el PUT y reintentar
blockedla cuenta no está en condicionesescribinos
exhaustedse agotaron los reintentos automáticosreintentar

El estado se consulta en el GET de la propiedad, que trae el mismo bloque ya resuelto.

Dada de alta no es publicada. synced significa que la propiedad existe en tu cuenta; publicarla es una decisión tuya, con PUT …/publication/mapaprop.

Si tu token no salió de una cuenta de Mapaprop —el caso de un integrador que publica para clientes que no son clientes nuestros— el bloque no viaja y no hay alta: tus propiedades viven sólo en PropertyAPI. Todo esto está explicado en Mapaprop.

Reintentar las imágenes

POST https://property-api.mapaprop.com/property-v1/properties/{paId}/assets

Vuelve a intentar sólo las que faltan: las que ya están en nuestros servidores no se tocan ni se vuelven a bajar. Responde 202 con el estado nuevo.

Sirve cuando el GET te dio partial y ya corregiste el problema de tu lado.

Consultar y borrar

Modificar

  • PUT /properties/{paId} — reemplazo total: mandás el objeto completo y te devolvemos un diff de lo que cambió, con los campos que se vaciaron aparte

Errores

CódigoCuándo
400 canonical_missingFalta canonical en el body
400 account_requiredFalta customer en el objeto
400 invalid_bodyEl body no es JSON válido
400 body_missingNo mandaste body
401Token ausente, vencido o inválido
404Ese paId no existe
409Ya tenés una propiedad con ese code — ver abajo
409images_processing — la propiedad está procesando sus imágenes. Ver abajo
501PUT: todavía no disponible

El 409 por code repetido

El code es único por cuenta. Es el código con el que identificás la propiedad en tu sistema, así que no puede haber dos propiedades tuyas con el mismo.

{
  "error": "code_already_exists",
  "detail": "Ya tenés una propiedad con el código \"CMT-0014\". …",
  "code": "CMT-0014",
  "paId": "01M41AQNXYG4W4SEEEEPHEDNX4"
}

Te devolvemos el paId de la que ya existe, que es lo que necesitás para actuar:

  • ¿querés actualizarla? → PUT /property-v1/properties/{paId} con ese paId
  • ¿es otra propiedad? → mandá otro code

Dos cosas que conviene saber:

  • Es por cuenta, no global. Otro integrador puede usar el mismo código sin problema: es el código de tu sistema.
  • El código de una propiedad que diste de baja se puede reusar. Sólo cuentan las vivas.

Si venías re-posteando tu inventario entero cada vez, antes se creaban duplicados y ahora vas a recibir 409. Eso es lo que te dice qué propiedades ya tenías: con el paId que viene en la respuesta, el re-posteo se convierte en PUT.

El 409 por imágenes procesando

{
  "status": 409,
  "error": "images_processing",
  "detail": "La propiedad está procesando sus imágenes. Procesando 2 de 4 imágenes. No se puede modificar ni publicar hasta que terminen. El estado está en GET /property-v1/properties/{paId}."
}

No es un error de tu petición: es que todavía no terminamos. Volvés a consultar el GET y reintentás cuando esté en ready o partial.

Si una descarga se traba, el bloqueo se libera solo pasado un rato, y ahí podés reintentar las imágenes o borrar la propiedad.

Cómo usarlo

  1. Armás el objeto — los campos
  2. Lo probás con /properties/verify hasta que no queden blockers
  3. POST /properties → guardás el paId
  4. Consultás el GET hasta que images.status deje de ser processing
  5. Si quedó partial, arreglás las URLs y llamás a /assets