Imóveis (Properties)

Esta seção documenta os endpoints para gerenciamento de imóveis e suas propriedades físicas.

📖 Visão Geral

O sistema separa Imóvel (Property) de Anúncio (Listing):

Property - Representa o imóvel físico (características, localização, mídia)
Listing - Representa a oferta comercial (preço, tipo de transação, visibilidade)

Um imóvel pode ter múltiplos anúncios (ex: venda e aluguel simultaneamente).

Em revenda, as características (quartos, área) ficam no Property. Em lançamento (mercado primário), elas vivem na Tipologia do empreendimento; o anúncio referencia typologyId e isPrimaryMarket: "true". Nesse caso, property.totalArea pode ser um placeholder — a área real vem da tipologia. totalArea no imóvel é obrigatório apenas quando isPrimaryMarket é false.

Leitura pública de tipologias, unidades e empreendimento: Sites API — Mercado primário. Campos no REST de anúncios: Anúncios — Mercado primário.

┌─────────────────────────────────────────┐
│         Building (empreendimento)        │  ← mercado primário
│  - Construtora, entrega, torres          │
└─────────────────────────────────────────┘
           │
           ▼
┌─────────────────────────────────────────┐
│              Typology                    │
│  - Quartos, área, preço base, estoque    │
└─────────────────────────────────────────┘
           │
     ┌─────┴─────┐
     ▼           ▼
┌─────────┐  ┌─────────────────────────────┐
│  Unit   │  │         Property             │
│ (stock) │  │  (revenda: características;  │
└─────────┘  │   lançamento: pode ser mínimo)│
             └─────────────────────────────┘
                       │
                       │ 1:N
                       ▼
             ┌─────────────────────────────┐
             │           Listings             │
             │  isPrimaryMarket, typologyId   │
             └─────────────────────────────┘

📊 Endpoints

Buscar Imóvel por ID

GET /api/v1/real-estate/properties/{id}

Exemplo:

curl -X GET "https://app.garagem.ai/api/v1/real-estate/properties/uuid-do-imovel" \
  -H "Authorization: Bearer sua_api_key"

Resposta:

{
  "id": "uuid-do-imovel",
  "title": "Apartamento 2 quartos - Copacabana",
  "type": "apartment",
  "bedrooms": 2,
  "bathrooms": 1,
  "suites": 0,
  "parkingSpaces": 1,
  "totalArea": "75.00",
  "usableArea": "65.00",
  "location": {
    "address": "Rua Example, 123",
    "neighborhood": "Copacabana",
    "city": "Rio de Janeiro",
    "state": "RJ",
    "zipCode": "22020-000",
    "latitude": -22.970722,
    "longitude": -43.182365
  },
  "features": ["ar_condicionado", "churrasqueira", "piscina"],
  "listings": [
    {
      "id": "uuid-do-listing",
      "type": "rental",
      "price": "3500.00",
      "visibility": "public",
      "stage": "active"
    }
  ],
  "medias": [
    {
      "id": "uuid-da-midia",
      "src": "https://cdn.example.com/image.jpg",
      "type": "image",
      "category": "Sala",
      "isPrimary": true
    }
  ],
  "createdAt": "2024-01-15T10:30:00Z"
}

Criar Imóvel com Anúncios

POST /api/v1/real-estate/properties

Body Básico:

{
  "property": {
    "title": "Apartamento 2 quartos - Copacabana",
    "type": "apartment",
    "bedrooms": 2,
    "bathrooms": 1,
    "totalArea": "75"
  },
  "location": {
    "neighborhood": "Copacabana",
    "city": "Rio de Janeiro",
    "state": "RJ"
  },
  "listings": [
    {
      "title": "Apartamento para alugar",
      "type": "rental",
      "price": "3500.00",
      "currency": "BRL",
      "stage": "active",
      "visibility": "public"
    }
  ]
}

Exemplo Completo:

