Sistema de Contabilidade Pessoal com Beancount - Documentação Completa

CLAUDE_sanitized.md

Sistema de Contabilidade Pessoal com Beancount

Visão Geral

Sistema de contabilidade pessoal por partidas dobradas usando Beancount + Fava. Gerencia contas de múltiplos membros da família. Python 3.12, gerenciado com Pipenv.

Comandos Úteis

# Instalar dependências
pipenv install

# Rodar testes
pipenv run pytest

# Extrair transações de CSVs/OFXs baixados
./extract_transactions_from_csv.sh

# Importar Nubank via API
python -m importers.nubank.nubank_api_importer

# Abrir interface Fava
fava transactions.beancount

Arquivos Beancount

• transactions.beancount - Livro-razão principal. Inclui os outros via include.
• 2019.beancount - Histórico desde 2017. Definição de moedas (BRL, USD, VOO, SELIC, BTC) e abertura de contas antigas.
• prices.beancount - Cotações de commodities separadas do livro principal.

Importadores Disponíveis

Banco Inter

• importers/inter/importer.py - Extratos e faturas CSV
• Classes: ExtractImporter{Pessoa1,Pessoa2,Pessoa3}, FaturaImporter{Pessoa1,Pessoa2}

Nubank

• importers/nubank/nubank_ofx_importer.py - Fatura via OFX com categorização automática (434 regras)
• importers/nubank/nubank_api_importer.py - Importação via API pynubank com categorização por tags
• Gera: out_personal.txt e out_pythonpro.txt

Telegram (Novos)

• importers/telegram/reconcile_ofx.py - Conciliação OFX via Telegram
• importers/telegram/reconcile_inter_csv.py - Conciliação CSV Inter via Telegram
• Ver gist: https://gist.github.com/renzon/f502114d4308eba40a0a8139f0807bce

Configuração

• config.py - Registra todos os importadores para uso com bean-extract / bean-file

Nomes de Arquivos Esperados

Importador	Arquivo esperado
ExtractImporterPessoa1	ExtratoPessoa1.csv
ExtractImporterPessoa2	ExtratoPessoa2.csv
ExtractImporterPessoa3	ExtratoPessoa3.csv
FaturaImporterPessoa1	FaturaPessoa1.csv
FaturaImporterPessoa2	FaturaPessoa2.csv
CreditCardImporter (Nubank)	Nubank_YYYY-MM-DD.ofx

Estrutura de Contas Beancount

Assets (Ativos)

• Assets:Caixa:Inter:{Pessoa} - Contas correntes Banco Inter
• Assets:Caixa:Nubank:{Pessoa} - Contas correntes Nubank
• Assets:Investimentos:RendaFixa:Nubank:{Pessoa} - RDB/Caixinhas Nubank
• Assets:Investimentos:Inter:EUA:{Pessoa}:Cash - Conta Global Inter (USD)
• Assets:Investimentos:Inter:EUA:{Ticker}:{Pessoa} - Ações/ETFs
• Assets:Recebiveis:{Nome} - Empréstimos a receber

Liabilities (Passivos)

• Liabilities:Cartoes:Inter:{Pessoa} - Cartões de crédito Inter
• Liabilities:Cartoes:Nubank - Cartão de crédito Nubank

Expenses (Despesas)

• Expenses:Mercado - Supermercado, feira
• Expenses:Restaurante - Alimentação fora de casa
• Expenses:Casa - Aluguel, utilidades, manutenção
• Expenses:Lazer - Entretenimento, viagens
• Expenses:Transporte:Carro - Combustível, estacionamento, manutenção
• Expenses:Transporte:Uber - Uber, 99, etc
• Expenses:Transporte:Moto - Manutenção moto
• Expenses:Familia:{Pessoa} - Gastos pessoais específicos
• Expenses:Familia:Filhos - Escola, brinquedos, roupas infantis
• Expenses:Familia:Saude - Plano de saúde, médicos, farmácia
• Expenses:Familia:Mae - Gastos com mãe
• Expenses:Cachorro - Pet shop, veterinário
• Expenses:Faxina - Serviços de limpeza
• Expenses:Impostos:IR - Imposto de renda
• Expenses:SeguroDeVida - Seguros
• Expenses:Unknown - Transações não categorizadas (força revisão)

Income (Receitas)

• Income:Work:MEI:{Pessoa} - Receita MEI
• Income:Work:PythonPro:{Pessoa}:{ProLabore|Distribuicao} - PythonPro
• Income:Work:DevPro:{Pessoa}:{ProLabore|Distribuicao} - DevPro
• Income:Business:Investimentos:RendaFixa:Nubank:{Pessoa} - Juros RDB
• Income:Business:Nubank:Desconto - Descontos antecipação

