O objeto JSON da propriedade
Esta é a referência de o que você envia: quais campos tem o objeto propriedade, quais são obrigatórios, quais valores aceita cada um e como se diz "não tenho esse dado".
É uma referência do objeto, não de um endpoint. Para entender como se identifica uma propriedade —por que o tipo e a operação são chaves estáveis e de onde saem seus valores— leia primeiro O modelo de propriedade.
O objeto que você envia
Este é o objeto completo. Abaixo está o que é obrigatório, o que é opcional e quais valores aceita 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
},
// … e mais 42 entradas, uma por atributo do imóvel
],
"publication": { … } // configuração de publicação por portal — veja sua própria página
}
As fotos, a planta, os vídeos e os preços acessórios
Vão no mesmo JSON: você envia um único objeto.
| Bloque | Forma | Nota |
|---|---|---|
images | lista de {url, description, main} | a URL, não o arquivo: o binário não viaja em um JSON |
blueprint | {url} | apenas um por propriedade |
videos | lista de {source, description} | source é a URL do YouTube ou Matterport |
prices | {expensesCurrency, expensesPrice, taxCurrency, taxPrice, paymentPeriod} | despesas e impostos, valores como número |
altPrices | lista de {description, currency, price} | preços alternativos |
⚠️ O price e a currency da propriedade não vão aqui: são campos do imóvel e já estão mais
acima.
Os cinco blocos são registrados na mesma chamada. Você manda o objeto uma vez e as fotos, a planta, os vídeos, as expensas e os preços alternativos são guardados com a propriedade — não há uma segunda chamada por acessório.
E aqui a regra acima tem uma consequência útil: como o price não vai dentro de prices,
registrar as expensas não pode mudar o preço da propriedade.
O array attributes
Cada entrada descreve um dado. Há duas famílias: o estado da propriedade
(propertyStatus) e os atributos — amenidades, orientação, tipo de calefação e demais
(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
}
]
O valor que você envia é key_legacy: é o mesmo em todos os países. O id, o label e o
value saem do catálogo do seu país — de onde obtê-los está mais abaixo.
attributes é obrigatório, e uma lista vazia é válida. Se a propriedade não tem nenhum
atributo, envie "attributes": []; o que não se pode é omitir a chave.
O bag é verificado contra o catálogo
Cada entrada é buscada no catálogo do país da propriedade, e o que não bate sai em
object.contract do verificador:
| O quê | O que dizemos | Invalida o objeto? |
|---|---|---|
o id não existe nesse país | rule: unknown — é ignorado, a propriedade é guardada do mesmo jeito | não |
o key_legacy não é o do catálogo | rule: attribute_value, com o que corresponde | sim |
um atributo bool com um selected que não é booleano | rule: attribute_value | sim |
O catálogo não é o mesmo nos 15 países. Os conjuntos de chaves são subconjuntos uns dos outros: o que existe na Argentina pode não existir no Paraguai ou no Brasil. Peça o catálogo com o país da propriedade, não com um qualquer — é a causa mais comum de um atributo que não é publicado.
Um id inventado não quebra o cadastro: é ignorado. Mas essa característica não viaja para
nenhum portal, e isso não se nota olhando a propriedade — por isso é reportado.
customerSource — de onde saiu o cliente
Toda resposta que traz o bloco customer traz também, na raiz, de onde saiu:
| Valor | O que significa |
|---|---|
account | É sua ficha, a lemos com seu clientRef. É o normal |
placeholder | Você não declarou ficha e isto é preenchimento. Só acontece em /verify — o cadastro sem ficha responde 400, não preenche. Se resolve com POST /customers |
frozen | O snapshot com o qual essa propriedade foi cadastrada (o GET e o PUT o devolvem). Não é sua ficha de hoje, e é deliberado: assim o GET diz com quais dados essa propriedade foi publicada |
Está na raiz e não dentro de customer de propósito: ali se misturaria com os campos que
você declarou.
O cliente NÃO é parte deste objeto
O cliente se declara uma vez, separadamente, e suas propriedades o herdam.
👉 Clientes — o POST /property-v1/customers,
seus campos, o customerId que devolvemos e a filial.
⚠️ Se você enviar customer dentro deste objeto, é ignorado — assim como propertyId, customerId e
branchId. E sem cliente declarado, o cadastro responde 400 com rule: account_required.
publication — como se publica
Dentro do mesmo objeto viaja uma chave publication com o que cada portal precisa da sua conta e
das suas escolhas de publicação. Não é um campo do imóvel: é como você o publica.
{
"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>"
}
}
}
}
A referência completa está em A chave publication.
Campos obrigatórios
São 26, mais o array attributes. Todo o resto é opcional.
A maioria são campos isolados:
| Campo | Tipo | Regra | |
|---|---|---|---|
code | string | ^[A-Za-z0-9._-]{1,30}$ | |
title | string | 1–150 caracteres | |
description | string | pelo menos 1 caractere | |
price | integer | 1 ou mais | |
currency | string | USD ou ARS | |
type | integer | — | o id do tipo — pa_key_legacy do grupo type do catálogo |
operation | integer | — | o id da operação — pa_key_legacy do grupo operation |
zone0 | integer | um dos 15 países | país. A lista vem do catálogo: se o seu não estiver, não conseguimos resolver nem o tipo nem a operação |
zone1 | integer | — | província/estado |
zone2 | integer | — | município ou departamento |
address | string | pelo menos 1 caractere | |
zipcode | string | ^[A-Za-z0-9-]{1,10}$ | |
mapLatitude | number | -90 – 90 | veja o aviso abaixo |
mapLongitude | number | -180 – 180 | veja o aviso abaixo |
buildingArea | integer | 0 – 100.000 | superfície construída, em m² |
landArea | integer | 1 – 10.000.000 | superfície TOTAL da propriedade, em m² — também em um apartamento |
ambiences | integer | 0 – 50 | os ambientes |
rooms | integer | 0 – 50 | ⚠️ são dormitórios, não ambientes |
bathrooms | integer | 0 – 50 | |
toilettes | integer | 0 – 10 | |
garage | integer | 0 – 100 | |
floors | integer | 0 – 10 | andares da unidade |
totalFloors | integer | 0 – 200 | andares do edifício |
apartmentsPerFloor | integer | 0 – 50 | |
dependencies | integer | 0 – 10 | |
yearsOld | integer | 0 – 300 | idade, em anos |
O número do tipo e o da operação é o mesmo em todos os países — o que muda de um país para outro é o rótulo. Você os tem listados em Constantes.
zone3 nem sempre existe, e por isso é opcional. As zonas da Capital Federal —Recoleta,
Caballito, Palermo— têm três níveis: o bairro é o último. Nesses casos envie zone0,
zone1 e zone2, e deixe zone3 de fora. Você vai notar isso no catálogo de zonas: o code vem
com três segmentos em vez de quatro.
As duas superfícies têm pisos distintos, e é de propósito. landArea vai de 1 em diante
porque toda propriedade ocupa terreno; buildingArea admite 0, porque um lote não tem
construção e declará-lo em zero é correto.
Campos opcionais
| Campo | Tipo | Regra | |
|---|---|---|---|
zone3 | integer | — | localidade ou bairro |
betweenStreets | string | — | |
occupancy | integer | 1 – 50 | |
sold | boolean | — | fechou como venda — veja a nota abaixo |
rented | boolean | — | fechou como aluguel — veja a nota abaixo |
reserved | boolean | — | reservada |
suspended | boolean | — | publicação suspensa |
descriptionFormatted | string | — | a descrição com suas quebras de linha; se você não a enviar, usa-se description |
conditions | string | — | condições da operação — "À vista", "Aceita financiamento"… |
urlWebExternal | string | — | a URL da propriedade no seu próprio site |
🔴 sold · rented · reserved · suspended: UM estado ou nenhum, nunca dois — e sold/rented
precisam ser coerentes com operation (uma venda não fecha um anúncio de aluguel).
As duas regras são rejeitadas pelo verificador, com o detalhe do que corrigir: os estados que viajam com a propriedade.
mapLatitude e mapLongitude são obrigatórias, e vão como número, não como texto. Estão na
tabela acima: se você as omitir ou enviá-las em null, a propriedade não passa a validação. Geocodifique
o endereço antes de postar.
E o 0 não é "sem coordenada": é um ponto real no Golfo da Guiné, então uma propriedade com
0, 0 é publicada ali. A validação o aceita —é um número válido— mas o anúncio sai errado.
Como se diz "não tenho este dado"
Um campo opcional que você não tem se envia em null ou não se envia: para nós é o mesmo.
O que não é o mesmo é enviar 0. Um 0 em uma superfície, na idade, na quantidade
de ocupantes ou em uma coordenada se guarda como o número zero — ou seja, como um dado.
Um campo que não existe nós avisamos
Se você enviar uma chave que não está neste contrato, ela não entra em lugar nenhum — e a partir
de agora nós a reportamos em object.contract, na resposta do POST e do
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 também dentro dos blocos (prices, altPrices, images, blueprint, videos), e numa
lista dizemos qual item: images[1].rotacion.
É um relatório, não uma recusa: valid não muda e a propriedade é guardada do mesmo jeito.
Existe para que você não envie um campo durante meses acreditando que ele chega.
⚠️ Uma chave existir no objeto do Mapaprop não a torna parte deste contrato. Se você enviar
accessible, vamos reportar: o contrato do PropertyAPI é o que manda.
Os blocos têm regras próprias
Os subcampos de cada bloco são validados igual aos campos acima: tipo, valores admitidos, mínimos.
| bloco | subcampo | regra |
|---|---|---|
prices | expensesPrice · taxPrice | inteiro, mínimo 0 |
prices | expensesCurrency · taxCurrency | USD ou ARS — independentes da moeda do preço |
prices | paymentPeriod | 1 = dia · 2 = mês · 3 = ano |
altPrices[] | price | inteiro, mínimo 1 |
altPrices[] | currency | USD ou ARS |
images[] · blueprint | url | obrigatória |
videos[] | source | obrigatória |
A zona tem que existir
zone1, zone2 e zone3 são validadas contra o catálogo, e também a hierarquia: uma zone2
que existe mas pertence a outra zone1 é recusada igual a uma inventada. Uma zona que não existe
deixa a propriedade fora de qualquer busca por localização, então não deixamos entrar.
Para não declarar um nível, envie 0 — é a mesma convenção do
código de 4 segmentos, onde o último segmento é 0 quando não
há terceiro nível. -1 e omitir a chave significam o mesmo.
Não é preciso postar para descobrir. O verificador
busca a zona no catálogo e avisa antes, de graça: você vai vê-la em object.contract como zone2
com rule: not_found, e o value traz o código de 4 segmentos com que procurá-la.
De onde saem os valores
Os campos enumerados —o tipo, a operação, o estado, as orientações, as amenidades— não têm uma lista fixa nesta página de propósito: dependem do país e mudam quando se adiciona um novo.
Você os pede aqui:
GET /property-attributes?country=AR
Veja a referência completa do endpoint
Devolve, para esse país, tudo o que aceita: a chave em texto (pa_key), o valor que você envia
(pa_key_legacy), o rótulo traduzido (pa_label) e a família (pa_group_subtype).
Peça o catálogo do país da propriedade, não de um só: um tipo pode estar habilitado na Argentina e não no Peru.
E tenha isso em mente: não validamos os valores contra o catálogo. Um valor que esse país não usa não é rejeitado: é guardado, e a propriedade fica publicada com um dado errado. O catálogo não é uma sugestão — é a única forma de saber o que enviar.
Verifique antes de publicar
Você pode enviar seu objeto e ver o que produz, sem cadastrar nada:
POST /property-v1/properties/verify
Diz se o objeto é válido, quais regras descumpre campo a campo, e o que aconteceria em cada portal. É o mesmo corpo do cadastro, sem a escrita.
Seu token precisa do scope property-api-verify. Sem ele, a resposta é 403. Peça-o junto com
suas credenciais de acesso.
Veja também
- O modelo de propriedade — chaves estáveis, catálogo por país, o que você envia e o que colocamos nós
- GET /property-attributes — o catálogo de valores
- POST /properties — o endpoint de cadastro