# 📘 Documentação da API: Módulo Usuários e Sessão Este módulo gerencia o ciclo de vida dos usuários, autenticação via token seguro, verificação periódica de sessão (*heartbeat*) e logout. --- ## 1. Cadastro de Usuário (`criar.php`) Cria um novo usuário (`gestor` ou `inquilino`) e já retorna o token de sessão ativo. - **URL:** `POST /aluguel/api/usuarios/criar.php` - **Autenticação:** Pública (não requer token) - **Headers:** `Content-Type: application/json` ### Body da Requisição (JSON) ```json { "nome": "Carlos Gestor", "email": "carlos@gestor.com", "senha": "senhaSegura123", "tipo": "gestor" // "gestor" ou "inquilino" } ``` ### Resposta de Sucesso (`201 Created`) ```json { "success": true, "message": "Usuário cadastrado com sucesso.", "timestamp": "2026-11-08 19:40:00", "data": { "usuario": { "id": 1, "nome": "Carlos Gestor", "email": "carlos@gestor.com", "tipo": "gestor" }, "token": "4a7f9b8c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a", "expira_em": "2026-11-09 07:40:00" } } ``` --- ## 2. Login (`login.php`) Autentica o usuário e gera um novo token com o TTL configurado (`TOKEN_TTL_HOURS`). - **URL:** `POST /aluguel/api/usuarios/login.php` - **Autenticação:** Pública - **Headers:** `Content-Type: application/json` ### Body da Requisição (JSON) ```json { "email": "carlos@gestor.com", "senha": "senhaSegura123" } ``` ### Resposta de Sucesso (`200 OK`) ```json { "success": true, "message": "Login realizado com sucesso.", "timestamp": "2026-11-08 19:40:00", "data": { "token": "4a7f9b8c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a", "expira_em": "2026-11-09 07:40:00", "ttl_horas": 12, "usuario": { "id": 1, "nome": "Carlos Gestor", "email": "carlos@gestor.com", "tipo": "gestor" }, "assinatura_ativa": true } } ``` --- ## 3. Verificação de Sessão / Heartbeat (`verificar_sessao.php`) Consultado periodicamente pelo frontend (ex: a cada 5 ou 10 minutos) ou na inicialização da aplicação para confirmar se a sessão continua ativa. - **URL:** `GET` ou `POST /aluguel/api/usuarios/verificar_sessao.php` - **Autenticação:** Requer Token via Header `Authorization: Bearer ` ou no body `{ "token": "..." }` ### Resposta de Sucesso (`200 OK`) ```json { "success": true, "message": "Sessão ativa e válida.", "timestamp": "2026-11-08 19:40:00", "data": { "ativa": true, "usuario": { "id": 1, "nome": "Carlos Gestor", "email": "carlos@gestor.com", "tipo": "gestor" }, "expira_em": "2026-11-09 07:40:00", "segundos_restantes": 43200, "assinatura_ativa": true } } ``` ### Resposta de Sessão Expirada ou Inválida (`401 Unauthorized`) ```json { "success": false, "message": "A sessão expirou pelo limite de tempo (TTL).", "timestamp": "2026-11-08 19:40:00", "data": { "ativa": false, "codigo": "SESSAO_EXPIRADA" } } ``` --- ## 4. Encerrar Sessão / Logout (`logout.php`) Invalida e remove o token no banco de dados. - **URL:** `POST` ou `DELETE /aluguel/api/usuarios/logout.php` - **Headers:** `Authorization: Bearer ` ### Resposta de Sucesso (`200 OK`) ```json { "success": true, "message": "Sessão encerrada com sucesso.", "timestamp": "2026-11-08 19:40:00" } ``` --- ## 5. Consultar e Atualizar Dados Cadastrais / Qualificação (`perfil.php`) Permite que o usuário autenticado (especialmente o **Gestor/Locador**) consulte ou preencha seus dados civis para constar nos contratos gerados (CPF/CNPJ, RG, CRECI, estado civil, profissão e endereço completo). - **URL:** `GET` ou `POST` (ou `PUT`) `/aluguel/api/usuarios/perfil.php` - **Headers:** `Authorization: Bearer ` (e `Content-Type: application/json` no `POST`/`PUT`) ### Body do `POST`/`PUT` (JSON - campos opcionais para atualização parcial) ```json { "nome": "Carlos Gestor", "telefone": "(11) 99999-1111", "cpf_cnpj": "222.333.444-55", "rg": "22.333.444-5", "creci": "CRECI-SP 98765-F", "nacionalidade": "Brasileira", "estado_civil": "casado", "profissao": "Corretor de Imóveis", "endereco_completo": "Av. Paulista, 1200, Conj. 41 - Bela Vista, São Paulo/SP" } ``` --- ## 6. Exclusão ou Anonimização de Conta - LGPD / App Store / Google Play (`excluir_conta.php`) Permite que o **inquilino** ou o **gestor** autenticado exclua sua própria conta diretamente pelo aplicativo, atendendo à LGPD e às políticas obrigatórias da App Store e Google Play: - **`exclusao_definitiva`:** Quando não há histórico jurídico/fiscal (sem contratos em andamento/assinados/encerrados, pagamentos ou vistorias assinadas), exclui fisicamente os arquivos pessoais em disco (`foto_perfil`, documentos e capas de imóveis sem vínculos) e remove o registro de `usuarios`. - **`anonimizacao_lgpd`:** Quando existem contratos, pagamentos ou laudos assinados (obrigação legal/fiscal), remove todos os documentos pessoais (`RG`, `CNH`, selfie, CRM, tokens), oculta imóveis disponíveis do mapa, anonimiza IPs de vistoria e substitui nome/e-mail/documentos da tabela `usuarios` por dados anônimos irreversíveis, liberando o e-mail original e bloqueando qualquer novo acesso. - **Métrica de Desistência (`exclusoes_contas_log`):** Toda operação grava um registro **sem dados pessoais (PII)** com perfil, modo aplicado, dias de uso, motivo e `competencia_exclusao` (`YYYY-MM`). - **URL:** `DELETE` ou `POST /aluguel/api/usuarios/excluir_conta.php` - **Headers:** `Authorization: Bearer `, `Content-Type: application/json` ### Body (JSON) ```json { "confirmar_exclusao": true, "senha_atual": "123456", "motivo_categoria": "ja_aluguei_encontrei_imovel", "motivo_detalhe": "Já fechei contrato em outro imóvel." } ``` > Valores aceitos em `motivo_categoria`: `ja_aluguei_encontrei_imovel`, `nao_gostei_da_experiencia`, `problemas_tecnicos`, `privacidade_dados`, `pausa_temporaria` ou `outro` (padrão). ### Resposta de Sucesso (`200 OK`) ```json { "success": true, "message": "Sua conta, perfil, documentos e sessões foram excluídos definitivamente com sucesso.", "timestamp": "2026-11-11 21:40:00", "data": { "usuario_id": 2, "tipo_usuario": "inquilino", "modo_aplicado": "exclusao_definitiva", "arquivos_removidos": 3, "competencia_registro": "2026-11", "excluido_em": "2026-11-11 21:40:00" } } ``` ### Consulta SQL para Painel de Desistências Mensais (`exclusoes_contas_log`) ```sql SELECT competencia_exclusao, tipo_usuario, modo_exclusao, motivo_categoria, COUNT(*) AS total_excluidos, ROUND(AVG(dias_de_uso), 1) AS media_dias_uso FROM exclusoes_contas_log GROUP BY competencia_exclusao, tipo_usuario, modo_exclusao, motivo_categoria ORDER BY competencia_exclusao DESC, total_excluidos DESC; ``` --- ## 7. Exemplo de Integração Frontend (JavaScript / Fetch) ```javascript // Exemplo de Login e armazenamento seguro async function realizarLogin(email, senha) { const response = await fetch('http://localhost/aluguel/api/usuarios/login.php', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ email, senha }) }); const res = await response.json(); if (res.success) { localStorage.setItem('auth_token', res.data.token); localStorage.setItem('usuario', JSON.stringify(res.data.usuario)); return res.data; } else { throw new Error(res.message); } } // Exemplo de Heartbeat (Verificação de sessão) async function verificarSessao() { const token = localStorage.getItem('auth_token'); if (!token) return false; const response = await fetch('http://localhost/aluguel/api/usuarios/verificar_sessao.php', { method: 'GET', headers: { 'Authorization': `Bearer ${token}` } }); const res = await response.json(); return res.success && res.data.ativa; } ```