BETA

O objeto JSON do empreendimento

Um empreendimento imobiliário —um prédio na planta, um condomínio fechado, uma torre em construção— é enviado com o mesmo endpoint que um imóvel: POST /property-v1/properties. Não há um endpoint à parte nem um modelo novo para aprender.

O que o torna um empreendimento é um grupo development dentro do objeto:

{
  "code": "TORRE-NORTE",
  "type": 23,
  "operation": 1,
  "title": "Torre Norte — Empreendimento na planta",
  // … o resto dos campos de sempre …

  "development": {
    "totalBuildingArea": 7400,
    "totalFloors": 12,
    "apartmentsPerFloor": 4,
    "units": ["TORRE-NORTE-4B", "TORRE-NORTE-5A"]
  }
}

Duas regras que convém ter claras desde o começo:

O type precisa ser 23É "Empreendimento Imobiliário" no nosso catálogo de tipos. Enviar o grupo com outro tipo é um erro de contrato, e nós avisamos: não adivinhamos qual dos dois você quis dizer
A presença do grupo É o sinalNão é preciso nenhuma flag. Um development vazio ({}) já declara que o objeto é um empreendimento

1. Os campos do grupo development

Todos descrevem o projeto, não uma unidade.

CampoO que éObrigatório
totalBuildingAreaM² cobertos do empreendimentosim
totalLandAreaM² totais do terrenosim
totalGaragesVagas de garagem do empreendimentosim
minAmbiencesAmbientes a partir de — o mínimo entre as unidadessim
minRoomsDormitórios a partir desim
minBathroomsBanheiros completos a partir desim
unitsAs unidades. Ver a seção 2não
totalApartmentsQuantidade de apartamentosnão
totalFloorsAndares do prédionão
apartmentsPerFloorApartamentos por andarnão
totalElevatorsQuantidade de elevadoresnão
totalOfficesQuantidade de salas comerciaisnão
totalCommercialUnitsQuantidade de lojasnão
totalTowersQuantidade de torresnão
totalHousesQuantidade de casas. Para um condomínio fechadonão
totalLotsQuantidade de lotes. Para um condomínio fechadonão
deliveryDateData de entreganão
logoUrlLogotipo do empreendimentonão
commercialTaglineSlogan comercialnão

Os total* são do conjunto; os min* são o "a partir de" que o anúncio mostra.

Se faltar um obrigatório, o erro o nomeia pelo seu caminho no seu JSON (development.minRooms): algo que você pode procurar literalmente no que enviou.

totalHouses / totalLots e os campos de prédio não convivem. Um condomínio fechado é descrito com casas e lotes; um prédio com andares, apartamentos por andar e elevadores. Se você enviar dos dois lados devolvemos o conflito nomeando os campos de cada um, para que você deixe só os de um.

2. As unidades: units

As unidades são imóveis normais do seu mesmo cliente, que você já cadastrou. No empreendimento você apenas as referencia:

"units": ["TORRE-NORTE-4B", "TORRE-NORTE-5A", "01M43Y1T192XEXJCV6Y6C4QTNB"]

Você pode usar o code que você deu a elas ou o paId que devolvemos ao cadastrá-las. Os dois valem, e na resposta devolvemos os dois para que você possa cruzá-los com a sua base.

A ordem importa: primeiro as unidades, depois o empreendimento

Uma unidade precisa existir antes de você referenciá-la. O fluxo é:

  1. POST /properties de cada unidade guarde o paId
  2. POST /properties do empreendimento, com os códigos delas em units

Um empreendimento pode nascer sem unidades — mas não se publica assim

units é opcional para o cadastro. Você pode cadastrar o empreendimento vazio e carregar as unidades depois com PUT: é o fluxo normal quando o projeto entra no sistema antes de a tipologia estar fechada.

Para publicá-lo é preciso ao menos uma unidade. Não é uma regra nossa: é do portal, e ele a diz com estas palavras — "o empreendimento só será publicado se tiver pelo menos uma unidade". Um empreendimento vazio é salvo, consultado e editado sem problema; quando você mandar publicá-lo nós recusamos informando o motivo, antes de chamar o portal e sem gastar nenhuma chamada da cota.

O PUT substitui a lista completa, não acrescenta. Se o empreendimento tem 10 unidades e você envia um PUT com 3, ele fica com 3 — as outras 7 são liberadas. Envie sempre a lista inteira.

O limite: 100 unidades que MUDAM, não que ele tem

Uma única operação pode movimentar até 100 unidades. O que conta são as que entram e saem, não as que o empreendimento já tem: uma unidade que já era dele e continua sendo não custa nada.

