# 📘 Documentação da API: Módulo Imóveis

Este módulo gerencia o cadastro, listagem e detalhes dos imóveis para os perfis de Gestor e Inquilino.

---

## 1. Cadastrar Imóvel (`criar.php`)
Permite ao gestor cadastrar um novo imóvel sob sua gestão.

- **URL:** `POST /aluguel/api/imoveis/criar.php`
- **Autenticação:** Requer perfil de `gestor` com assinatura ativa
- **Headers:** 
  - `Authorization: Bearer <token>`
  - `Content-Type: application/json`

### Body da Requisição (JSON)
```json
{
  "titulo": "Apartamento 304 - Edifício Bela Vista",
  "descricao": "Apartamento ensolarado de 2 quartos com sacada e garagem coberta.",
  "endereco": "Rua das Flores, 123, Apto 304",
  "bairro": "Bela Vista",
  "cidade": "São Paulo",
  "estado": "SP",
  "cep": "01310-200",
  "latitude": -23.561684,
  "longitude": -46.655981,
  "valor_aluguel": 2500.00,
  "status": "disponivel" // "disponivel", "alugado" ou "manutencao"
}
```

### Resposta de Sucesso (`201 Created`)
```json
{
  "success": true,
  "message": "Imóvel cadastrado com sucesso.",
  "timestamp": "2026-11-08 19:40:00",
  "data": {
    "id": 1,
    "titulo": "Apartamento 304 - Edifício Bela Vista",
    "endereco": "Rua das Flores, 123, Apto 304",
    "bairro": "Bela Vista",
    "cidade": "São Paulo",
    "estado": "SP",
    "latitude": -23.561684,
    "longitude": -46.655981,
    "valor_aluguel": 2500.00,
    "status": "disponivel"
  }
}
```

---

## 2. Listar Imóveis do Gestor (`listar.php`)
Retorna todos os imóveis cadastrados pelo gestor autenticado, acompanhado do inquilino vinculado e status do convite.

- **URL:** `GET /aluguel/api/imoveis/listar.php`
- **Parâmetros Opcionais (Query String):**
  - `status`: Filtrar por status (`disponivel`, `alugado`, `manutencao`)
- **Headers:** `Authorization: Bearer <token>`

### Resposta de Sucesso (`200 OK`)
```json
{
  "success": true,
  "message": "Lista de imóveis recuperada com sucesso.",
  "timestamp": "2026-11-08 19:40:00",
  "data": {
    "total": 1,
    "imoveis": [
      {
        "id": 1,
        "gestor_id": 1,
        "titulo": "Apartamento 304 - Edifício Bela Vista",
        "endereco": "Rua das Flores, 123, Apto 304 - Centro, São Paulo/SP",
        "valor_aluguel": "2500.00",
        "status": "alugado",
        "criado_em": "2026-11-08 18:30:00",
        "vinculo_id": 1,
        "token_convite": "9f8e7d6c5b4a3...",
        "status_vinculo": "ativo",
        "inquilino_id": 2,
        "inquilino_nome": "Mariana Santos",
        "inquilino_email": "mariana@inquilino.com",
        "inquilino_telefone": "(11) 98888-7777"
      }
    ]
  }
}
```

---

## 3. Detalhes de um Imóvel (`detalhe.php`)
Retorna os dados completos do imóvel. Gestores só podem consultar seus próprios imóveis; Inquilinos só podem consultar imóveis aos quais estão vinculados.

- **URL:** `GET /aluguel/api/imoveis/detalhe.php?id=1`
- **Headers:** `Authorization: Bearer <token>`

### Resposta de Sucesso (`200 OK`)
```json
{
  "success": true,
  "message": "Detalhes do imóvel recuperados com sucesso.",
  "timestamp": "2026-11-08 19:40:00",
  "data": {
    "imovel": {
      "id": 1,
      "gestor_id": 1,
      "titulo": "Apartamento 304 - Edifício Bela Vista",
      "endereco": "Rua das Flores, 123, Apto 304 - Centro, São Paulo/SP",
      "valor_aluguel": "2500.00",
      "status": "alugado",
      "gestor_nome": "Carlos Gestor",
      "gestor_email": "carlos@gestor.com",
      "inquilino_id": 2,
      "inquilino_nome": "Mariana Santos",
      "inquilino_email": "mariana@inquilino.com",
      "inquilino_telefone": "(11) 98888-7777",
      "inquilino_cpf_cnpj": "123.456.789-00",
      "vinculado_em": "2026-11-08 19:00:00"
    }
  }
}
```

---

## 4. Atualizar Imóvel (`atualizar.php`)
Permite ao gestor atualizar os dados do imóvel (título, endereço, valor e status).

