> ## Documentation Index
> Fetch the complete documentation index at: https://docs.patrimonion.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Autenticação

> Como autenticar na API do Patrimonion. O mecanismo é Session Cookie via Firebase Admin SDK — não Bearer Token.

## Visão Geral

A API usa **Session Cookie** para autenticação — não Bearer Token. O fluxo é:

1. Frontend chama `POST /auth/login` com e-mail e senha
2. O backend valida as credenciais na Firebase Identity Toolkit, cria um session cookie via Firebase Admin SDK e o seta na resposta
3. Todas as requisições seguintes enviam o cookie automaticamente (browser/fetch com `credentials: "include"`)
4. O middleware `verificarToken` valida o cookie em cada requisição usando `admin.auth().verifySessionCookie()`

O cookie tem nome configurável via `SESSION_COOKIE_NAME` (padrão: `imob_session`) e expira em `SESSION_EXPIRES_DAYS` dias (padrão: 5).

***

## Login

```http theme={null}
POST /auth/login
Content-Type: application/json

{
  "email": "usuario@email.com",
  "password": "suasenha"
}
```

```json Resposta 200 theme={null}
{
  "message": "Login realizado com sucesso.",
  "user": {
    "uid": "uid_do_usuario",
    "email": "usuario@email.com",
    "role": "LOCADOR",
    "tipoPessoa": "PF",
    "nome": "João da Silva"
  }
}
```

O cookie `imob_session` é setado automaticamente na resposta com as flags `httpOnly`, `secure` e `sameSite: none` em produção.

**Erros possíveis:**

```json 401 — Credenciais inválidas theme={null}
{ "error": "E-mail ou senha incorretos." }
```

```json 403 — Conta desativada theme={null}
{ "error": "Sua conta está desativada. Entre em contato com o suporte." }
```

***

## Como fazer requisições autenticadas

No frontend, use `credentials: "include"` em todas as chamadas para que o browser envie o cookie automaticamente:

```typescript theme={null}
const res = await fetch("https://api.patrimonion.com.br/imoveis", {
  credentials: "include",
});
```

Nenhum header `Authorization` é necessário — o cookie é enviado automaticamente pelo browser.

***

## Logout

Invalida o cookie e revoga os refresh tokens do Firebase.

```http theme={null}
POST /auth/logout
```

```json Resposta 200 theme={null}
{ "message": "Logout realizado com sucesso." }
```

***

## Registro

Cria uma conta nova. O primeiro usuário registrado recebe automaticamente o role `SUPER_ADMIN`. Os demais recebem `LOCADOR`.

Suporta Pessoa Física (`PF`) e Pessoa Jurídica (`PJ`).

```http theme={null}
POST /auth/register
Content-Type: application/json

{
  "email": "novo@email.com",
  "password": "senha123",
  "tipoPessoa": "PF",
  "nomeCompleto": "João da Silva",
  "cpf": "123.456.789-00",
  "telefone": "(11) 99999-0000",
  "cep": "01310-100",
  "rua": "Rua das Flores",
  "numero": "123",
  "bairro": "Centro",
  "cidade": "São Paulo",
  "estado": "SP"
}
```

```json Resposta 201 theme={null}
{
  "message": "Conta criada com sucesso. Verifique seu e-mail para ativar a conta.",
  "user": {
    "uid": "uid_gerado",
    "email": "novo@email.com",
    "role": "LOCADOR",
    "nome": "João da Silva"
  }
}
```

Um e-mail de verificação é enviado via Brevo automaticamente após o registro. A chamada não é bloqueada pelo envio — se falhar, apenas um aviso é logado.

### Campos obrigatórios por tipo de pessoa

**PF:** `nomeCompleto`, `cpf`, mais o endereço completo.

**PJ:** `razaoSocial`, `cnpj`, `nomeResponsavel`, mais o endereço completo.

***

## Verificação de e-mail

### Reenviar e-mail de verificação

Rate limit interno: 1 envio a cada 2 minutos por usuário.

```http theme={null}
POST /auth/resend-verification
```

### Confirmar verificação

Chamado pelo frontend após o usuário clicar no link e o Firebase processar. Atualiza `emailVerificado: true` no Firestore.

```http theme={null}
POST /auth/confirm-email
```

***

## Recuperação de senha

Envia o link de redefinição via Brevo. Por segurança, a resposta é sempre `200` independente de o e-mail existir ou não.

```http theme={null}
POST /auth/forgot-password
Content-Type: application/json

{
  "email": "usuario@email.com"
}
```

```json Resposta 200 theme={null}
{
  "message": "Se este e-mail estiver cadastrado, você receberá o link em instantes."
}
```

***

## Perfil do usuário autenticado

### Buscar perfil

```http theme={null}
GET /auth/perfil
```

### Atualizar perfil

Campos protegidos e ignorados mesmo que enviados: `userId`, `email`, `role`, `tipoPessoa`, `cpf`, `cnpj`, `criadoEm`, `emailVerificado`.

```http theme={null}
PATCH /auth/perfil
Content-Type: application/json

{
  "telefone": "(11) 98765-4321",
  "profissao": "Arquiteto"
}
```

***

## Erros de autenticação

| Status | Causa                                                               |
| ------ | ------------------------------------------------------------------- |
| `401`  | Cookie ausente, inválido ou expirado                                |
| `403`  | Cookie válido, mas conta desativada ou sem permissão para o recurso |

```json theme={null}
{ "error": "Sessão inválida ou expirada." }
```

<Warning>
  Como a autenticação usa cookie HttpOnly, ela **não funciona via ferramentas como Postman ou curl sem configuração adicional**. Para testar endpoints autenticados nessas ferramentas, faça o login primeiro e copie o valor do cookie `imob_session` da resposta.
</Warning>