Files

Cassel 647cbec54f docs: update all documentation and add AI tooling configs

- 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>

2026-03-19 13:29:03 -04:00

5.4 KiB

Raw Blame History

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

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:

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:

{
  "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)