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…" }
}

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…"
  },

  "object":  { "…igual que el verify…" },
  "portals": { "…igual que el verify…" },
  "summary": { "…igual que el verify…" }
}

Clave	Qué es
`clientRef`	De 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
`paId`	El identificador de la propiedad en nuestra API. Es tu handle para todo lo que venga después
`saved`	Quedó guardada
`savedAt`	Cuándo
`status`	`active`, o `deleted` si la borraste
`images`	El estado de tus imágenes — 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.status`	Qué significa	Qué hacés
`processing`	Estamos bajándolas	Esperás y volvés a consultar
`ready`	Todas en nuestros servidores	Seguís
`partial`	Algunas no se pudieron bajar	Mirá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:

Motivo	Qué 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ón`	Tu servidor no aceptó la conexión
`HTTP 403`	Tu CDN nos bloqueó, o el archivo no está ahí — ver abajo
`HTTP 404`	La imagen no está en esa URL
`el origen no respondió en 15s`	Demasiado lenta
`el certificado del origen está vencido`	Problema 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.

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

GET /properties — una propiedad por su paId, o el listado
DELETE /properties/{paId} — borrar. No da de baja tus avisos en los portales

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ódigo	Cuándo
`400`	Falta `canonical` en el body, falta `customer` en el objeto, o el body no es JSON válido
`401`	Token ausente, vencido o inválido
`404`	Ese `paId` no existe
`409`	La propiedad está procesando sus imágenes — ver abajo
`501`	`PUT`: todavía no disponible

El `409`

{
  "status": 409,
  "error": "La propiedad está procesando sus imágenes",
  "detail": "Procesando 2 de 4 imágenes. No se puede modificar ni publicar hasta que terminen."
}

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

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