cassel/bi-agents
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
96222aa6a2cb44014a400b3b72628cd2dbc97d64
bi-agents/docs/API.md
root 96222aa6a2 chore: adiciona Docker, scripts e documentacao 
- Adiciona Dockerfile e docker-compose para containerizacao
- Adiciona docker-entrypoint.sh com inicializacao
- Adiciona scripts/seed-admin.js para criar admin inicial
- Adiciona docs/ com logos originais CambioReal
- Atualiza README.md com instrucoes de uso
- Atualiza queries.js com metricas de portfólio

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-02-08 13:20:15 -05:00

6.3 KiB
Raw Blame History

API Reference - BI Agentes

Documentacao dos endpoints HTTP do sistema BI Agentes.

Base URL

http://localhost:3080

Autenticacao

O sistema usa autenticacao baseada em sessao. Apos login bem-sucedido, um cookie de sessao e enviado automaticamente pelo browser.

Cookie: connect.sid Duracao: 8 horas

Endpoints

GET /login

Exibe a pagina de login.

Autenticacao: Nao requerida

Comportamento:

  • Se usuario ja autenticado: redireciona para /dashboard
  • Se nao autenticado: retorna login.html

Response:

Status Descricao
200 Pagina HTML de login
302 Redirect para /dashboard (se ja logado)

Query Parameters:

Param Tipo Descricao
error number Se 1, exibe mensagem de erro

Exemplo:

GET /login HTTP/1.1
Host: localhost:3080

HTTP/1.1 200 OK
Content-Type: text/html

<!DOCTYPE html>
<html>...login form...</html>

POST /login

Processa tentativa de login.

Autenticacao: Nao requerida

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

Request Body:

Campo Tipo Obrigatorio Descricao
email string Sim Email do agente
senha string Sim Senha em texto plano

Response:

Status Descricao Redirect
302 Login bem-sucedido /dashboard
302 Login falhou /login?error=1

Comportamento:

  1. Busca agente por email no SQLite
  2. Compara senha com hash (bcrypt)
  3. Se valido, cria sessao com dados do agente
  4. Redireciona para dashboard

Exemplo:

POST /login HTTP/1.1
Host: localhost:3080
Content-Type: application/x-www-form-urlencoded

email=agente@cambioreal.com&senha=minhasenha123

HTTP/1.1 302 Found
Location: /dashboard
Set-Cookie: connect.sid=s%3A...; Path=/; HttpOnly

Dados da Sessao (interno):

req.session.agente = {
  id: 1,                    // ID interno SQLite
  email: "agente@email.com",
  agente_id: 76,            // ID do agente no RDS
  nome: "ValorFx"
}

GET /logout

Encerra a sessao do usuario.

Autenticacao: Nao requerida (mas so faz sentido se logado)

Response:

Status Descricao Redirect
302 Sessao destruida /login

Comportamento:

  1. Destroi sessao server-side
  2. Invalida cookie
  3. Redireciona para login

Exemplo:

GET /logout HTTP/1.1
Host: localhost:3080
Cookie: connect.sid=s%3A...

HTTP/1.1 302 Found
Location: /login
Set-Cookie: connect.sid=; Path=/; Expires=Thu, 01 Jan 1970 00:00:00 GMT

GET /dashboard

Exibe o dashboard de transacoes do agente.

Autenticacao: Requerida (cookie de sessao)

Response:

Status Descricao
200 Pagina HTML do dashboard
302 Redirect para /login (nao autenticado)
500 Erro ao carregar dados

Comportamento:

  1. Middleware requireAuth verifica sessao
  2. Busca agente_id da sessao
  3. Executa queries no RDS (BRL→USD e USD→BRL)
  4. Serializa e ordena dados
  5. Gera HTML com KPIs, graficos e tabela
  6. Retorna HTML completo

Dados Retornados no HTML:

O dashboard inclui dados embedded como JavaScript:

window.TRANSACOES = [
  {
    fluxo: "BRL → USD",
    cliente: "Cliente A",
    data_operacao: "2024-01-15 14:30",
    valor_reais: 10000.00,
    valor_dolar: 2000.00,
    iof_pct: 1.10,
    iof_valor_rs: 110.00,
    taxa_ptax: 4.95,
    taxa_cobrada: 5.00,
    spread_bruto: 0.05,
    spread_pct: 1.00,
    status: "completed"
  },
  // ... mais transacoes
];

Exemplo:

GET /dashboard HTTP/1.1
Host: localhost:3080
Cookie: connect.sid=s%3A...

HTTP/1.1 200 OK
Content-Type: text/html

<!DOCTYPE html>
<html>
<head><title>BI Agentes - Dashboard</title></head>
<body>
  <!-- KPIs, Graficos, Tabela -->
</body>
</html>

GET /

Redireciona para o dashboard.

Autenticacao: Nao requerida (redirect acontece primeiro)

Response:

Status Descricao Redirect
302 Redirect /dashboard

Exemplo:

GET / HTTP/1.1
Host: localhost:3080

HTTP/1.1 302 Found
Location: /dashboard

Arquivos Estaticos

GET /public/*

Serve arquivos estaticos da pasta public/.

Autenticacao: Nao requerida

Arquivos Disponiveis:

Path Arquivo
/public/login.html Pagina de login

Exemplo:

GET /public/login.html HTTP/1.1
Host: localhost:3080

Codigos de Erro

Codigo Significado Causa Comum
302 Redirect Login/logout, acesso nao autorizado
500 Erro interno Falha conexao RDS, erro de query

Middleware

requireAuth

Middleware que protege rotas que exigem autenticacao.

Comportamento:

function requireAuth(req, res, next) {
  if (req.session && req.session.agente) {
    return next();  // Continua para rota
  }
  res.redirect('/login');  // Redireciona
}

Rotas Protegidas:

  • GET /dashboard

Modelo de Dados (Sessao)

Agente (sessao)

interface AgenteSession {
  id: number;        // ID interno (SQLite)
  email: string;     // Email do agente
  agente_id: number; // ID no sistema RDS
  nome: string;      // Nome de exibicao
}

Exemplos de Uso

Fluxo Completo de Login

# 1. Tentar acessar dashboard (sera redirecionado)
curl -v http://localhost:3080/dashboard
# < HTTP/1.1 302 Found
# < Location: /login

# 2. Fazer login
curl -v -X POST http://localhost:3080/login \
  -d "email=agente@cambioreal.com" \
  -d "senha=minhasenha" \
  -c cookies.txt
# < HTTP/1.1 302 Found
# < Location: /dashboard
# < Set-Cookie: connect.sid=...

# 3. Acessar dashboard com cookie
curl -v http://localhost:3080/dashboard \
  -b cookies.txt
# < HTTP/1.1 200 OK
# < Content-Type: text/html

# 4. Fazer logout
curl -v http://localhost:3080/logout \
  -b cookies.txt
# < HTTP/1.1 302 Found
# < Location: /login

Futuras Extensoes

Endpoints planejados para proximas versoes:

Endpoint Metodo Descricao
/api/export GET Exportar transacoes (CSV/Excel)
/api/kpis GET KPIs em formato JSON
/api/transacoes GET Transacoes paginadas (JSON)