- **URL:** `POST` ou `PUT /aluguel/api/imoveis/atualizar.php`
- **Headers:** 
  - `Authorization: Bearer <token>`
  - `Content-Type: application/json`

### Body da Requisição (JSON)
```json
{
  "id": 1,
  "titulo": "Apartamento 304 - Edifício Bela Vista (Reformado)",
  "endereco": "Rua das Flores, 123, Apto 304 - Centro, São Paulo/SP",
  "valor_aluguel": 2700.00,
  "status": "disponivel"
}
```

### Resposta de Sucesso (`200 OK`)
```json
{
  "success": true,
  "message": "Imóvel atualizado com sucesso.",
  "data": {
    "id": 1,
    "titulo": "Apartamento 304 - Edifício Bela Vista (Reformado)",
    "endereco": "Rua das Flores, 123, Apto 304 - Centro, São Paulo/SP",
    "valor_aluguel": 2700,
    "status": "disponivel"
  }
}
```

---

## 5. Buscar Imóveis no Mapa por Raio e Catálogo Público (`buscar_mapa.php`)
**Endpoint 100% Público** (não requer token). Usado na tela Home do app para mostrar o mapa e a lista de imóveis disponíveis para locação próximos à localização do usuário (via fórmula geodésica de Haversine).

- **URL:** `GET /aluguel/api/imoveis/buscar_mapa.php`
- **Autenticação:** Pública (visitantes e inquilinos)
- **Parâmetros da Query String:**
  - `lat`: (float, obrigatório p/ busca em raio) Latitude do centro/usuário (ex: `-23.561684`)
  - `lng`: (float, obrigatório p/ busca em raio) Longitude do centro/usuário (ex: `-46.655981`)
  - `raio_km`: (float, opcional, padrão `5.0`) Raio de busca em quilômetros (ex: `2`, `3`, `5`, `10`)
  - `preco_min`: (float, opcional) Valor de aluguel mínimo
  - `preco_max`: (float, opcional) Valor de aluguel máximo
  - `cidade`: (string, opcional) Filtro textual (ex: "São Paulo")
  - `bairro`: (string, opcional) Filtro textual (ex: "Pinheiros")

### Exemplo de Requisição por Raio (3km)
`GET /aluguel/api/imoveis/buscar_mapa.php?lat=-23.561684&lng=-46.655981&raio_km=3.0`

### Resposta de Sucesso (`200 OK`)
```json
{
  "success": true,
  "message": "Imóveis para catálogo e mapa recuperados com sucesso.",
  "timestamp": "2026-11-08 20:40:00",
  "data": {
    "modo_busca": "geolocalizacao_raio",
    "filtros": {
      "latitude": -23.561684,
      "longitude": -46.655981,
      "raio_km": 3,
      "preco_min": null,
      "preco_max": null
    },
    "total": 1,
    "imoveis": [
      {
        "id": 1,
        "titulo": "Apartamento 102 - Residencial Jardins",
        "descricao": "Excelente apartamento mobiliado de 2 dormitórios próximo ao metrô Trianon-Masp.",
        "endereco": "Av. Paulista, 1500, Apto 102",
        "bairro": "Bela Vista",
        "cidade": "São Paulo",
        "estado": "SP",
        "cep": "01310-200",
        "latitude": "-23.56168400",
        "longitude": "-46.65598100",
        "foto_capa": null,
        "foto_capa_url": null,
        "valor_aluguel": "2850.00",
        "status": "disponivel",
        "gestor_nome": "Carlos Gestor Demo",
        "gestor_email": "gestor@demo.com",
        "distancia_km": 0.00
      }
    ]
  }
}
```

---

## 6. Exemplo de Integração Frontend (JavaScript / Fetch)

```javascript
// Buscar imóveis próximos ao usuário (usando GPS do dispositivo)
async function buscarImoveisProximos(raioKm = 3.0) {
  navigator.geolocation.getCurrentPosition(async (pos) => {
    const lat = pos.coords.latitude;
    const lng = pos.coords.longitude;

    const res = await fetch(`http://localhost/aluguel/api/imoveis/buscar_mapa.php?lat=${lat}&lng=${lng}&raio_km=${raioKm}`);
    const data = await res.json();
    
    // Plota os pins no mapa (Google Maps / Leaflet / Mapbox)
    data.data.imoveis.forEach(imovel => {
      console.log(`Imóvel: ${imovel.titulo} a ${imovel.distancia_km}km de você. Valor: R$ ${imovel.valor_aluguel}`);
    });
  });
}

// Listar imóveis do gestor logado
async function carregarImoveisGestor() {
  const token = localStorage.getItem('auth_token');
  const res = await fetch('http://localhost/aluguel/api/imoveis/listar.php', {
    headers: { 'Authorization': `Bearer ${token}` }
  });
  const json = await res.json();
  return json.data.imoveis;
}
```