curl -X POST https://app.garagem.ai/api/v1/real-estate/properties \
  -H "Authorization: Bearer sua_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "property": {
      "title": "Apartamento 2 quartos reformado - Copacabana",
      "type": "apartment",
      "bedrooms": 2,
      "bathrooms": 1,
      "suites": 1,
      "parkingSpaces": 1,
      "totalArea": "75",
      "usableArea": "65",
      "features": ["ar_condicionado", "armarios_embutidos", "varanda"]
    },
    "location": {
      "address": "Rua Example, 123",
      "complement": "Apto 501",
      "neighborhood": "Copacabana",
      "city": "Rio de Janeiro",
      "state": "RJ",
      "zipCode": "22020-000",
      "latitude": -22.970722,
      "longitude": -43.182365
    },
    "listings": [
      {
        "title": "Apartamento 2 quartos para alugar - Copacabana",
        "description": "Excelente apartamento reformado com vista para o mar...",
        "type": "rental",
        "price": "3500.00",
        "currency": "BRL",
        "stage": "active",
        "visibility": "public",
        "priceVisibility": "public",
        "typeSpecificData": {
          "deposit": 7000,
          "condominiumFee": 500,
          "iptu": 200
        },
        "acceptanceCriteria": {
          "minIncome": 10500,
          "petAllowed": true,
          "requiresGuarantor": true
        }
      },
      {
        "title": "Apartamento 2 quartos à venda - Copacabana",
        "type": "sale",
        "price": "450000.00",
        "currency": "BRL",
        "stage": "active",
        "visibility": "public",
        "typeSpecificData": {
          "financingAllowed": true,
          "condominiumFee": 500,
          "iptu": 200
        }
      }
    ]
  }'

Traduções de título/descrição (en / es) em listings[].translations — veja Anúncios — Traduções.

Resposta:

{
  "property": {
    "id": "uuid-do-imovel-criado",
    "title": "Apartamento 2 quartos reformado - Copacabana",
    "type": "apartment"
  },
  "listings": [
    {
      "id": "uuid-listing-aluguel",
      "type": "rental",
      "price": "3500.00",
      "listingCode": "AP-001"
    },
    {
      "id": "uuid-listing-venda",
      "type": "sale",
      "price": "450000.00",
      "listingCode": "AP-002"
    }
  ]
}

Atualizar Imóvel

PATCH /api/v1/real-estate/properties/{id}

Body:

{
  "property": {
    "bedrooms": 3,
    "features": ["ar_condicionado", "churrasqueira", "piscina", "academia"]
  },
  "location": {
    "complement": "Apto 502"
  }
}

📋 Campos do Imóvel

Campos Principais (Property)

Campo	Tipo	Obrigatório	Descrição
`title`	string	Sim	Título do imóvel
`type`	enum	Sim	Tipo do imóvel (ver lista abaixo)
`bedrooms`	number	Não	Número de quartos
`bathrooms`	number	Não	Número de banheiros
`suites`	number	Não	Número de suítes
`parkingSpaces`	number	Não	Vagas de garagem
`totalArea`	decimal	Não	Área total em m²
`usableArea`	decimal	Não	Área útil em m²
`features`	string[]	Não	Lista de características

Tipos de Imóvel

Valor	Descrição
`apartment`	Apartamento
`house`	Casa
`condo_house`	Casa de Condomínio
`penthouse`	Cobertura
`studio`	Studio/Kitnet
`loft`	Loft
`commercial`	Comercial
`land`	Terreno
`rural`	Rural/Fazenda
`garage`	Garagem/Vaga

Campos de Localização

Campo	Tipo	Obrigatório	Descrição
`address`	string	Não	Endereço (rua e número)
`complement`	string	Não	Complemento
`neighborhood`	string	Sim	Bairro
`city`	string	Sim	Cidade
`state`	string	Sim	Estado (sigla: SP, RJ, etc.)
`zipCode`	string	Não	CEP
`latitude`	number	Não	Latitude
`longitude`	number	Não	Longitude

Características Comuns (Features)

{
  "features": [
    "ar_condicionado",
    "armarios_embutidos",
    "varanda",
    "churrasqueira",
    "piscina",
    "academia",
    "portaria_24h",
    "elevador",
    "playground",
    "salao_festas",
    "quadra_esportes",
    "pet_friendly"
  ]
}

🖼️ Mídias

Adicionar Mídias

As mídias são adicionadas via upload separado ou URL:

{
  "medias": [
    {
      "src": "https://cdn.example.com/image1.jpg",
      "type": "image",
      "category": "Sala",
      "order": 0,
      "isPrimary": true
    },
    {
      "src": "https://cdn.example.com/image2.jpg",
      "type": "image",
      "category": "Quarto",
      "order": 1
    }
  ]
}

Tipos de Mídia

Tipo	Descrição
`image`	Foto
`video`	Vídeo
`tour`	Tour virtual 360
`floor_plan`	Planta baixa

Categorias de Mídia

Sala, Quarto, Cozinha, Banheiro, Varanda, Área Externa,
Garagem, Fachada, Piscina, Área Comum, Planta

📚 Mais Informações

Sites API - Endpoints públicos para WordPress e sites externos
Anúncios - Gerenciar anúncios e visibilidade
Compartilhamento - Criar links de compartilhamento
Exemplos Práticos - Mais exemplos de uso