# 📘 Documentação da API: Módulo Inquilinos, CRM e Reputação

Este módulo gerencia o relacionamento completo com o inquilino em três camadas complementares:
1. **Camada de Carteira / CRM Multi-Corretor:** O corretor pode cadastrar inquilinos na sua base de contatos/leads mesmo antes de ter um imóvel para ele (sem exclusividade — o inquilino pode estar na carteira de múltiplos corretores).
2. **Camada da Esteira de Locação de Imóvel:** O fluxo operacional para quando há um imóvel definido (`convidado` $\rightarrow$ `em_analise` $\rightarrow$ `aprovado` $\rightarrow$ `contrato_enviado` $\rightarrow$ `contrato_assinado` $\rightarrow$ `ativo`).
3. **Score Reputacional / Avaliações em Rede:** Notas de 1 a 5 estrelas sobre Pontualidade, Conservação e Convivência/Conduta deixadas por locadores anteriores, compartilhadas entre os corretores da plataforma.

---

## 1. Gerar Link de Convite de Imóvel (`convite.php`)
O gestor gera um link atrelado a um imóvel específico após uma visita ou contato.

- **URL:** `POST /aluguel/api/inquilinos/convite.php`
- **Autenticação:** Requer perfil `gestor`
- **Headers:** `Authorization: Bearer <token>`, `Content-Type: application/json`

### Body (JSON)
```json
{
  "imovel_id": 1
}
```

### Resposta (`201 Created`)
```json
{
  "success": true,
  "message": "Link de convite para inquilino gerado com sucesso.",
  "data": {
    "imovel": {
      "id": 1,
      "titulo": "Apartamento 304 - Edifício Bela Vista",
      "valor_aluguel": "2500.00"
    },
    "token_convite": "e8a1c97f4d2b0e6a3c5f8e1a7d4b0c2e...",
    "url_convite": "http://localhost/aluguel/cadastro-inquilino.html?token=e8a1c97f...",
    "texto_whatsapp": "Olá! Aqui está o seu acesso exclusivo para o imóvel..."
  }
}
```

---

## 2. Gerar Convite Geral de Carteira / CRM (`convite_carteira.php`)
O gestor gera um link sem imóvel vinculado, para convidar o inquilino a entrar na sua carteira de clientes (receber lançamentos e oportunidades futuras).

- **URL:** `POST /aluguel/api/inquilinos/convite_carteira.php`
- **Autenticação:** Requer perfil `gestor`
- **Headers:** `Authorization: Bearer <token>`, `Content-Type: application/json`

### Body (JSON)
```json
{
  "observacoes": "Cliente buscando ap de 2 dormitórios na Zona Sul até R$ 3.000"
}
```

### Resposta (`201 Created`)
```json
{
  "success": true,
  "message": "Link de convite para a carteira de clientes gerado com sucesso.",
  "data": {
    "gestor": { "id": 1, "nome": "Carlos Gestor", "email": "carlos@gestor.com" },
    "token_convite": "CORRETOR_a9f1b2c3d4...",
    "url_convite": "http://localhost/aluguel/cadastro-inquilino.html?token=CORRETOR_a9f1b2c3d4...",
    "texto_whatsapp": "Olá! Aqui é Carlos Gestor. Acesse meu portal exclusivo para se cadastrar na minha carteira de clientes..."
  }
}
```

---

## 3. Consulta Prévia do Convite (`cadastrar_auto.php` via GET)
Identifica automaticamente se o link é de um Imóvel ou da Carteira Geral do Corretor.

- **URL:** `GET /aluguel/api/inquilinos/cadastrar_auto.php?token={TOKEN}`
- **Autenticação:** Pública

---

## 4. Autocadastro e Vinculação (`cadastrar_auto.php` via POST)
Processa tanto contas novas quanto contas existentes (login para vincular).

- **URL:** `POST /aluguel/api/inquilinos/cadastrar_auto.php`
- **Autenticação:** Pública
- **Headers:** `Content-Type: application/json`

### Body (JSON)
```json
{
  "token_convite": "CORRETOR_... ou TOKEN_IMOVEL",
  "nome": "Mariana Santos",
  "email": "mariana@inquilino.com",
  "senha": "senhaSegura123",
  "telefone": "(11) 98888-7777",
  "cpf_cnpj": "123.456.789-00"
}
```

---

