# API Reference — BI-CCC

Documentação dos endpoints HTTP do sistema BI-CCC.

## Base URL

```
http://localhost:3080
```

## Autenticação

O sistema usa autenticação baseada em sessão. Após login bem-sucedido, um cookie de sessão é enviado automaticamente pelo browser.

**Cookie:** `connect.sid`
**Duração:** 8 horas

---

## Endpoints de Autenticação

### POST /login

Processa tentativa de login.

**Content-Type:** `application/x-www-form-urlencoded`

| Campo | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| email | string | Sim | Email do usuário |
| senha | string | Sim | Senha em texto plano |

**Response:** `302` redirect para `/dashboard` (agente), `/corporate` (admin/corporate), ou `/login?error=1` (falha).

**Dados da Sessão:**
```javascript
req.session.agente = {
  id: 1,                    // ID interno SQLite
  email: "user@email.com",
  agente_id: 76,            // ID do agente no RDS (null para admin/corporate)
  nome: "Nome",
  role: "admin"             // admin | corporate | agente
}
```

### GET /logout

Destrói sessão e redireciona para `/login`.

---

## Páginas HTML (Server-Side Rendered)

Todas requerem autenticação via cookie de sessão.

| Rota | Role | Descrição |
|------|------|-----------|
| `GET /corporate` | admin, corporate | Corporate Dashboard |
| `GET /admin/bi` | admin | BI Executive Dashboard |
| `GET /admin/cliente` | admin | Client 360 |
| `GET /admin` | admin | Gestão de Usuários |
| `GET /admin/home` | admin | Daily Overview |
| `GET /admin/providers` | admin | Payment Providers |
| `GET /dashboard` | agente | Dashboard pessoal do agente |

---

## APIs REST — Corporate

Todas retornam JSON e requerem role `admin` ou `corporate`.

### GET /corporate/api/kpis

KPIs de hoje vs média 30 dias.

**Response:**
```json
{
  "hoje": { "total_ops": 42, "volume_brl": 500000, "volume_usd": 100000, "ticket_medio": 2380 },
  "media30d": { "total_ops": 35, "volume_brl": 420000, ... }
}
```

### GET /corporate/api/trend

Tendência dos últimos 30 dias (volume diário).

### GET /corporate/api/top-agentes

Top 5 agentes por volume.

| Param | Tipo | Default | Descrição |
|-------|------|---------|-----------|
| dias | number | 30 | Período em dias (7, 30, 90) |

### GET /corporate/api/kpis-period

KPIs por período customizado.

| Param | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| inicio | date | Sim | Data início (YYYY-MM-DD) |
| fim | date | Sim | Data fim (YYYY-MM-DD) |

### GET /corporate/api/trend-period

Tendência por período customizado.

| Param | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| inicio | date | Sim | Data início |
| fim | date | Sim | Data fim |

---

## APIs REST — BI Executive

Requerem role `admin`.

### GET /admin/api/bi

Dashboard BI completo: KPIs, tendências, ranking de agentes, retenção.

| Param | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| start | date | Sim | Data início (YYYY-MM-DD) |
| end | date | Sim | Data fim (YYYY-MM-DD) |

**Response:** Objeto com `kpis`, `kpisPrev`, `trend`, `topAgentes`, `topClientes`, `retention`.

### GET /admin/api/bi/revenue

Revenue analytics por produto com granularidade.

| Param | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| start | date | Sim | Data início |
| end | date | Sim | Data fim |
| granularity | string | Não | `day`, `month`, `year` (default: `month`) |

### GET /admin/api/bi/strategic

BI estratégico: cohort retention, revenue expansion/contraction, cross-sell, maturidade.

| Param | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| start | date | Sim | Data início |
| end | date | Sim | Data fim |

---

## APIs REST — Client 360

Requerem role `admin`.

### GET /admin/api/clientes/top

Top 20 clientes por volume total (lifetime).

### GET /admin/api/clientes/search

Busca clientes por nome.

| Param | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| q | string | Sim | Termo de busca (mín. 2 caracteres) |

### GET /admin/api/cliente/:id/profile

Profile lifetime do cliente: stats gerais, health score, merchant detection.

| Param | Tipo | Descrição |
|-------|------|-----------|
| id | number | `id_conta` do cliente |

### GET /admin/api/cliente/:id/data

Dados detalhados do cliente por período: KPIs, transações, timeline, insights.

| Param | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| id | number | Sim | `id_conta` do cliente |
| start | date | Sim | Data início |
| end | date | Sim | Data fim |

---

## APIs REST — Outras

### GET /api/cotacao

Cotação USD/BRL em tempo real (proxy para API externa AwesomeAPI).

**Autenticação:** Requerida (qualquer role)

**Response:**
```json
{
  "bid": "5.0123",
  "ask": "5.0234",
  "timestamp": "1706889600"
}
```

---

## Middleware

### requireAuth

Verifica se há sessão ativa. Redireciona para `/login` se não autenticado.

### requireRole(role)

Verifica se o usuário tem a role necessária. Retorna `403` se não autorizado. Admin tem acesso a todas as rotas.

---

## Códigos de Erro

| Código | Significado | Causa Comum |
|--------|-------------|-------------|
| 302 | Redirect | Login/logout, acesso não autorizado |
| 403 | Forbidden | Role insuficiente |
| 500 | Erro interno | Falha conexão RDS, erro de query |