Assistente financeiro pessoal via WhatsApp. Envie mensagens de texto, fotos de recibos ou extratos bancários em PDF para registrar despesas, entradas e transferências automaticamente. O assistente utiliza IA (Google Gemini) para interpretar as transações e armazená-las em um banco de dados PostgreSQL.
Você envia uma mensagem para si mesmo no WhatsApp — texto descrevendo um gasto, uma foto de recibo ou o PDF do extrato bancário — e o assistente registra as transações automaticamente.
Exemplos de mensagens:
"gastei 45 reais no almoço no pix""netflix 55 reais todo mês todo dia 15""cancelar netflix""recebi 6000 reais de salário""coloquei 2000 no cofrinho""quanto gastei em março?""exportar meus gastos de março"- Foto de um recibo ou nota fiscal
- PDF do extrato bancário (Itaú e outros)
O assistente classifica cada transação em três categorias:
| Tipo | Descrição | Exemplo |
|---|---|---|
| Despesa | Gasto real de dinheiro | Almoço, Netflix, conta de luz |
| Entrada | Dinheiro recebido | Salário, freelance, reembolso |
| Transferência | Movimentação entre contas próprias | Aplicação no cofrinho, resgate de CDB |
Transferências são excluídas dos totais de despesas e entradas — evitando que aplicações no cofrinho distorçam o resumo financeiro.
- Go — aplicação principal
- Google Gemini — análise e interpretação das mensagens
- Evolution API — integração com WhatsApp
- PostgreSQL — armazenamento das despesas
- Redis — cache da Evolution API
- Docker / Docker Compose — infraestrutura
- Docker com Docker Compose
- Chave de API do Google Gemini
- Conta no WhatsApp
git clone https://github.com/MarcosAAlbanoJunior/go-financial-assistant.git
cd go-financial-assistantCopie o arquivo de exemplo e preencha com suas informações:
cp .env.example .envEdite o .env:
PORT=3000
DATABASE_URL=postgres://finassist:finassist@localhost:5432/finassist?sslmode=disable
GEMINI_API_KEY=sua-chave-do-gemini
EVOLUTION_API_KEY=uma-chave-qualquer-para-proteger-a-api
EVOLUTION_API_URL=http://localhost:8082
EVOLUTION_INSTANCE=Financial Assistant
OWNER_PHONE=5511999999999
# Opcional — adicione aqui se o Evolution API usar um numero diferente do seu número (bug conhecido)
ALLOWED_NUMBERS=
# Senha para o endpoint /admin/qrcode (obrigatório para usar o endpoint em produção)
ADMIN_SECRET=sua-senha-segura| Variável | Descrição |
|---|---|
GEMINI_API_KEY |
Chave da API do Google Gemini — obtenha em aistudio.google.com |
EVOLUTION_API_KEY |
Chave para proteger a sua instância da Evolution API — pode ser qualquer valor |
EVOLUTION_INSTANCE |
Nome da instância no Evolution API |
OWNER_PHONE |
Seu número de WhatsApp com código do país e DDD, sem + ou espaços (ex: 5511999999999) |
ALLOWED_NUMBERS |
Opcional — número alternativo caso o Evolution API entregue seu número em formato diferente |
ADMIN_SECRET |
Senha para acessar o endpoint /admin/qrcode — defina um valor forte em produção |
docker compose up -d --build && docker compose logs -f appNa primeira execução, o assistente irá criar a instância no Evolution API automaticamente e exibir um QR code no terminal.
Basicamente o QR code vem dos logs do app em Go
Escaneie o QR code exibido no terminal com o seu WhatsApp:
WhatsApp → Aparelhos conectados → Conectar um aparelho → escaneie o QR code
Após escanear, o assistente estará pronto para uso.
Em execuções futuras, se o WhatsApp já estiver conectado, o QR code não será exibido.
Com o container rodando e o WhatsApp conectado, envie mensagens para si mesmo no WhatsApp.
gastei 45 reais no almoço no pix
comprei um tênis de 300 reais em 3x no cartão
netflix 55 reais todo mês todo dia 15
cancelar netflix
recebi 6000 reais de salário
entrou 500 reais de freela no pix
coloquei 2000 reais no cofrinho
resgatei 500 do CDB
Transferências não afetam despesas nem entradas — servem apenas para rastrear movimentações entre suas próprias contas.
quanto gastei esse mês?
quanto gastei em fevereiro?
O resumo mostra:
- Despesas por categoria
- Entradas totais (se houver)
- Resultado do mês (entradas − despesas)
- Investimentos no mês: quanto foi aplicado, quanto foi resgatado
- Em conta: resultado descontando o líquido que ficou investido
Envie o PDF do extrato do seu banco diretamente no WhatsApp. O assistente processa todas as transações automaticamente:
- Despesas, entradas e transferências são classificadas pela IA
- Aplicações no cofrinho e resgates de CDB são detectados como Transferência — não inflam as despesas
- Transações já existentes no banco são sinalizadas para confirmação individual
- Suporta o formato de extrato do Itaú (e outros formatos com datas DD/MM/AAAA ou AAAA-MM-DD)
Peça ao assistente para exportar os gastos de um mês e ele enviará um arquivo .csv diretamente no WhatsApp — pronto para abrir no Excel ou Google Sheets:
exportar meus gastos de março
me manda o csv de fevereiro 2024
quero a planilha de janeiro
exportar
- Se nenhum mês for especificado, exporta o mês atual.
- Se não houver lançamentos no período, o assistente avisa por texto.
- O arquivo vem com BOM UTF-8 para compatibilidade com Excel.
- Colunas: Data, Descrição, Categoria, Forma de Pagamento, Tipo, Parcela, Valor (R$).
- Linhas de totais ao final: TOTAL DESPESAS, TOTAL ENTRADAS (se houver), SALDO, TOTAL APLICADO / TOTAL RESGATADO (se houver transferências).
- A mensagem que acompanha o arquivo já traz o resumo financeiro: despesas, entradas, resultado, aplicado/resgatado e valor em conta.
O Gemini interpreta a intenção de exportação, então frases naturais como "quero ver meus gastos em planilha" ou "gera um csv pra mim" também funcionam.
No primeiro dia de cada mês, o assistente envia automaticamente a planilha CSV com todos os gastos do mês anterior — sem você precisar pedir.
Tire uma foto ou encaminhe a imagem do recibo diretamente no WhatsApp.
Abra no navegador substituindo pelo IP da sua VPS ou localhost se estiver rodando localmente:
http://<IP-DA-VPS-OU-LOCALHOST>:3000/admin/qrcode?token=sua-senha
Se o WhatsApp já estiver conectado, exibe uma mensagem de confirmação. Se não, exibe o QR code para escanear — a página atualiza automaticamente a cada 30 segundos.
Proteções implementadas:
- Requer
ADMIN_SECRETconfigurado (retorna503se vazio) - Rate limit de 10 requisições por minuto por IP
/webhookaceita conexões apenas do container Evolution API (verificação por IP via DNS interno do Docker)
# Subir e acompanhar logs da aplicação
docker compose up -d --build && docker compose logs -f app
# Ver logs em tempo real
docker compose logs -f app
# Parar os containers
docker compose down
# Parar e apagar todos os dados (banco, volumes)
docker compose down -v
# Acessar o banco de dados
docker compose exec postgres psql -U finassist -d finassistcmd/ entrypoint da aplicação
internal/
config/ carregamento de variáveis de ambiente
domain/ entidades e regras de negócio
usecase/ casos de uso (análise, recorrentes, consulta, exportação)
infra/
db/ repositório PostgreSQL
evolution/ cliente da Evolution API (WhatsApp)
gemini/ cliente do Google Gemini
http/ servidor HTTP e webhook handler
migrations/ scripts SQL de criação do banco
MIT