Por isso "envie sempre a lista inteira" e o limite convivem. Com um empreendimento de 150:

Você fazMovimenta
PUT com as mesmas 1500
PUT com 150, das quais 1 é nova1
PUT com 149 (você tira uma)1
POST de cadastro com as 150 de uma vez150400 too_many_units_in_one_operation

O único caso que não passa é carregar mais de ~92 unidades novas de uma só vez. Resolve-se em duas etapas e depois não incomoda mais:

POST /properties    o empreendimento com as primeiras 90
PUT  /properties/{paId}  a lista das 150

A partir daí você pode fazer PUT das 150 quantas vezes quiser: nenhuma se movimenta.

As sete regras de uma unidade

Uma unidade que não cumprir uma destas é reportada a você com o seu motivo, e o empreendimento é salvo mesmo assim: o que não dá é publicá-lo.

Se…Nós dizemos
o código não existe, ou o imóvel está excluídonot_found
você enviou o mesmo código duas vezes na mesma listaduplicate
a string pode ser um code e um paId de dois imóveis diferentesambiguous — desambigue com o paId
a unidade já é unidade de outro empreendimentoalready_in_development
você colocou o empreendimento como unidade dele mesmoself_reference
a unidade contém o empreendimento (direta ou indiretamente)cycle
a cadeia de empreendimentos é profunda demais para verificarunverifiable_depth

Uma unidade pertence a um único empreendimento. Se quiser movê-la, tire-a antes do anterior.

Um empreendimento pode ser unidade de outro (um condomínio com torres dentro). Nesse caso conta como uma unidade: não descemos até as unidades dos seus filhos, porque somar o filho e as unidades dele contaria duas vezes a mesma coisa.

3. Amenidades próprias do empreendimento

Um empreendimento usa o mesmo attributes que qualquer imóvel e, além disso, tem 16 amenidades próprias: as do empreendimento, não as de uma unidade. Uma academia ou um campo de golfe são do complexo; o ar-condicionado é do apartamento.

Elas vêm no catálogo com group_subtype: "development":

clubhouse Salão de festasgym Academiaspa Spa
golf-course Campo de golfesports-court Quadra esportivasauna Sauna
equestrian Equitaçãosports-school Escola esportivasolarium Solário
playground Playgroundmicro-cinema Sala de cinemarestaurant Restaurante
medical-center Centro médicoschool Escolacommercial-area Área comercial
maid-service Serviço de camareira

São booleanos e são enviadas em attributes igual ao resto, sem nada de especial:

"attributes": [
  { "id": "gym",        "key_legacy": "gym",        "group_sub": "label", "group_subtype": "development", "selected": true },
  { "id": "clubhouse",  "key_legacy": "clubhouse",  "group_sub": "label", "group_subtype": "development", "selected": true }
]

Estão nos 15 países. Baixe-as do catálogo junto com o resto —não as escreva à mão— e filtre por group_subtype:

GET /property-attributes — o catálogo completo: tipos, operações, estados e amenidades

4. Se você publica no Zonaprop: diga se é horizontal ou vertical

O Zonaprop distingue duas classes de empreendimento e precisa saber qual é — não podemos escolher por você, porque é disso que depende quais dados ele aceita para esse anúncio.

horizontalum condomínio fechado, um country, lotes, casas
verticalum edifício

Declara-se na configuração do Zonaprop, dentro do mesmo objeto:

  "publication": {
 "api": {
   "zonaprop": {
     "developmentCategory": "vertical",
     "plan": { "plan": "DESARROLLOS_HOME" },
     "token": "<seu-token-do-zonaprop>"
   }
 }
  }

O código do plano não é fixo: sai dos planos que o seu cliente tem contratados. Um empreendimento precisa de um plano de empreendimentos (os de anúncios avulsos não servem), e cada imobiliária tem os seus. DESARROLLOS_HOME é um exemplo real, não o valor a copiar: se você enviar um plano que essa conta não tem, o portal recusa, e no erro informamos quais ela tem disponíveis.

Quando NÃO é necessário enviar

Se os seus próprios campos já dizem, nós deduzimos. Há campos que só existem em uma das duas classes:

Se você declara…Entendemos como
totalHouses ou totalLotshorizontal
totalFloors, apartmentsPerFloor, totalElevators, totalOffices, totalCommercialUnitsvertical

totalGarages não conta para isso, mesmo sendo obrigatório: um condomínio fechado também tem vagas de garagem, então não distingue nada.

Quando É necessário, e o que dizemos se faltar

Pedimos a você em dois casos, e nos dois a mensagem nomeia o campo:

