BETA

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.

BloqueFormaNota
imageslista 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
videoslista de {source, description}source é a URL do YouTube ou Matterport
prices{expensesCurrency, expensesPrice, taxCurrency, taxPrice, paymentPeriod}despesas e impostos, valores como número
altPriceslista 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.

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 dizemosInvalida o objeto?
o id não existe nesse paísrule: unknown — é ignorado, a propriedade é guardada do mesmo jeitonão
o key_legacy não é o do catálogorule: attribute_value, com o que correspondesim
um atributo bool com um selected que não é booleanorule: attribute_valuesim

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:

ValorO que significa
accountÉ sua ficha, a lemos com seu clientRef. É o normal
placeholderVocê 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
frozenO 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:

CampoTipoRegra
codestring^[A-Za-z0-9._-]{1,30}$
titlestring1–150 caracteres
descriptionstringpelo menos 1 caractere
priceinteger1 ou mais
currencystringUSD ou ARS
typeinteger—o id do tipo — pa_key_legacy do grupo type do catálogo
operationinteger—o id da operação — pa_key_legacy do grupo operation
zone0integerum dos 15 paísespaís. A lista vem do catálogo: se o seu não estiver, não conseguimos resolver nem o tipo nem a operação
zone1integer—província/estado
zone2integer—município ou departamento
addressstringpelo menos 1 caractere
zipcodestring^[A-Za-z0-9-]{1,10}$
mapLatitudenumber-90 – 90veja o aviso abaixo
mapLongitudenumber-180 – 180veja o aviso abaixo
buildingAreainteger0 – 100.000superfície construída, em m²
landAreainteger1 – 10.000.000superfície TOTAL da propriedade, em m² — também em um apartamento
ambiencesinteger0 – 50os ambientes
roomsinteger0 – 50⚠️ são dormitórios, não ambientes
bathroomsinteger0 – 50
toilettesinteger0 – 10
garageinteger0 – 100
floorsinteger0 – 10andares da unidade
totalFloorsinteger0 – 200andares do edifício
apartmentsPerFloorinteger0 – 50
dependenciesinteger0 – 10
yearsOldinteger0 – 300idade, 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

CampoTipoRegra
zone3integer—localidade ou bairro
betweenStreetsstring—
occupancyinteger1 – 50
soldboolean—fechou como venda — veja a nota abaixo
rentedboolean—fechou como aluguel — veja a nota abaixo
reservedboolean—reservada
suspendedboolean—publicação suspensa
descriptionFormattedstring—a descrição com suas quebras de linha; se você não a enviar, usa-se description
conditionsstring—condições da operação — "À vista", "Aceita financiamento"…
urlWebExternalstring—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.

blocosubcamporegra
pricesexpensesPrice · taxPriceinteiro, mínimo 0
pricesexpensesCurrency · taxCurrencyUSD ou ARS — independentes da moeda do preço
pricespaymentPeriod1 = dia · 2 = mês · 3 = ano
altPrices[]priceinteiro, mínimo 1
altPrices[]currencyUSD ou ARS
images[] · blueprinturlobrigatória
videos[]sourceobrigató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