Dificultad: ★★☆☆☆ | Duración: 15 minutos | Resultado: Dominar el despliegue y las funciones principales de una aplicación de contabilidad con IA autohospedada
Público objetivo: Desarrolladores individuales, freelancers, dueños de pequeñas empresas y entusiastas de la tecnología interesados en la automatización de la gestión financiera.
Dependencias principales: Docker, Docker Compose, API de LLM (OpenAI/Gemini/Mistral)
1 Introducción al proyecto
Hablemos primero de TaxHacker.
TaxHacker es una aplicación de contabilidad con IA de código abierto y autohospedada, diseñada específicamente para freelancers, pequeñas empresas y desarrolladores individuales. Su principal propuesta de valor es: utilizar la IA para identificar y extraer automáticamente datos financieros de facturas y recibos, convirtiendo las tediosas tareas de registro manual en un proceso de un solo clic.
Te preguntarás: con tantos softwares financieros en el mercado, ¿por qué usar este? Aquí tienes algunas razones:
- Reconocimiento inteligente por IA: Sube una foto de un recibo y la IA extraerá automáticamente el nombre del producto, importe, fecha, comercio, etc., reconociendo incluso notas manuscritas.
- Soporte multidivisa: Admite más de 170 monedas fiduciarias y 14 criptomonedas, con conversión automática basada en tipos de cambio históricos según la fecha de la transacción.
- 100% Autohospedado: Los datos residen en tu propio servidor. Tienes el control total de tu privacidad sin preocuparte por filtraciones de datos financieros.
- Gratis y de código abierto: Licencia MIT, sin costes de licencia.
Este proyecto está construido con Next.js 15 + Prisma + PostgreSQL. El despliegue con Docker es muy sencillo y puede estar funcionando en 15 minutos.
2 Preparación del entorno
Antes de comenzar el despliegue, confirma los requisitos de tu entorno.
2.1 Requisitos de hardware
- Memoria: Al menos 4GB de RAM (8GB recomendados)
- Almacenamiento: Al menos 10GB de espacio disponible (para almacenar las imágenes de las facturas subidas)
- Sistema: Linux/macOS/Windows (requiere soporte para Docker)
2.2 Requisitos de software
Necesitas instalar lo siguiente:
- Docker Engine 20.10+
- Docker Compose 2.0+
TIP
Para usuarios de Windows, se recomienda usar WSL2 + Docker Desktop, que es la combinación más estable.
2.3 Preparación de la API de LLM
TaxHacker admite tres proveedores de LLM:
- OpenAI (se recomienda GPT-4o)
- Google Gemini
- Mistral
Necesitas una API Key para que la IA identifique las facturas. Si quieres ahorrar costes, puedes considerar la plataforma Defapi, que ofrece APIs de los principales LLM a mitad de precio oficial, compatible con OpenAI, Claude, Gemini, etc., y totalmente compatible con el protocolo de API de OpenAI.
3 Estructura del proyecto
Antes del despliegue, echemos un vistazo a la estructura general del proyecto:
TaxHacker/
├── app/ # Aplicación Next.js
│ ├── (app)/ # Rutas principales de la aplicación
│ │ ├── dashboard/ # Panel de control
│ │ ├── transactions/ # Registros de transacciones
│ │ ├── settings/ # Página de ajustes
│ │ └── ...
│ └── api/ # Rutas de la API
├── ai/ # Lógica central de IA
│ ├── analyze.ts # Análisis de recibos
│ ├── prompt.ts # Plantillas de prompts
│ └── providers/ # Proveedores de LLM
├── prisma/ # Modelos de base de datos
├── docker-compose.yml # Configuración de orquestación de Docker
├── Dockerfile # Definición de imagen Docker
└── .env.example # Ejemplo de variables de entorno
4 Despliegue con Docker en un clic
Comenzamos formalmente el despliegue. El método Docker es el más sencillo; se puede ejecutar con un solo comando.
4.1 Descargar archivos de configuración
# Crear directorio del proyecto
mkdir -p taxhacker && cd taxhacker
# Descargar docker-compose.yml
curl -O https://raw.githubusercontent.com/vas3k/TaxHacker/main/docker-compose.yml
# Descargar plantilla de variables de entorno
curl -O https://raw.githubusercontent.com/vas3k/TaxHacker/main/.env.example
4.2 Configurar variables de entorno
# Copiar archivo de variables de entorno
cp .env.example .env
Abre .env con tu editor favorito y rellena las siguientes configuraciones clave:
# Configuración base
PORT=7331
BASE_URL=http://localhost:7331
SELF_HOSTED_MODE=true
# Configuración de base de datos (usando el PostgreSQL incluido en docker-compose)
DATABASE_URL=postgresql://postgres:postgres@db:5432/taxhacker
# Ruta de almacenamiento de archivos
UPLOAD_PATH=/app/data/uploads
# Clave secreta de autenticación (al menos 16 caracteres)
BETTER_AUTH_SECRET=tu-clave-super-secreta-cambia-esto
# Deshabilitar registro (recomendado en modo autohospedado)
DISABLE_SIGNUP=true
# Configuración de LLM (ejemplo con OpenAI)
OPENAI_MODEL_NAME=gpt-4o
OPENAI_API_KEY=tu-api-key-de-openai-aqui
# O usar Google Gemini
# GOOGLE_MODEL_NAME=gemini-2.0-flash
# GOOGLE_API_KEY=tu-api-key-de-gemini-aqui
WARNING
Asegúrate de cambiar BETTER_AUTH_SECRET por una cadena aleatoria compleja; de lo contrario, la seguridad no estará garantizada.
4.3 Iniciar el servicio
# Iniciar todos los servicios
docker compose up -d
La primera ejecución creará automáticamente la base de datos PostgreSQL y ejecutará las migraciones, lo que tardará de 1 a 2 minutos.
4.4 Verificar el despliegue
# Ver estado de los contenedores
docker compose ps
# Ver logs
docker compose logs -f app
Si todo es correcto, al visitar http://localhost:7331 deberías ver la página de inicio de sesión.
5 Configuración básica
Una vez iniciado el servicio, debemos completar algunas configuraciones básicas.
5.1 Primer inicio de sesión
En modo autohospedado, TaxHacker crea automáticamente una cuenta de administrador. Las credenciales por defecto son:
- Email: admin@localhost
- Contraseña: admin
WARNING
¡Por favor, cambia la contraseña por defecto inmediatamente después del primer inicio de sesión!
5.2 Configurar LLM
Haz clic en Settings (Ajustes) en la esquina inferior izquierda → LLM, y confirma que tu API Key está configurada correctamente. Puedes probar si la IA funciona en esta página:
Test AI Connection: [Clic para probar]
Si devuelve un éxito, significa que el LLM está configurado.
5.3 Establecer moneda base
En Settings → Currencies (Monedas), establece tu moneda base. Recomiendo configurarla en tu moneda local habitual (por ejemplo, EUR o USD).
5.4 Crear categorías
En Settings → Categories, crea las categorías de gastos/ingresos que necesites, por ejemplo:
- Restauración
- Transporte
- Material de oficina
- Servicios de software
- Otros ingresos
6 Funciones principales en acción
Con el entorno configurado, veamos cómo usar la IA para identificar facturas.
6.1 Subir el primer recibo
Ve a la sección Unsorted (Sin clasificar) de la página principal, haz clic en el botón Upload y sube una imagen de recibo o una factura en PDF.
Formatos de archivo admitidos: JPG, PNG, PDF.
Tras la subida, verás una vista previa del archivo.
6.2 Identificación automática por IA
Haz clic en el botón Analyze (Analizar) junto al archivo. La IA comenzará a analizar tu recibo. Tras unos segundos, verás los resultados extraídos:
{
"date": "2026-03-15",
"merchant": "Starbucks Coffee",
"amount": 35.00,
"currency": "CNY",
"items": [
{ "name": "Latte", "quantity": 1, "price": 30.00 },
{ "name": "Servilleta", "quantity": 1, "price": 5.00 }
],
"category": "Restauración"
}
Si hay algún error en los resultados, puedes editarlos manualmente para corregirlos.
6.3 Confirmar y guardar
Tras confirmar que los datos son correctos, haz clic en Confirm (Confirmar) y la transacción se guardará en tu libro de contabilidad.
6.4 Conversión automática de divisas
Si subes una factura en moneda extranjera, como USD o EUR, TaxHacker automáticamente:
- Identificará el tipo de moneda.
- Obtendrá el tipo de cambio histórico de la fecha de la transacción.
- La convertirá a tu moneda base.
Puedes ver la lista de monedas admitidas en Settings → Currencies, incluyendo criptomonedas como BTC o ETH.
6.5 Campos personalizados
Si tienes necesidades especiales de extracción, puedes crear campos personalizados en Settings → Fields. Por ejemplo, si quieres extraer el número de identificación fiscal (NIF/CIF):
- Haz clic en Add Field.
- Nombre del campo: Identificación Fiscal.
- Rellena el prompt de extracción para la IA:
Por favor, extrae el número de identificación fiscal o NIF de la factura. - Guarda.
La próxima vez que analices una factura, la IA intentará extraer automáticamente este campo.
7 Exportación y copia de seguridad de datos
Un punto crucial en la contabilidad es la exportación de datos, y TaxHacker destaca en esto.
7.1 Exportación filtrada
En la página Transactions, puedes filtrar por fecha, categoría, proyecto, etc.:
- Rango de fechas: 2026-01-01 a 2026-03-21
- Categoría: Restauración, Transporte
- Importe: > 100
Tras filtrar, haz clic en Export CSV para exportar los registros de transacciones con todos sus adjuntos.
7.2 Copia de seguridad completa
En Settings → Backups, puedes crear una copia de seguridad completa que incluye:
- Instantánea de la base de datos
- Todos los archivos subidos
- Información de configuración
Los archivos de respaldo se pueden descargar localmente para garantizar la seguridad de los datos.
8 Solución de problemas comunes
Estos son problemas que podrían surgir durante el despliegue o el uso:
Q1: El contenedor no arranca, indica error de conexión a la base de datos
Revisa si DATABASE_URL en docker-compose.yml es correcto. La configuración por defecto usa db como nombre de host (red interna de Docker); si personalizaste la base de datos, ajústalo en consecuencia.
Q2: El análisis de IA se queda siempre en "Procesando"
Primero, comprueba que la API Key de LLM esté configurada correctamente. Luego, revisa los logs del contenedor:
docker compose logs app | grep -i error
Si ves un error de "rate limit", significa que se ha limitado el número de llamadas a la API.
Q3: Al subir un archivo indica "archivo demasiado grande"
El límite máximo por defecto es 10MB. Si necesitas subir archivos más grandes, modifica el .env:
MAX_FILE_SIZE=20971520 # 20MB
Luego reinicia el servicio: docker compose restart.
Q4: La identificación del recibo no es precisa
Puedes personalizar el prompt del sistema en Settings → LLM para dar más contexto a la IA. Por ejemplo, si perteneces al sector hostelero, puedes añadir:
Eres un contable experto en el sector de la restauración, especializado en identificar formatos de recibos de diversos restaurantes y cafeterías.
Q5: Cómo cambiar la contraseña de acceso
Tras iniciar sesión, haz clic en tu avatar en la esquina superior derecha → Profile (Perfil), donde podrás modificar la contraseña y el correo.
Q6: ¿Qué hacer si olvido la contraseña de administrador?
Es necesario restablecerla a través de la base de datos. Conéctate al contenedor de PostgreSQL:
docker exec -it taxhacker-db-1 psql -U postgres -d taxhacker
Luego ejecuta:
UPDATE users SET password_hash = 'nuevo_hash_de_contraseña' WHERE email = 'admin@localhost';
9 Direcciones avanzadas
Una vez dominadas las funciones básicas, puedes explorar estas opciones avanzadas:
9.1 Personalización de prompts de IA
TaxHacker permite personalizar profundamente el comportamiento de la IA. Modifica el prompt del sistema en Settings → LLM para que la IA extraiga los datos siguiendo las normas de tu industria.
9.2 Gestión de múltiples proyectos
Crea diferentes proyectos en Settings → Projects (ej. "Proyecto A", "Proyecto B") para contabilizar ingresos y gastos por proyecto, ideal para freelancers con varias líneas de negocio.
9.3 Automatización con OpenClaw
Si también tienes desplegado OpenClaw, puedes hacer que llame periódicamente a la API de TaxHacker para procesar automáticamente los recibos sin clasificar, logrando una contabilidad totalmente desatendida.
9.4 Copias de seguridad automáticas programadas
Usa un cronjob para llamar periódicamente a la API de backups:
0 2 * * * curl -X POST http://localhost:7331/api/backups
Esto creará automáticamente una copia de seguridad cada día a las 2 AM.