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"
}
| Clave | Tipo | Obligatorio | Qué es |
|---|---|---|---|
canonical | object | sí | El objeto de la propiedad |
portals | array | no | A qué portales la querés verificar |
options | object | no | Opciones por portal |
branchRef | string | no | Con 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
branchesy no tienebranch, 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
400y 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…" }
}
| 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 |
mapaprop | Só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.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.
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": "…" } }
state | qué pasó | qué hacer |
|---|---|---|
pending | todavía no corrió: la ingesta no terminó | esperar |
synced | la propiedad existe en tu cuenta, con el propertyId de Mapaprop | nada |
rejected | algo del objeto no se pudo guardar. El bloque nombra el campo | corregir con el PUT y reintentar |
blocked | la cuenta no está en condiciones | escribinos |
exhausted | se agotaron los reintentos automáticos | reintentar |
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
GET /properties— una propiedad por supaId, o el listadoDELETE /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 undiffde lo que cambió, con los campos que se vaciaron aparte
Errores
| Código | Cuándo |
|---|---|
400 canonical_missing | Falta canonical en el body |
400 account_required | Falta customer en el objeto |
400 invalid_body | El body no es JSON válido |
400 body_missing | No mandaste body |
401 | Token ausente, vencido o inválido |
404 | Ese paId no existe |
409 | Ya tenés una propiedad con ese code — ver abajo |
409 | images_processing — la propiedad está procesando sus imágenes. Ver abajo |
501 | PUT: 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 esepaId - ¿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
- Armás el objeto — los campos
- Lo probás con
/properties/verifyhasta que no quedenblockers POST /properties→ guardás elpaId- Consultás el
GEThasta queimages.statusdeje de serprocessing - Si quedó
partial, arreglás las URLs y llamás a/assets