Gerenciador de finanças pessoais open source feito para brasileiros.
Sincroniza automaticamente com seus bancos via Open Finance (Pluggy), categoriza transações com IA e exibe tudo em um dashboard local bonito.
O FinanceBR é uma aplicação 100% local que:
- 🏦 Sincroniza com seus bancos via meu.pluggy.ai (Nubank, Itaú, Bradesco, BB, Santander, Inter, Caixa, C6 e mais de 150 instituições)
- 🤖 Categoriza automaticamente suas transações com regras inteligentes + IA (Groq / Llama 3.3 70B)
- 📊 Exibe um dashboard com receitas, despesas, evolução do saldo, gráficos por categoria e mais
- 🔒 Tudo fica na sua máquina — seus dados financeiros nunca saem do seu computador
Pense no FinanceBR como um Organizze/Guiabolso open source que roda localmente, sem mensalidade e sem vender seus dados.
O FinanceBR usa a plataforma Pluggy — a maior infraestrutura de Open Finance do Brasil, certificada pelo Banco Central e usada por fintechs como Nubank, XP, Stone, C6 e mais.
1. Crie uma conta gratuita em meu.pluggy.ai
2. Dentro do Pluggy, clique em "Adicionar conta" e selecione seu banco:
3. Faça o login no seu banco (o Pluggy usa OAuth/Open Finance — ele nunca vê sua senha, só um token de leitura)
4. Após conectar, volte para o terminal e execute o setup do FinanceBR — ele vai autenticar no Pluggy usando seu email e um magic link, e importar todas as suas contas e transações.
| Banco | Tipo |
|---|---|
| Nubank | Conta e Cartão |
| Itaú | Conta, Poupança e Cartão |
| Bradesco | Conta, Poupança e Cartão |
| Banco do Brasil | Conta e Poupança |
| Santander | Conta e Cartão |
| Caixa Econômica | Conta e Poupança |
| Inter | Conta e Cartão |
| C6 Bank | Conta e Cartão |
| XP Investimentos | Conta |
| BTG Pactual | Conta |
| + 150 instituições | Ver lista completa |
- Python 3.12+
- Node.js 18+
git clone https://github.com/helioneto144/financebr.git
cd financebrpython3 -m venv .venv
source .venv/bin/activate # Linux/Mac
# .venv\Scripts\activate # Windows
pip install -e .
playwright install chromium # Necessário para autenticar no Pluggycd frontend
npm install
npm run build
cd ..financebr setupO wizard interativo vai pedir:
| Dado | Onde obter | Onde é salvo |
|---|---|---|
| Email do meu.pluggy.ai | Sua conta em meu.pluggy.ai | ~/.financebr/config.json |
| Magic link | Email que o Pluggy envia | Usado para gerar cookies de sessão |
| Groq API Key | Gratuita em console.groq.com | ~/.financebr/config.json |
🔒 Segurança: Todos os dados (config, cookies, banco SQLite) ficam em
~/.financebr/no seu computador. Nada disso é enviado para a internet ou commitado no repositório.
financebr start
# → http://localhost:5666Abra o navegador em http://localhost:5666 e veja suas finanças! 🎉
financebr setup # Wizard de configuração inicial (faça isso primeiro!)
financebr start # Inicia o servidor web em http://localhost:5666
financebr start --dev # Modo dev com auto-reload
financebr sync # Sincronização manual com o Pluggy
financebr recategorize # Re-aplica as regras de categorização a todas as transações
financebr status # Exibe o status do último syncO FinanceBR usa um sistema de categorização em 5 camadas, do mais específico ao mais genérico:
1. Overrides de descrição → "Pagamento de Fatura Nubank" = Transferência
2. Mapa do Pluggy → Categoria da API do Pluggy (eating out, groceries...)
3. Refinamento por sinal → PIX positivo inesperado = Receita
4. Regras de regex (local) → "iFood" = Comida, "Uber" = Transporte
5. LLM (Groq Llama 3.3 70B) → Fallback para transações desconhecidas
As categorias do LLM são cacheadas localmente na tabela merchant_categories — cada estabelecimento só é categorizado via IA uma vez.
| Emoji | Categoria | Exemplos |
|---|---|---|
| 🍔 | Alimentação | iFood, restaurantes, lanchonetes |
| 🛒 | Supermercado | Carrefour, Pão de Açúcar, Extra |
| 🚗 | Transporte | Uber, 99, combustível, pedágio |
| 🏥 | Saúde | Farmácias, consultas, planos |
| 🎬 | Entretenimento | Netflix, Spotify, academia, games |
| 📦 | E-commerce | Amazon, Mercado Livre, Shopee |
| 🛍️ | Compras | Lojas físicas, shoppings |
| 📄 | Contas | Energia, internet, aluguel, escola |
| 💼 | Salário | Depósitos de salário |
| 💰 | Receita | Estornos, reembolsos, receitas extras |
| 💸 | Transferência | PIX, TED, pagamento de fatura |
| 📈 | Investimentos | Tesouro Direto, CDB, fundos |
| 📌 | Outros | Tudo que não se encaixa acima |
financebr/
├── backend/
│ ├── main.py # FastAPI app + configuração de rotas
│ ├── models.py # SQLAlchemy models (Account, Transaction, Category...)
│ ├── schemas.py # Pydantic schemas para a API
│ ├── database.py # Engine SQLite async + seed de categorias
│ ├── config.py # Leitura/escrita de ~/.financebr/config.json
│ ├── scheduler.py # APScheduler para sync periódico
│ ├── cli.py # CLI com Click (financebr setup/start/sync...)
│ ├── scraper/
│ │ ├── transactions.py # Playwright: scraping + interception da API do Pluggy
│ │ └── auth.py # Autenticação via magic link
│ ├── categorizer/
│ │ ├── rules.py # Regras regex + overrides de alta prioridade
│ │ └── llm.py # Integração Groq com cache de merchants
│ └── routers/
│ ├── accounts.py # GET /api/accounts
│ ├── transactions.py # GET/PATCH /api/transactions + summary/monthly/top
│ ├── categories.py # GET/POST /api/categories + breakdown
│ ├── sync.py # POST /api/sync + status/logs/debug
│ ├── insights.py # GET /api/insights (gerado por IA)
│ └── settings.py # GET/PATCH /api/settings
└── frontend/
└── src/
├── pages/
│ ├── DashboardPage.tsx # Dashboard principal
│ ├── TransactionsPage.tsx # Lista e filtragem de transações
│ └── ...
├── api/client.ts # Funções para chamar o backend
└── types/index.ts # Tipos TypeScript
| Camada | Tecnologia |
|---|---|
| Backend | Python 3.12 + FastAPI + SQLAlchemy async |
| Banco de dados | SQLite (aiosqlite) — fica em ~/.financebr/ |
| Scraper | Playwright (Chromium headless) |
| IA | Groq SDK → Llama 3.3 70B |
| Agendamento | APScheduler |
| Frontend | Vite + React 18 + TypeScript + Recharts |
| CLI | Click |
# Instalar dependências de teste
pip install pytest pytest-asyncio httpx
# Rodar os 105 testes
python -m pytest tests/ -v
# Resultado esperado:
# 105 passed in ~1.2sOs testes cobrem parsers de moeda/data brasileira, regras de categorização, todos os endpoints da API e casos de borda.
source .venv/bin/activate
uvicorn backend.main:app --reload --port 5666cd frontend
npm run dev # → http://localhost:5173 (proxy para :5666)financebr start --dev &
cd frontend && npm run devPull requests são muito bem-vindos! O FinanceBR é pensado para ser um projeto comunitário de brasileiros para brasileiros.
- Fork o repositório
- Crie uma branch para sua feature:
git checkout -b feature/minha-feature - Commit suas mudanças:
git commit -m 'feat: adiciona suporte a X' - Push para sua branch:
git push origin feature/minha-feature - Abra um Pull Request com uma descrição clara do que foi feito
- 🏦 Mais regras de categorização — conhece um estabelecimento que está sendo mal-categorizado? Adicione uma regra em
backend/categorizer/rules.py! - 🐛 Bug reports — abra uma Issue com o máximo de detalhes possível
- 💡 Novas features — discuta no Discussions antes de implementar
- 🧪 Mais testes — cobertura nunca é demais
- 📱 UI/UX melhorias — ideias pro dashboard ou para novas páginas
- 📖 Documentação — melhorias neste README ou wiki
Usamos Conventional Commits:
feat: nova funcionalidade
fix: correção de bug
docs: atualização de documentação
test: adição ou correção de testes
refactor: refatoração sem mudança de comportamento
chore: tarefas de manutenção
Ao abrir uma Issue de bug, inclua:
- Versão do Python (
python --version) - Sistema operacional
- Trecho do log de erro (encontrado com
financebr statusou no terminal) - Passos para reproduzir o problema
Q: Minhas senhas ficam guardadas no app?
A: Não. O FinanceBR usa o Pluggy como intermediário via Open Finance. Você autentica no seu banco diretamente pelo site do Pluggy, e o FinanceBR recebe apenas um token de leitura. Sua senha nunca passa pelo FinanceBR.
Q: Meus dados vão para a nuvem?
A: Não. O banco SQLite e as configurações ficam exclusivamente em ~/.financebr/ na sua máquina. A única comunicação externa é: (1) com o meu.pluggy.ai para buscar transações e (2) com a API do Groq para categorizar transações desconhecidas.
Q: Preciso de uma conta paga no Groq?
A: Não. O plano gratuito do Groq é suficiente — ele oferece tokens mais que suficientes para categorizar novas transações. Após a primeira categorização de cada estabelecimento, o resultado é cacheado localmente e não consome mais tokens.
Q: A sessão do Pluggy expira?
A: Sim, eventualmente. Quando isso acontecer, o sync vai falhar com erro de autenticação. Execute financebr setup novamente para renovar a sessão.
Q: Posso rodar em um servidor/Raspberry Pi?
A: Sim! O backend roda em qualquer Python 3.12+. O Playwright (necessário para autenticação) requer uma instalação do Chromium — playwright install chromium instala automaticamente.
MIT © Hélio Neto — use, modifique e distribua à vontade.
Feito com ❤️ no Brasil 🇧🇷
⭐ Star o projeto se ele te ajudou!
🐛 Abrir Issue · 💬 Discussions · 🔀 Pull Request