# 📘 Documentação da API: Módulo Vistorias e Aceite Digital

Este módulo gerencia laudos de vistoria de entrada e saída, registro fotográfico por cômodos e coleta de aceite digital auditável (com IP e carimbo temporal).

---

## 1. Abrir Vistoria (`criar_vistoria.php`)
Permite ao gestor iniciar um novo laudo de vistoria (entrada ou saída) para um imóvel.

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

### Body da Requisição (JSON)
```json
{
  "imovel_id": 1,
  "tipo": "entrada", // "entrada" ou "saida"
  "status": "rascunho" // "rascunho" ou "aguardando_aceite"
}
```

### Resposta de Sucesso (`201 Created`)
```json
{
  "success": true,
  "message": "Vistoria iniciada com sucesso.",
  "timestamp": "2026-11-08 19:40:00",
  "data": {
    "vistoria_id": 1,
    "imovel_id": 1,
    "tipo": "entrada",
    "status": "rascunho"
  }
}
```

---

## 2. Listar Vistorias de um Imóvel (`listar.php`)
Retorna todas as vistorias abertas para o imóvel informado.

- **URL:** `GET /aluguel/api/vistorias/listar.php?imovel_id=1`
- **Autenticação / Autorização:** Exige ser o `gestor` proprietário do imóvel ou `inquilino` vinculado ao imóvel (`403` caso contrário)
- **Headers:** `Authorization: Bearer <token>`

### Resposta de Sucesso (`200 OK`)
```json
{
  "success": true,
  "message": "Lista de vistorias recuperada com sucesso.",
  "data": {
    "imovel_id": 1,
    "total": 1,
    "vistorias": [
      {
        "id": 1,
        "imovel_id": 1,
        "tipo": "entrada",
        "status": "aguardando_aceite",
        "criado_em": "2026-11-08 18:00:00",
        "total_fotos": 6
      }
    ]
  }
}
```

---

## 3. Adicionar Foto por Cômodo (`adicionar_foto.php`)
Upload isolado de imagem para a vistoria com identificação do cômodo e observações de avarias/estado de conservação.

- **URL:** `POST /aluguel/api/vistorias/adicionar_foto.php`
- **Autenticação / Autorização:** Requer perfil `gestor` proprietário do imóvel da vistoria (`403` para outros gestores ou inquilinos)
- **Headers:** 
  - `Authorization: Bearer <token>`
  - `Content-Type: multipart/form-data`
- **Campos do Formulário (`FormData`):**
  - `vistoria_id`: (int) ID da vistoria
  - `comodo`: (string) Ex: "Sala", "Cozinha", "Quarto 1", "Banheiro Social"
  - `observacao`: (string, opcional) Ex: "Pequeno risco na pintura da parede leste."
  - `foto`: (arquivo binário: JPG, PNG, WEBP)

### Resposta de Sucesso (`201 Created`)
```json
{
  "success": true,
  "message": "Foto do cômodo adicionada com sucesso.",
  "data": {
    "id": 1,
    "vistoria_id": 1,
    "comodo": "Sala de Estar",
    "caminho_arquivo": "vistorias/4b8a2c1d_1762641000.jpg",
    "url_completa": "http://localhost/aluguel/api/arquivos/ver.php?arquivo=vistorias%2F4b8a2c1d_1762641000.jpg&expires=1794443200&uid=1&token=a4f9...",
    "observacao": "Pintura nova sem manchas.",
    "nome_original": "sala_foto_1.jpg"
  }
}
```

---

## 4. Consulta Completa do Laudo (`aceite.php` via GET)
Recupera todos os dados do laudo, galeria de fotos separada por cômodos e histórico de aceites digitais.

- **URL:** `GET /aluguel/api/vistorias/aceite.php?vistoria_id=1`
- **Autenticação / Autorização:** Exige vínculo com o imóvel (`gestor` dono ou `inquilino` vinculado/signatário)
- **Headers:** `Authorization: Bearer <token>`

### Resposta de Sucesso (`200 OK`)
```json
{
  "success": true,
  "message": "Laudo de vistoria recuperado com sucesso.",
  "data": {
    "vistoria": {
      "id": 1,
      "imovel_id": 1,
      "tipo": "entrada",
      "status": "aguardando_aceite",
      "imovel_titulo": "Apartamento 304 - Edifício Bela Vista",
      "fotos": [
        {
          "id": 1,
          "comodo": "Sala de Estar",
          "caminho_arquivo": "vistorias/4b8a2c1d_1762641000.jpg",
          "url_foto": "http://localhost/aluguel/api/arquivos/ver.php?arquivo=vistorias%2F4b8a2c1d_1762641000.jpg&expires=1794443200&uid=1&token=a4f9...",
          "observacao": "Pintura nova sem manchas."
        }
      ],
      "aceites": [
        {
          "id": 1,
          "usuario_id": 1,
          "nome": "Carlos Gestor",
          "tipo_usuario": "gestor",
          "ip_origem": "189.40.12.55",
          "data_aceite": "2026-11-08 18:30:00"
        }
      ]
    }
  }
}
```

---

## 5. Registrar Aceite Digital (`aceite.php` via POST)
Registra formalmente a aprovação do laudo de vistoria pelo gestor ou pelo inquilino, capturando automaticamente data, hora e IP de origem.

- **URL:** `POST /aluguel/api/vistorias/aceite.php`
- **Headers:** 
  - `Authorization: Bearer <token>`
  - `Content-Type: application/json`

### Body da Requisição (JSON)
```json
{
  "vistoria_id": 1
}
```

### Resposta de Sucesso (`200 OK`)
```json
{
  "success": true,
  "message": "Aceite digital registrado com sucesso!",
  "data": {
    "aceite_id": 2,
    "vistoria_id": 1,
    "usuario": {
      "id": 2,
      "nome": "Mariana Santos",
      "tipo": "inquilino"
    },
    "ip_origem": "177.18.90.102",
    "data_aceite": "2026-11-08 19:40:00",
    "novo_status": "concluida"
  }
}
```

---

## 6. Exemplo de Integração no Mobile (React Native / Flutter / Web)

```javascript
// Enviar foto capturada pela câmera do celular
async function enviarFotoVistoria(vistoriaId, comodo, arquivoImagem, observacao = '') {
  const token = localStorage.getItem('auth_token');
  const formData = new FormData();
  formData.append('vistoria_id', vistoriaId);
  formData.append('comodo', comodo);
  formData.append('observacao', observacao);
  formData.append('foto', arquivoImagem);

  const res = await fetch('http://localhost/aluguel/api/vistorias/adicionar_foto.php', {
    method: 'POST',
    headers: { 'Authorization': `Bearer ${token}` },
    body: formData
  });
  return await res.json();
}

// Assinar laudo digitalmente
async function registrarAceiteVistoria(vistoriaId) {
  const token = localStorage.getItem('auth_token');
  const res = await fetch('http://localhost/aluguel/api/vistorias/aceite.php', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ vistoria_id: vistoriaId })
  });
  return await res.json();
}
```