Regras de Categorização

Exemplos de Mapeamentos

Padrão na Descrição	Conta	Tipo
ESCOLA MOPPE LTDA	Expenses:Familia:Filhos	Escola
PORTO SEGURO	Expenses:Familia:Saude	Plano de saúde
RECEITA FEDERAL	Expenses:Impostos:IR	IR
Pagamento fatura cartao	Liabilities:Cartoes:Inter:{Pessoa}	Pagamento fatura
Detran	Expenses:Transporte:Carro	IPVA, licenciamento
MUNICIPIO DE ...	Expenses:Casa	IPTU
EDP	Expenses:Casa	Energia elétrica
Nomes de pessoas na fatura	Expenses:Mercado	Feirantes
Shopping, lojas de roupa	Expenses:Familia:{Pessoa}	Compras pessoais
Parques de diversão	Expenses:Familia:Filhos	Entretenimento infantil
BIG JUMP, RI HAPPY	Expenses:Familia:Filhos	Brinquedos/parques
Esmalteria, cabeleireiro	Expenses:Familia:{Pessoa}	Beleza
POPULAR PET	Expenses:Cachorro	Pet shop
Pix entre contas próprias	Assets:Caixa:{Banco}:{Pessoa}	Transferência interna

Regras Gerais

1. Destinatário desconhecido: usar Expenses:Unknown e marcar transação com ! (flag de revisão)
2. Transferências internas: usar conta da outra pessoa como contrapartida
3. Pagamentos de fatura: usar Liabilities:Cartoes:... correspondente
4. Balance assertions: incluir no final do extrato
5. Parcelas: Importador Inter lança valor total na parcela 1/N, ignora parcelas seguintes

Detecção de Duplicatas

• Nubank OFX: usa nubank_id no metadata
• Inter CSV: usa combinação data + descrição + valor
• Telegram importers: detectam automaticamente transações já lançadas

Convenções do Projeto

• Moeda operacional: BRL
• Pró-labore fixo: R$ 1.100 (diferencia de distribuição)
• Parcelas: Importador lança valor total na primeira parcela
• Pagamentos "PAGAMENTO ON LINE": ignorados (já aparecem no extrato)
• Conta Expenses:Unknown: NÃO é aberta propositalmente para forçar revisão

Fluxo de Trabalho

1. Importação Manual (bean-extract)

# Extrair transações dos arquivos baixados
bean-extract config.py Downloads/ -e transactions.beancount > out.txt

# Revisar e editar out.txt conforme necessário

# Adicionar ao ledger
cat out.txt >> transactions.beancount

# Validar
bean-check transactions.beancount

2. Importação via Telegram (Novo)

1. Enviar arquivo OFX ou CSV para o bot
2. Bot processa e mostra preview com categorização
3. Confirmar ou cancelar
4. Bot adiciona ao ledger automaticamente

Ver: https://gist.github.com/renzon/f502114d4308eba40a0a8139f0807bce

3. Arquivamento (bean-file)

# Arquivar documentos importados
bean-file config.py Downloads/ -o .

4. Visualização (Fava)

# Abrir interface web
fava transactions.beancount
# Acesse: http://localhost:5000

Estrutura de Diretórios

.
├── transactions.beancount       # Ledger principal
├── 2019.beancount              # Histórico antigo
├── prices.beancount            # Cotações
├── config.py                   # Config bean-extract
├── importers/
│   ├── inter/
│   │   └── importer.py        # Inter CSV
│   ├── nubank/
│   │   ├── nubank_ofx_importer.py
│   │   └── nubank_api_importer.py
│   └── telegram/              # Novos importadores
│       ├── reconcile_ofx.py
│       ├── reconcile_inter_csv.py
│       └── README.md
├── Assets/                     # Arquivos arquivados
│   └── Caixa/Inter/{Pessoa}/
├── Liabilities/
│   └── Cartoes/
│       ├── Inter/{Pessoa}/
│       └── Nubank/
└── out_csv.txt                # Output temporário

Links Úteis

• Beancount: https://beancount.github.io/docs/
• Fava: https://github.com/beancount/fava
• Importadores Telegram: https://gist.github.com/renzon/f502114d4308eba40a0a8139f0807bce
• Importador Inter: https://gist.github.com/renzon/9304614017d7ed01ef70a6839d7a5c84
• Importador Nubank OFX: https://gist.github.com/renzon/6d90ccfee88731259e52292f7c07ac10

Regras do Projeto

• NUNCA comitar sem pedido explícito do usuário
• Idioma dos commits e mensagens: português
• Validar com bean-check antes de comitar
• Manter documentação atualizada