## 5. Listar Carteira de Clientes do Gestor (`listar_carteira.php`)
Permite ao gestor ver todos os inquilinos na sua base, contatos, observações e se possuem contratos ativos.

- **URL:** `GET /aluguel/api/inquilinos/listar_carteira.php`
- **Autenticação:** Requer perfil `gestor`
- **Headers:** `Authorization: Bearer <token>`

---

## 6. Vincular Inquilino da Carteira ao Imóvel (`vincular_imovel.php`)
Permite ao gestor pegar um inquilino que já está na sua base e vinculá-lo diretamente a um imóvel que acabou de vagar, iniciando a esteira de locação.

- **URL:** `POST /aluguel/api/inquilinos/vincular_imovel.php`
- **Autenticação:** Requer perfil `gestor`
- **Headers:** `Authorization: Bearer <token>`, `Content-Type: application/json`

### Body (JSON)
```json
{
  "inquilino_id": 2,
  "imovel_id": 1
}
```

---

## 7. Perfil Completo e Foto de Perfil do Inquilino (`perfil.php`)
Permite ao inquilino consultar e completar/editar toda a sua ficha civil após o cadastro inicial (incluindo upload da `foto_perfil`, RG, estado civil, profissão, renda e endereço atual), e permite ao gestor vinculado consultar essa ficha antes de fechar o contrato.

- **URL (`GET`):** `GET /aluguel/api/inquilinos/perfil.php` *(para o próprio inquilino)* ou `GET /aluguel/api/inquilinos/perfil.php?inquilino_id=2` *(para o gestor vinculado)*
- **URL (`POST`/`PUT`):** `POST /aluguel/api/inquilinos/perfil.php`
- **Autenticação:** Requer token válido (`Authorization: Bearer <token>`)
- **Formatos aceitos no `POST`:**
  - `multipart/form-data` (quando enviar arquivo no campo `foto_perfil` + campos de texto)
  - `application/json` (atualizações parciais apenas de texto; campos omitidos são preservados)

### Campos Suportados (`POST` / `PUT`)
`nome`, `foto_perfil` *(arquivo JPG/PNG/WEBP)*, `telefone`, `cpf_cnpj`, `rg`, `orgao_emissor`, `data_nascimento` *(YYYY-MM-DD)*, `nacionalidade`, `estado_civil` *(`solteiro`, `casado`, `divorciado`, `viuvo`, `uniao_estavel`)*, `profissao`, `renda_mensal`, `empresa_trabalho`, `cep`, `endereco_atual`, `cidade`, `estado` *(UF)*, `contato_emergencia_nome`, `contato_emergencia_telefone`.

> **Resposta (`GET`/`POST`):** Além do objeto `perfil` e da lista `documentos` com URLs, retorna `perfil_completo_para_contrato` (`true`/`false`) e `campos_pendentes_contrato` listando o que ainda falta para redigir o contrato.

---

## 8. Detalhes do Inquilino no Imóvel (`detalhes_vinculo.php`)
Retorna os dados cadastrais completos do inquilino (incluindo `inquilino_url_foto_perfil`, qualificação civil e `campos_pendentes_contrato`), dados do locador/gestor, documentos enviados e o **Score Reputacional / Avaliações** de locadores anteriores.

- **URL:** `GET /aluguel/api/inquilinos/detalhes_vinculo.php?vinculo_id=1`
- **Autenticação:** Requer perfil `gestor`
- **Headers:** `Authorization: Bearer <token>`

---

## 9. Aprovação do Cadastro pelo Gestor / "Dar OK" (`aprovar_cadastro.php`)
- **URL:** `POST /aluguel/api/inquilinos/aprovar_cadastro.php`
- **Autenticação:** Requer perfil `gestor`
- **Body:** `{ "vinculo_id": 1 }`

---

## 10. Gerar ou Enviar Minuta de Contrato (`gerar_contrato.php`)
Gera automaticamente a minuta completa em HTML/PDF preenchida com a qualificação civil do locador + locatário + imóvel, ou aceita upload de PDF próprio via `multipart/form-data` (campo `arquivo_contrato`).
- **URL:** `POST /aluguel/api/inquilinos/gerar_contrato.php`
- **Autenticação:** Requer perfil `gestor`
- **Body (JSON - campos opcionais além de `vinculo_id`):**
```json
{
  "vinculo_id": 1,
  "prazo_meses": 12,
  "data_inicio": "2026-12-01",
  "dia_vencimento": 5,
  "garantia_tipo": "caucao",
  "garantia_valor": 7500.00,
  "observacoes_clausula": "Permitido 1 animal de estimação de pequeno porte."
}
```
> Valores aceitos em `garantia_tipo`: `caucao` (padrão), `fiador`, `seguro_fianca`, `sem_garantia`.