CasoO que acontece
Seus campos não dizem de que classe é (por exemplo, você envia apenas os obrigatórios)pedimos o developmentCategory
Seus campos dizem as duas coisas (casas e andares de edifício)dizemos quais estão em conflito, e que você pode resolver declarando a categoria

Não escolhemos por você. Se escolhêssemos errado, o anúncio seria publicado e o Zonaprop descartaria em silêncio os dados que não correspondem a essa classe — um problema que você não veria até olhar o anúncio.

O que você declara sempre ganha, mesmo sobre o que os seus campos digam. Se algum deles não corresponder à classe escolhida, o Zonaprop não o aceita e nós o devolvemos em omitted.

Isto se aplica somente ao Zonaprop. Argenprop e MercadoLibre não pedem essa distinção.

5. O objeto completo

Este é um empreendimento inteiro, com todos os seus campos. É o objeto que usamos para testar.

{
  "code": "DEV-TORRE-NORTE",
  "type": 23,
  "development": {
    "totalBuildingArea": 126,
    "totalLandArea": 189,
    "totalGarages": 2,
    "minAmbiences": 2,
    "minRooms": 3,
    "minBathrooms": 1,
    "units": [
      "TORRE-NORTE-4B",
      "TORRE-NORTE-5A",
      "TORRE-NORTE-PH-A"
    ],
    "totalFloors": 12,
    "apartmentsPerFloor": 4,
    "totalApartments": 96,
    "totalTowers": 3,
    "totalElevators": 4,
    "totalOffices": 2,
    "totalCommercialUnits": 3,
    "deliveryDate": "2027-06-30",
    "logoUrl": "https://cdn.inmobiliaria-modelo.com/torre-norte/logo.png",
    "commercialTagline": "Torre Norte — 96 unidades frente al parque, entrega 2027"
  },
  "operation": 1,
  "title": "Torre Norte — desarrollo de 48 unidades en Nordelta",
  "address": "Av. de los Lagos 7000, Nordelta",
  "mapLatitude": -34.4036,
  "mapLongitude": -58.648,
  "zone0": 1,
  "zone1": 2,
  "zone2": 259,
  "description": "Desarrollo de 48 unidades distribuidas en 12 pisos, con amenities completos. Unidades de 1, 2 y 3 ambientes.",
  "descriptionFormatted": "<p>Desarrollo de 48 unidades distribuidas en 12 pisos, con amenities completos.</p>",
  "zipcode": "1670",
  "betweenStreets": "Entre Av. Pueyrredón y Av. Coronel Díaz",
  "urlWebExternal": "https://ejemplo-inmobiliaria.com/propiedad-dev",
  "conditions": "Contado",
  "yearsOld": 16,
  "floors": 2,
  "dependencies": 1,
  "toilettes": 2,
  "currency": "USD",
  "price": 120000,
  "zone3": 151,
  "rented": false,
  "sold": false,
  "reserved": false,
  "suspended": false,
  "occupancy": null,
  "images": [
    {
      "url": "https://images.mapaprop.app/photos/1/33616/213831.jpg",
      "description": "Imagen principal",
      "main": true
    },
    {
      "url": "https://images.mapaprop.app/photos/1/33616/1950514.jpg",
      "description": "Imagen 2",
      "main": false
    },
    {
      "url": "https://images.mapaprop.app/photos/1/33616/1950515.jpg",
      "description": "Imagen 3",
      "main": false
    }
  ],
  "blueprint": {
    "url": "https://images.mapaprop.app/photos/1/33616/1950516.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
    }
  ],
  "publication": {
    "api": {
      "argenprop": {
        "visible": true,
        "token": "<tu-token-de-argenprop>"
      },
      "zonaprop": {
        "plan": {
          "plan": "DESARROLLOS_DESTACADO"
        },
        "developmentCategory": "vertical",
        "token": "<tu-token-de-zonaprop>"
      },
      "cabaprop": {
        "token": "<tu-token-de-cabaprop>"
      },
      "mercadolibre": {
        "listingTypeId": "gold_special",
        "condition": "used",
        "token": "<tu-token-de-mercadolibre>"
      }
    }
  },
  "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": "statusUnderConstruction",
      "label": "En Construcción",
      "group": "propertyStatus",
      "group_sub": "status",
      "type": "list",
      "key_legacy": "6",
      "value": 6
    },
    // … e mais 54 entradas, uma por atributo do empreendimento
  ]
}

6. E depois

POST /properties/verify para um empreendimento — teste o objeto antes de cadastrar qualquer coisa

developmentStats — os números calculados das suas unidades

O objeto JSON do imóvel — os campos de sempre, que um empreendimento também leva