TaxHacker: Monte seu sistema de contabilidade com IA a custo zero

March 21, 2026

Dificuldade: ★★☆☆☆ | Duração: 15 minutos | Ganho: Domine a implantação e as funções principais de um aplicativo de contabilidade com IA auto-hospedado

Público-alvo: Desenvolvedores individuais, freelancers, proprietários de pequenas empresas e entusiastas de tecnologia interessados em automação de gestão financeira.

Dependências principais: Docker, Docker Compose, LLM API (OpenAI/Gemini/Mistral)

1 Introdução ao Projeto

Vamos falar primeiro sobre o projeto TaxHacker.

O TaxHacker é um aplicativo de contabilidade com IA de código aberto e auto-hospedado, projetado especificamente para freelancers, pequenas empresas e desenvolvedores individuais. Seu principal diferencial é: usar IA para identificar e extrair automaticamente dados financeiros de faturas e recibos, transformando o tedioso trabalho de contabilidade manual em algo que pode ser resolvido com um clique.

Você pode perguntar: com tantos softwares financeiros no mercado, por que usar este? Aqui estão alguns motivos:

  • Reconhecimento Inteligente por IA: Carregue a foto de um recibo e a IA extrai automaticamente o nome do item, valor, data, estabelecimento, etc., reconhecendo até faturas manuscritas.
  • Suporte Multi-moedas: Suporta mais de 170 moedas fiduciárias e 14 criptomoedas, com conversão automática baseada na taxa de câmbio histórica da data da transação.
  • 100% Auto-hospedado: Os dados ficam no seu próprio servidor, a privacidade está totalmente sob seu controle, sem preocupações com vazamento de dados financeiros.
  • Gratuito e Open Source: Licença MIT, custo zero de licenciamento.

Este projeto foi construído com Next.js 15 + Prisma + PostgreSQL. A implantação via Docker é muito simples e pode ser executada em 15 minutos.

2 Preparação do Ambiente

Antes de começarmos a implantação, verifique seu ambiente.

2.1 Requisitos de Hardware

  • Memória: Pelo menos 4GB RAM (8GB recomendado)
  • Armazenamento: Pelo menos 10GB de espaço livre (para armazenar imagens de faturas enviadas)
  • Sistema: Linux/macOS/Windows (requer suporte a Docker)

2.2 Requisitos de Software

Você precisará instalar os seguintes softwares:

  • Docker Engine 20.10+
  • Docker Compose 2.0+

TIP

Para usuários Windows, recomenda-se o uso de WSL2 + Docker Desktop, que é a combinação mais estável.

2.3 Preparação da API de LLM

O TaxHacker suporta três provedores de LLM:

  • OpenAI (GPT-4o recomendado)
  • Google Gemini
  • Mistral

Você precisará de uma chave de API (API Key) para que a IA identifique as faturas. Se quiser economizar, considere a plataforma Defapi — ela oferece APIs dos principais LLMs pela metade do preço oficial, suporta OpenAI, Claude, Gemini, etc., e é totalmente compatível com o protocolo da API da OpenAI.

3 Estrutura do Projeto

Antes da implantação, vamos dar uma olhada na estrutura geral do projeto:

TaxHacker/
├── app/                    # Aplicativo Next.js
│   ├── (app)/             # Rotas principais do app
│   │   ├── dashboard/    # Painel de controle
│   │   ├── transactions/ # Registros de transações
│   │   ├── settings/      # Página de configurações
│   │   └── ...
│   └── api/              # Rotas de API
├── ai/                    # Lógica central de IA
│   ├── analyze.ts        # Analisar recibos
│   ├── prompt.ts         # Modelos de prompts
│   └── providers/        # Provedores de LLM
├── prisma/               # Modelos de banco de dados
├── docker-compose.yml    # Configuração de orquestração Docker
├── Dockerfile            # Definição de imagem Docker
└── .env.example          # Exemplo de variáveis de ambiente

4 Implantação com um clique via Docker

Agora vamos começar formalmente a implantação. O método Docker é o mais simples, podendo ser executado com um único comando.

4.1 Baixar Arquivos de Configuração

# Criar diretório do projeto
mkdir -p taxhacker && cd taxhacker

# Baixar docker-compose.yml
curl -O https://raw.githubusercontent.com/vas3k/TaxHacker/main/docker-compose.yml