---

## 11. Upload do Contrato Assinado (`enviar_contrato_assinado.php`)
O inquilino envia a via assinada com **Gov.br** ou cartório.
- **URL:** `POST /aluguel/api/inquilinos/enviar_contrato_assinado.php`
- **Autenticação:** Requer perfil `inquilino`
- **Campos Multipart:** `vinculo_id` (int), `arquivo` (PDF)

---

## 12. Ativar Locação Oficialmente (`ativar_locacao.php`)
- **URL:** `POST /aluguel/api/inquilinos/ativar_locacao.php`
- **Autenticação:** Requer perfil `gestor`
- **Body:** `{ "vinculo_id": 1 }`

---

## 13. Documentos Enviados pelo Inquilino (`documentos.php`)
Lista, envia ou remove fotos/PDFs dos documentos do inquilino, devolvendo `caminho_arquivo` e a URL completa `url_arquivo` pronta para abertura no frontend.

- **URL:** `GET`, `POST` ou `DELETE /aluguel/api/inquilinos/documentos.php`
- **Autenticação:** Requer token válido (`inquilino` gerencia os seus; `gestor` consulta/envia passando `?inquilino_id=...`, exigindo vínculo ativo em carteira ou imóvel)
- **Campos Multipart (`POST`):** `tipo_documento` (ex.: `"RG Frente"`, `"CNH"`, `"Comprovante de Renda"`), `arquivo` (PDF/JPG/PNG/DOC/DOCX)
- **Parâmetro (`DELETE`):** `?id=1` ou body `{ "id": 1 }` *(apenas o próprio inquilino)*

### Resposta do `GET` (`200 OK`)
```json
{
  "success": true,
  "message": "Documentos recuperados com sucesso.",
  "data": {
    "inquilino_id": 2,
    "total": 1,
    "documentos": [
      {
        "id": 1,
        "inquilino_id": 2,
        "tipo_documento": "RG Frente",
        "caminho_arquivo": "documentos/9a1b2c..._1762890000.jpg",
        "enviado_em": "2026-11-11 20:00:00",
        "url_arquivo": "http://localhost/aluguel/api/arquivos/ver.php?arquivo=documentos%2F9a1b2c..._1762890000.jpg&expires=1794443200&uid=2&token=a4f9..."
      }
    ]
  }
}
```
> **Segurança (LGPD):** A pasta `/uploads` é bloqueada para leitura direta. Toda URL devolvida já traz um **token HMAC temporário** (15 min) vinculado ao usuário autenticado e checado no banco em tempo real via [`api/arquivos/ver.php`](../arquivos/README.md).
>
> **Dica de Frontend:** Ao abrir a tela de perfil via `GET /api/inquilinos/perfil.php`, a lista `documentos` (já com `url_arquivo`) e `url_foto_perfil` já vêm embutidas na mesma resposta! Use `GET /api/inquilinos/documentos.php` se quiser atualizar apenas a lista de documentos de forma isolada.

---

## 14. Consultar Meus Aluguéis / Portal do Inquilino (`meus_alugueis.php`)
Retorna todas as locações do inquilino logado, status na esteira, minutas e vistorias pendentes de aceite digital.
- **URL:** `GET /aluguel/api/inquilinos/meus_alugueis.php`
- **Autenticação:** Requer perfil `inquilino`
- **Headers:** `Authorization: Bearer <token>`

---

## 15. Avaliar Inquilino / Score Reputacional (`avaliar.php`)
Permite ao gestor/corretor avaliar um inquilino em 3 pilares fundamentais com notas de 1 a 5 estrelas. Essas avaliações ficam registradas na rede e constroem a pontuação de confiabilidade do inquilino.

- **URL:** `POST /aluguel/api/inquilinos/avaliar.php`
- **Autenticação:** Requer perfil `gestor`
- **Headers:** `Authorization: Bearer <token>`, `Content-Type: application/json`

