Cassel
647cbec54f
- Rewrite README.md with current architecture, features and stack - Update docs/API.md with all current endpoints (corporate, BI, client 360) - Update docs/ARCHITECTURE.md with cache, modular queries, services, ETL - Update docs/GUIA-USUARIO.md for all roles (admin, corporate, agente) - Add docs/INDEX.md documentation index - Add PROJETO.md comprehensive project reference - Add BI-CCC-Implementation-Guide.md - Include AI agent configs (.claude, .agents, .gemini, _bmad) - Add netbird VPN configuration - Add status report Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
226 lines
5.4 KiB
Markdown
226 lines
5.4 KiB
Markdown
# 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 |
|