# Baixar modelo de variáveis de ambiente
curl -O https://raw.githubusercontent.com/vas3k/TaxHacker/main/.env.example

4.2 Configurar Variáveis de Ambiente

# Copiar arquivo de variáveis de ambiente
cp .env.example .env

Abra o .env com seu editor favorito e preencha as seguintes configurações críticas:

# Configurações básicas
PORT=7331
BASE_URL=http://localhost:7331
SELF_HOSTED_MODE=true

# Configuração do banco de dados (usando o PostgreSQL do docker-compose)
DATABASE_URL=postgresql://postgres:postgres@db:5432/taxhacker

# Caminho de armazenamento de arquivos
UPLOAD_PATH=/app/data/uploads

# Chave secreta de autenticação (mínimo 16 caracteres)
BETTER_AUTH_SECRET=sua-chave-super-secreta-altere-isso

# Desativar registro (recomendado para modo auto-hospedado)
DISABLE_SIGNUP=true

# Configuração de LLM (exemplo OpenAI)
OPENAI_MODEL_NAME=gpt-4o
OPENAI_API_KEY=sua-chave-api-openai-aqui

# Ou use o Google Gemini
# GOOGLE_MODEL_NAME=gemini-2.0-flash
# GOOGLE_API_KEY=sua-chave-api-gemini-aqui

WARNING

Certifique-se de alterar o BETTER_AUTH_SECRET para uma string aleatória complexa, caso contrário, a segurança não poderá ser garantida.

4.3 Iniciar os Serviços

# Iniciar todos os serviços
docker compose up -d

A primeira inicialização criará automaticamente o banco de dados PostgreSQL e executará as migrações, o que leva cerca de 1-2 minutos.

4.4 Verificar a Implantação

# Verificar status dos containers
docker compose ps

# Ver logs
docker compose logs -f app

Se tudo estiver normal, ao acessar http://localhost:7331 você deverá ver a página de login.

5 Configurações Básicas

Após o início do serviço, precisamos concluir algumas configurações básicas.

5.1 Primeiro Login

No modo auto-hospedado, o TaxHacker cria automaticamente uma conta de administrador. O login padrão é:

  • E-mail: admin@localhost
  • Senha: admin

WARNING

Altere a senha padrão imediatamente após o primeiro login!

5.2 Configurar LLM

Clique em Settings → LLM no canto inferior esquerdo e confirme se sua API Key está configurada corretamente. Você pode testar se a IA está funcionando nesta página:

Test AI Connection: [Clique para Testar]

Se retornar sucesso, significa que o LLM está configurado.

5.3 Definir Moeda Base

Em Settings → Currencies, defina sua moeda base. Sugiro definir como Real (BRL) ou sua moeda de uso frequente.

5.4 Criar Categorias

Em Settings → Categories, crie as categorias de despesas/receitas que você precisa, como:

  • Alimentação
  • Transporte
  • Material de Escritório
  • Serviços de Software
  • Outras Receitas

6 Prática das Funções Principais

Com o ambiente configurado, vamos ver como usar a IA para identificar faturas.

6.1 Upload do Primeiro Recibo

Vá para a área Unsorted (Não classificados) na página inicial, clique no botão Upload e envie a imagem de um recibo ou uma fatura em PDF.

Formatos suportados: JPG, PNG, PDF

Após o upload, você verá uma prévia do arquivo.

6.2 Identificação Automática por IA

Clique no botão Analyze ao lado do arquivo e a IA começará a analisar seu recibo. Após alguns segundos, você verá o resultado da extração:

{
  "date": "2026-03-15",
  "merchant": "Starbucks Coffee",
  "amount": 35.00,
  "currency": "BRL",
  "items": [
    { "name": "Latte", "quantity": 1, "price": 30.00 },
    { "name": "Guardanapo", "quantity": 1, "price": 5.00 }
  ],
  "category": "Alimentação"
}

Se o resultado estiver incorreto, você pode editar e corrigir manualmente.

6.3 Confirmar e Salvar

Após confirmar que os dados estão corretos, clique em Confirm, e esta transação entrará em seu livro de registros.

6.4 Conversão Automática de Multi-moedas

Se você carregar uma fatura em moeda estrangeira, como Dólar ou Euro, o TaxHacker irá automaticamente:

  1. Identificar o tipo de moeda
  2. Obter a taxa de câmbio histórica da data da transação
  3. Converter para a moeda base

