developmentStats — os números calculados do empreendimento

Quando o objeto é um empreendimento, a resposta traz um bloco developmentStats com os indicadores agregados das suas unidades: quantas existem e em que situação, quanto foi comercializado separando venda de locação, os m² disponíveis, o preço por moeda e a distribuição por tipologia.

São os mesmos números que mostramos no nosso painel de empreendimentos. Você não precisa percorrer as unidades nem calcular nada: vem resolvido, no verify, no POST, no PUT e no GET.

1. Não confundir com canonical.development

São dois blocos diferentes, e a diferença é de quem é cada um:

Por isso não está dentro de canonical: ali vai apenas o seu objeto, verbatim.

2. O bloco completo

{
  "units": {
    "total": 4,
    "available": 1,
    "sold": 1,
    "rented": 1,
    "reserved": 1,
    "suspended": 0,
    "withOperation": 3,
    "availabilityRate": 25
  },
  "sale":  { "units": 3, "commercialized": 2, "rate": 67 },
  "rent":  { "units": 1, "commercialized": 1, "rate": 100 },
  "otherOperation": { "units": 0 },
  "buildingArea": {
    "unit": "m2",
    "total": 220,
    "available": 62,
    "unavailable": 158,
    "sold": 48,
    "rented": 48,
    "reserved": 62
  },
  "prices": {
    "mixedCurrencies": true,
    "byCurrency": {
      "USD": { "units": 3, "from": 85000, "to": 120000, "total": 325000 },
      "ARS": { "units": 1, "from": 450000, "to": 450000, "total": 450000 }
    }
  },
  "typology": {
    "byAmbiences":    { "2": 2, "3": 2 },
    "byRooms":        { "1": 2, "2": 2 },
    "byBuildingArea": { "48": 2, "62": 2 },
    "byLandArea":     { "70": 4 }
  }
}

Os nomes são os mesmos que você envia: os seus m² cobertos são buildingArea, os seus dormitórios são rooms, os seus m² totais são landArea. Não há um vocabulário novo para aprender.

3. units — quantas e em que situação

withOperation conta unidades, não situações: uma unidade vendida e reservada conta uma. Por isso available + withOperation sempre dá total, e as disponíveis nunca ficam negativas.

4. 🔴 sale e rent — venda e locação são medidas SEPARADAMENTE

É a parte que mais vale a pena entender, porque é onde uma média única mente.

Venda e locação são negócios diferentes e não se misturam em uma média. Cada um é medido contra o seu próprio universo, e o evento que conta como comercializada é diferente:

No exemplo acima, a locação está colocada em 100 % e a venda em 67 %. Uma média única diria "75 %" e não diria nada sobre nenhum dos dois negócios.

rate: null não é 0

Um empreendimento só de locação devolve "sale": { "units": 0, "commercialized": 0, "rate": null } — e não 0 % de vendas que não existem.

otherOperation

As unidades em permuta, trespasse, compartilhamento ou leilão não entram em nenhuma das duas taxas: não são venda nem locação. São contadas à parte para que sale.units + rent.units + otherOperation.units dê sempre o total e nenhuma unidade desapareça.

5. buildingArea — os metros quadrados cobertos

unavailable é um ou, não uma soma: os m² de uma unidade vendida e reservada são descontados uma vez. Por isso sold + rented + reserved pode dar mais que unavailable, e available nunca fica negativo.

6. 🔴 prices — sempre por moeda

Um empreendimento pode ter unidades em moedas diferentes, e isso é normal. Por isso o preço é sempre devolvido detalhado:

Não devolvemos um total que cruze moedas. Uma faixa que mistura dólares com pesos não é um dado degradado: é um dado falso. Se você quiser um total único, converta com a cotação que usar — essa é uma decisão sua, não nossa.

⚠️ Uma unidade com preço mas sem moeda declarada não entra no detalhamento: não inventamos uma para ela.

7. typology — a distribuição das unidades

Quantas unidades há de cada configuração. São mapas: a chave é o valor e o valor é quantas unidades.

"byAmbiences": { "2": 18, "3": 22 } lê-se: 18 unidades de 2 ambientes e 22 de 3.

Não têm teto: se você tiver unidades de 9 ambientes, aparece a chave "9". E uma configuração que nenhuma unidade tem não aparece — não volta como 0.

Lembre do cruzamento de nomes do nosso modelo, o mesmo que em um imóvel avulso: ambiences são os ambientes e rooms são os dormitórios.

8. Um empreendimento sem unidades

O bloco vem igual, com os contadores em zero, os mapas vazios e as duas taxas em null. Não é o mesmo que ausente: está dizendo que o empreendimento existe e ainda não tem unidades carregadas, o que é um estado normal.

O bloco não aparece quando o objeto não é um empreendimento.

9. E depois

O objeto JSON do empreendimento — como se declara, e as regras das unidades

Verificar e cadastrar um empreendimento — o fluxo e o que validamos

GET /properties — consultar um empreendimento já carregado