El objeto JSON de la propiedad
Esta es la referencia de lo que vos mandás: qué campos tiene el objeto propiedad, cuáles son obligatorios, qué valores acepta cada uno y cómo se dice "este dato no lo tengo".
Es una referencia del objeto, no de un endpoint. Para entender cómo se identifica una propiedad —por qué el tipo y la operación son claves estables y de dónde salen sus valores— leé primero El modelo de propiedad.
El objeto que mandás
Éste es el objeto completo. Abajo está qué es obligatorio, qué es opcional y qué valores acepta cada campo.
{
"code": "DEV-V3-909181",
"type": 1,
"operation": 2,
"title": "Hermoso departamento luminoso con excelente ubicación y amenities completos",
"address": "Av. Santa Fe 4271",
"mapLatitude": -34.5828,
"mapLongitude": -58.4206,
"zone0": 1,
"zone1": 1,
"zone2": 46,
"description": "Excelente propiedad ubicada en zona premium con fácil acceso a transporte público, comercios y servicios. Ideal para vivir o invertir.\n\nCuenta con todos los servicios y amenities modernos. Perfecta para familias o inversión.\n\nUbicación estratégica con fácil acceso a centros comerciales, escuelas y transporte público.",
"descriptionFormatted": "Excelente propiedad ubicada en zona premium con fácil acceso a transporte público, comercios y servicios. Ideal para vivir o invertir.\n\nCuenta con todos los servicios y amenities modernos. Perfecta para familias o inversión.\n\nUbicación estratégica con fácil acceso a centros comerciales, escuelas y transporte público.",
"zipcode": "1425",
"betweenStreets": "Entre Av. Pueyrredón y Av. Coronel Díaz",
"urlWebExternal": "https://ejemplo-inmobiliaria.com/propiedad-dev",
"conditions": "Contado",
"yearsOld": 16,
"totalFloors": 16,
"apartmentsPerFloor": 3,
"floors": 2,
"buildingArea": 126,
"landArea": 189,
"ambiences": 2,
"rooms": 3,
"dependencies": 1,
"bathrooms": 1,
"toilettes": 2,
"garage": 2,
"currency": "USD",
"price": 142410,
"zone3": 0,
"rented": false,
"sold": false,
"reserved": false,
"suspended": false,
"occupancy": null,
"images": [
{
"url": "https://cdn.ejemplo.com/propiedades/909181/foto-1.jpg",
"description": "Imagen principal",
"main": true
},
{
"url": "https://cdn.ejemplo.com/propiedades/909181/foto-2.jpg",
"description": "Imagen 2",
"main": false
},
{
"url": "https://cdn.ejemplo.com/propiedades/909181/foto-3.jpg",
"description": "Imagen 3",
"main": false
}
],
"blueprint": {
"url": "https://cdn.ejemplo.com/propiedades/909181/plano.jpg"
},
"videos": [
{
"source": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
"description": "Recorrido"
}
],
"prices": {
"expensesCurrency": "ARS",
"expensesPrice": 500,
"taxCurrency": "ARS",
"taxPrice": 200,
"paymentPeriod": 1
},
"altPrices": [
{
"description": "Alquiler por semana",
"currency": "ARS",
"price": 100000
}
],
"attributes": [
{
"locale": "es_AR",
"country": "ar",
"id": "accessible",
"label": "Accesible",
"group": "propertyAttribute",
"group_sub": "label",
"group_subtype": "ammenities",
"type": "bool",
"key_legacy": "accessible",
"selected": true,
"status": true
},
{
"locale": "es_AR",
"country": "ar",
"id": "statusAverage",
"label": "Estado Regular",
"group": "propertyStatus",
"group_sub": "status",
"type": "list",
"key_legacy": "8",
"value": 8
},
// … y 42 entradas más, una por cada atributo de la propiedad
],
"publication": { … } // la configuración de publicación por portal — ver su propia página
}
Las fotos, el plano, los videos y los precios accesorios
Van en el mismo JSON: mandás un objeto solo.
| Bloque | Forma | Nota |
|---|---|---|
images | lista de {url, description, main} | la URL, no el archivo: el binario no viaja en un JSON |
blueprint | {url} | uno solo por propiedad |
videos | lista de {source, description} | source es la URL de YouTube o Matterport |
prices | {expensesCurrency, expensesPrice, taxCurrency, taxPrice, paymentPeriod} | expensas e impuestos, montos como número |
altPrices | lista de {description, currency, price} | precios alternativos |
⚠️ El price y la currency de la propiedad no van acá: son campos del inmueble y ya están más
arriba.
Los cinco bloques se registran en la misma llamada. Mandás el objeto una vez y las fotos, el plano, los videos, las expensas y los precios alternativos se guardan con la propiedad — no hay una segunda llamada por accesorio.
Y acá la regla de arriba tiene una consecuencia útil: como el price no va dentro de prices,
registrar las expensas no puede cambiar el precio de la propiedad.
El arreglo attributes
Cada entrada describe un dato. Hay dos familias: el estado de la propiedad
(propertyStatus) y los atributos — amenidades, orientación, tipo de calefacción y demás
(propertyAttribute).
[
{
"locale": "es_AR",
"country": "ar",
"id": "accessible",
"label": "Accesible",
"group": "propertyAttribute",
"group_sub": "label",
"group_subtype": "ammenities",
"type": "bool",
"key_legacy": "accessible",
"selected": true,
"status": true
},
{
"locale": "es_AR",
"country": "ar",
"id": "statusAverage",
"label": "Estado Regular",
"group": "propertyStatus",
"group_sub": "status",
"type": "list",
"key_legacy": "8",
"value": 8
}
]
El valor que mandás es key_legacy: es el mismo en todos los países. El id, el label y el
value salen del catálogo de tu país — de dónde sacarlos está más abajo.
attributes es obligatorio, y una lista vacía es válida. Si la propiedad no tiene ningún
atributo mandá "attributes": []; lo que no se puede es omitir la clave.
El bag se verifica contra el catálogo
Cada entrada se busca en el catálogo del país de la propiedad, y lo que no cuadra sale en
object.contract del verificador:
| Qué | Qué te decimos | ¿Invalida el objeto? |
|---|---|---|
el id no existe en ese país | rule: unknown — se ignora, la propiedad se guarda igual | no |
el key_legacy no es el del catálogo | rule: attribute_value, con el que corresponde | sí |
un atributo bool con un selected que no es booleano | rule: attribute_value | sí |
El catálogo no es el mismo en los 15 países. Los juegos de claves son subconjuntos: lo que existe en Argentina puede no existir en Paraguay o Brasil. Pedí el catálogo con el país de la propiedad, no con uno cualquiera — es la causa más común de un atributo que no se publica.
Un id inventado no rompe el alta: se ignora. Pero esa característica no viaja a ningún portal,
y eso no se nota mirando la propiedad — por eso se reporta.
customerSource — de dónde salió el cliente
Toda respuesta que trae el bloque customer trae también, en la raíz, de dónde salió:
| Valor | Qué significa |
|---|---|
account | Es tu ficha, la leímos con tu clientRef. Lo normal |
placeholder | No declaraste ficha y esto es relleno. Sólo pasa en /verify — el alta sin ficha responde 400, no rellena. Se arregla con POST /customers |
frozen | El snapshot con el que esa propiedad se dio de alta (lo devuelven el GET y el PUT). No es tu ficha de hoy, y es deliberado: así el GET dice con qué datos se publicó esa propiedad |
Está en la raíz y no dentro de customer a propósito: adentro se mezclaría con los campos que
declaraste vos.
El cliente NO es parte de este objeto
El cliente se declara una vez, aparte, y sus propiedades lo heredan.
👉 Clientes — el POST /property-v1/customers,
sus campos, el customerId que te devolvemos y la sucursal.
⚠️ Si mandás customer dentro de este objeto, se ignora — como propertyId, customerId y
branchId. Y sin cliente declarado, el alta responde 400 con rule: account_required.
publication — cómo se publica
Dentro del mismo objeto viaja una clave publication con lo que cada portal necesita de tu cuenta y
de tus elecciones de publicación. No es un campo del inmueble: es cómo lo publicás.
{
"publication": {
"api": {
"argenprop": {
"visible": true,
"token": "<tu-token-de-argenprop>"
},
"zonaprop": {
"plan": {
"plan": "SUPERDESTACADO"
},
"token": "<tu-token-de-zonaprop>"
},
"cabaprop": {
"token": "<tu-token-de-cabaprop>"
},
"mercadolibre": {
"listingTypeId": "gold_special",
"condition": "used",
"token": "<tu-token-de-mercadolibre>"
}
}
}
}
La referencia completa está en La clave publication.
Campos obligatorios
Son 26, más el arreglo attributes. Todo lo demás es opcional.
La mayoría son campos sueltos:
| Campo | Tipo | Regla | |
|---|---|---|---|
code | string | ^[A-Za-z0-9._-]{1,30}$ | |
title | string | 1–150 caracteres | |
description | string | al menos 1 carácter | |
price | integer | 1 o más | |
currency | string | USD o ARS | |
type | integer | — | el id del tipo — pa_key_legacy del grupo type del catálogo |
operation | integer | — | el id de la operación — pa_key_legacy del grupo operation |
zone0 | integer | uno de los 15 países | país. La lista sale del catálogo: si el tuyo no está, no podemos resolver ni el tipo ni la operación |
zone1 | integer | — | provincia |
zone2 | integer | — | partido o departamento |
address | string | al menos 1 carácter | |
zipcode | string | ^[A-Za-z0-9-]{1,10}$ | |
mapLatitude | number | -90 – 90 | ver el aviso de abajo |
mapLongitude | number | -180 – 180 | ver el aviso de abajo |
buildingArea | integer | 0 – 100.000 | superficie construida, en m² |
landArea | integer | 1 – 10.000.000 | superficie TOTAL de la propiedad, en m² — también en un departamento |
ambiences | integer | 0 – 50 | los ambientes |
rooms | integer | 0 – 50 | ⚠️ son dormitorios, no ambientes |
bathrooms | integer | 0 – 50 | |
toilettes | integer | 0 – 10 | |
garage | integer | 0 – 100 | |
floors | integer | 0 – 10 | plantas de la unidad |
totalFloors | integer | 0 – 200 | pisos del edificio |
apartmentsPerFloor | integer | 0 – 50 | |
dependencies | integer | 0 – 10 | |
yearsOld | integer | 0 – 300 | antigüedad, en años |
El número del tipo y el de la operación es el mismo en todos los países — lo que cambia de un país a otro es la etiqueta. Los tenés listados en Constantes.
zone3 no siempre existe, y por eso es opcional. Las zonas de Capital Federal —Recoleta,
Caballito, Palermo— tienen tres niveles: el barrio es el último. En esos casos mandá zone0,
zone1 y zone2, y dejá zone3 afuera. Lo vas a notar en el catálogo de zonas: el code viene
con tres segmentos en vez de cuatro.
Las dos superficies tienen pisos distintos, y es a propósito. landArea va de 1 en adelante
porque toda propiedad ocupa terreno; buildingArea admite 0, porque un lote no tiene
construcción y declararlo en cero es correcto.
Campos opcionales
| Campo | Tipo | Regla | |
|---|---|---|---|
zone3 | integer | — | localidad o barrio |
betweenStreets | string | — | |
occupancy | integer | 1 – 50 | |
sold | boolean | — | cerró como venta — ver la nota de abajo |
rented | boolean | — | cerró como alquiler — ver la nota de abajo |
reserved | boolean | — | reservada |
suspended | boolean | — | publicación suspendida |
descriptionFormatted | string | — | la descripción con sus saltos de línea; si no la mandás se usa description |
conditions | string | — | condiciones de la operación — "Contado", "Apto crédito"… |
urlWebExternal | string | — | la URL de la propiedad en tu propio sitio |
🔴 sold · rented · reserved · suspended: UN estado o ninguno, nunca dos — y sold/rented
tienen que ser coherentes con operation (una venta no cierra un aviso de alquiler).
Las dos reglas se rechazan en el verificador, con el detalle de qué corregir: los estados que viajan con la propiedad.
mapLatitude y mapLongitude son obligatorias, y van como número, no como texto. Están en la
tabla de arriba: si las omitís o las mandás en null, la propiedad no pasa la validación. Geocodificá
la dirección antes de postear.
Y el 0 no es "sin coordenada": es un punto real en el Golfo de Guinea, así que una propiedad con
0, 0 se publica ahí. La validación lo acepta —es un número válido— pero el aviso sale mal.
Cómo se dice "no tengo este dato"
Un campo opcional que no tenés se manda en null o no se manda: para nosotros es lo mismo.
Lo que no es lo mismo es mandar 0. Un 0 en una superficie, en la antigüedad, en la cantidad
de ocupantes o en una coordenada se guarda como el número cero — o sea, como un dato.
Un campo que no existe te lo decimos
Si mandás una clave que no está en este contrato, no entra a ninguna parte — y desde ahora te lo
reportamos en object.contract, en la respuesta del POST y del
verify:
{
"object": {
"contract": [
{ "field": "metrosCuadrados", "rule": "unknown", "value": 55,
"detail": "no existe en el contrato del objeto: se ignora y no se guarda" },
{ "field": "prices.abl", "rule": "unknown", "value": 300,
"detail": "no existe en el contrato: prices acepta expensesPrice, expensesCurrency, taxPrice, taxCurrency, paymentPeriod" }
]
}
}
Vale también adentro de los bloques (prices, altPrices, images, blueprint, videos), y
en una lista te decimos qué item: images[1].rotacion.
Es un reporte, no un rechazo: valid no cambia y la propiedad se guarda igual. Está para que
no mandes un campo durante meses creyendo que llega.
⚠️ Que una clave exista en el objeto de Mapaprop no la hace parte de este contrato. Si mandás
accessible, te lo vamos a reportar: el contrato de PropertyAPI es el que manda.
Los bloques tienen sus propias reglas
Los subcampos de cada bloque se validan igual que los campos de arriba: tipo, valores admitidos, mínimos.
| bloque | subcampo | regla |
|---|---|---|
prices | expensesPrice · taxPrice | entero, mínimo 0 |
prices | expensesCurrency · taxCurrency | USD o ARS — independientes de la moneda del precio |
prices | paymentPeriod | 1 = día · 2 = mes · 3 = año |
altPrices[] | price | entero, mínimo 1 |
altPrices[] | currency | USD o ARS |
images[] · blueprint | url | obligatoria |
videos[] | source | obligatoria |
La zona tiene que existir
zone1, zone2 y zone3 se validan contra el catálogo, y también su jerarquía: una zone2 que
existe pero cuelga de otra zone1 se rechaza igual que una inventada. Una zona que no existe deja la
propiedad fuera de toda búsqueda por ubicación, así que no la dejamos entrar.
Para no declarar un nivel, mandá 0 — es la misma convención del
código de 4 segmentos, donde el último segmento es 0 cuando no
hay tercer nivel. -1 y omitir la clave significan lo mismo.
No hace falta postear para enterarte. El
verificador busca la zona en el catálogo y te lo dice
antes, gratis: la vas a ver en object.contract como zone2 con rule: not_found, y el value
trae el código de 4 segmentos con el que buscarla.
De dónde salen los valores
Los campos enumerados —el tipo, la operación, el estado, las orientaciones, los amenities— no tienen una lista fija en esta página a propósito: dependen del país y cambian cuando se agrega uno nuevo.
Los pedís acá:
GET /property-attributes?country=AR
Ver la referencia completa del endpoint
Te devuelve, para ese país, todo lo que acepta: la clave en texto (pa_key), el valor que mandás
(pa_key_legacy), la etiqueta traducida (pa_label) y la familia (pa_group_subtype).
Pedí el catálogo del país de la propiedad, no de uno solo: un tipo puede estar habilitado en Argentina y no en Perú.
Y tenelo presente: no validamos los valores contra el catálogo. Un valor que ese país no usa no se rechaza: se guarda, y la propiedad queda publicada con un dato equivocado. El catálogo no es una sugerencia — es la única forma de saber qué mandar.
Verificá antes de publicar
Podés mandar tu objeto y ver qué produce, sin dar de alta nada:
POST /property-v1/properties/verify
Te dice si el objeto es válido, qué reglas incumple campo por campo, y qué pasaría en cada portal. Es el mismo cuerpo del alta, sin la escritura.
Tu token necesita el scope property-api-verify. Sin él, la respuesta es 403. Pedilo junto con
tus credenciales de acceso.
Ver también
- El modelo de propiedad — claves estables, catálogo por país, qué mandás vos y qué ponemos nosotros
- GET /property-attributes — el catálogo de valores
- POST /properties — el endpoint de alta