### Pilares Avaliados:
- `pontualidade_pagamento` (1 a 5 estrelas): Rigor no pagamento pontual do aluguel.
- `conservacao_imovel` (1 a 5 estrelas): Cuidado com a integridade física do imóvel e instalações.
- `convivencia_conduta` (1 a 5 estrelas): Cumprimento do regulamento interno, respeito às normas condominiais e convivência harmônica.

### Body (JSON)
```json
{
  "inquilino_id": 2,
  "imovel_id": 1,
  "pontualidade_pagamento": 5,
  "conservacao_imovel": 5,
  "convivencia_conduta": 4,
  "recomenda": true,
  "comentario": "Excelente inquilino! Cumpriu todos os prazos pontualmente e entregou o imóvel em perfeito estado."
}
```

### Resposta (`201 Created`)
```json
{
  "success": true,
  "message": "Avaliação do inquilino registrada com sucesso na rede de corretores!",
  "data": {
    "avaliacao_id": 1,
    "inquilino_id": 2,
    "inquilino_nome": "Mariana Santos",
    "notas": {
      "pontualidade_pagamento": 5,
      "conservacao_imovel": 5,
      "convivencia_conduta": 4,
      "media_desta_avaliacao": 4.67,
      "recomenda": true
    },
    "score_atualizado": {
      "media_geral_estrelas": 4.67,
      "total_avaliacoes": 1,
      "taxa_recomendacao_percentual": 100
    }
  }
}
```

---

## 16. Consultar Score e Histórico de Avaliações (`score.php`)
Permite a qualquer corretor autenticado verificar a reputação do inquilino antes de aprovar uma nova locação, ou ao próprio inquilino consultar seu histórico.

- **URL:** `GET /aluguel/api/inquilinos/score.php?inquilino_id=2`
- **Autenticação:** Requer token (Gestor ou Inquilino)
- **Headers:** `Authorization: Bearer <token>`

### Resposta (`200 OK`)
```json
{
  "success": true,
  "message": "Score reputacional do inquilino recuperado com sucesso.",
  "data": {
    "inquilino": {
      "id": 2,
      "nome": "Mariana Santos",
      "email": "mariana@inquilino.com"
    },
    "score": {
      "total_avaliacoes": 3,
      "media_geral_estrelas": 4.89,
      "media_pontualidade": 5.0,
      "media_conservacao": 4.67,
      "media_convivencia_conduta": 5.0,
      "taxa_recomendacao_percentual": 100,
      "historico_avaliacoes": [
        {
          "id": 1,
          "pontualidade_pagamento": 5,
          "conservacao_imovel": 5,
          "convivencia_conduta": 4,
          "media_geral": "4.67",
          "recomenda": 1,
          "comentario": "Excelente inquilino! Cumpriu todos os prazos pontualmente.",
          "criado_em": "2026-11-08 22:20:00",
          "gestor_nome": "Carlos Gestor Demo",
          "imovel_titulo": "Apartamento 102 - Residencial Jardins"
        }
      ]
    }
  }
}
```

---

## 17. Candidatar-se a um Imóvel pelo Mapa (`demonstrar_interesse.php`)
Permite que o **inquilino já logado** demonstre interesse em 1 clique ao clicar em um imóvel encontrado no mapa público (`buscar_mapa.php`), sem precisar preencher cadastro novamente.

- **URL:** `POST /aluguel/api/inquilinos/demonstrar_interesse.php`
- **Autenticação:** Requer perfil `inquilino`
- **Headers:** `Authorization: Bearer <token>`, `Content-Type: application/json`

### Body (JSON)
```json
{
  "imovel_id": 1,
  "observacoes": "Tenho interesse em visitar nesta semana."
}
```
> Registra automaticamente o contato na carteira do corretor (`origem = 'busca_mapa'`). Se o imóvel estiver livre, já inicia o vínculo em `em_analise`.

---

## 18. Encerrar Locação (`encerrar_locacao.php`)
Finaliza oficialmente um contrato ativo ou negociação em andamento, muda o status do vínculo para `encerrado`, libera o imóvel (`disponivel` ou `manutencao`) e atualiza o status CRM do inquilino na carteira.

- **URL:** `POST /aluguel/api/inquilinos/encerrar_locacao.php`
- **Autenticação:** Requer perfil `gestor`
- **Headers:** `Authorization: Bearer <token>`, `Content-Type: application/json`

### Body (JSON)
```json
{
  "vinculo_id": 1,
  "novo_status_imovel": "disponivel",
  "status_carteira": "interessado"
}
```