Você pode ver a lista de moedas suportadas em Settings → Currencies, incluindo criptomoedas como BTC, ETH, etc.

6.5 Campos Personalizados

Se você tiver necessidades especiais de extração, pode criar campos personalizados em Settings → Fields. Por exemplo, se quiser extrair o CNPJ da fatura:

  1. Clique em Add Field
  2. Nome do campo: CNPJ
  3. Preencha o prompt de extração da IA: Por favor, extraia o número de identificação fiscal/CNPJ da fatura
  4. Salvar

Na próxima vez que analisar uma fatura, a IA tentará extrair esse campo automaticamente.

7 Exportação e Backup de Dados

Um dos pontos mais importantes da contabilidade é a portabilidade dos dados, e o TaxHacker faz isso muito bem.

7.1 Filtro e Exportação

Na página Transactions, você pode filtrar por data, categoria, projeto, etc.:

  • Intervalo de datas: 01/01/2026 a 21/03/2026
  • Categorias: Alimentação, Transporte
  • Valor: > 100

Após filtrar, clique em Export CSV para exportar os registros de transações com todos os anexos.

7.2 Backup Completo

Em Settings → Backups, você pode criar um backup completo dos dados, incluindo:

  • Snapshot do banco de dados
  • Todos os arquivos enviados
  • Informações de configuração

O arquivo de backup pode ser baixado localmente para garantir a segurança dos dados.

8 Solução de Problemas Comuns

Durante a implantação e o uso, você pode encontrar estes problemas:

Q1: Falha ao iniciar o container, erro de conexão com banco de dados

Verifique se o DATABASE_URL no docker-compose.yml está correto. A configuração padrão usa db como nome do host (rede interna do Docker); se você personalizou o banco de dados, precisará ajustar adequadamente.

Q2: A análise da IA fica travada em "Processando"

Primeiro, verifique se a API Key do LLM está configurada corretamente. Em seguida, verifique os logs do container:

docker compose logs app | grep -i error

Se vir um erro de "rate limit", significa que o limite de chamadas da API foi atingido.

Q3: Erro de "Arquivo muito grande" ao fazer upload

O limite padrão é de 10MB. Se precisar enviar arquivos maiores, altere o .env:

MAX_FILE_SIZE=20971520  # 20MB

Depois reinicie o serviço: docker compose restart

Q4: Reconhecimento do recibo impreciso

Você pode personalizar o prompt do sistema em Settings → LLM para dar mais contexto à IA. Por exemplo, se você for do setor de alimentação, pode adicionar:

Você é um contador profissional do setor de alimentação, especialista em identificar formatos de recibos de diversos restaurantes e lanchonetes.

Q5: Como alterar a senha de login

Após o login, clique no avatar no canto superior direito → Profile, onde poderá alterar a senha e o e-mail.

Q6: Esqueci a senha de administrador, o que fazer?

Será necessário resetar via banco de dados. Conecte-se ao container PostgreSQL:

docker exec -it taxhacker-db-1 psql -U postgres -d taxhacker

Em seguida, execute:

UPDATE users SET password_hash = 'novo_hash_de_senha' WHERE email = 'admin@localhost';

9 Direções Avançadas

Depois de dominar as funções básicas, você pode explorar estas opções avançadas:

9.1 Personalização de Prompts da IA

O TaxHacker permite personalizar profundamente o comportamento da IA. Em Settings → LLM, altere o prompt do sistema para que a IA extraia dados de acordo com as normas do seu setor.

9.2 Gestão de Múltiplos Projetos

Crie diferentes projetos em Settings → Projects, como "Projeto A" e "Projeto B", permitindo estatísticas de receitas e despesas por projeto, ideal para freelancers com múltiplas linhas de negócio.

9.3 Integração com OpenClaw para Automação

Se você também implantou o OpenClaw, pode fazer com que ele chame periodicamente a API do TaxHacker para processar automaticamente recibos não classificados, alcançando uma contabilidade verdadeiramente sem intervenção humana.

9.4 Backups Automáticos Agendados

Use um cronjob para chamar a API de backup periodicamente:

0 2 * * * curl -X POST http://localhost:7331/api/backups

Isso criará um backup automaticamente todas as madrugadas.

Updated March 21, 2026