Publicado por
Invoice Ninja 5: Facturación, Proyectos y Seguimiento de Tiempo Autoalojado
Aplicación de facturación, presupuestos, gestión de proyectos y control horario construida con Laravel, disponible para autoalojamiento con todas las funciones Pro y Enterprise incluidas.
Vídeo tutorial en YouTube
Mira el vídeo completo sobre cómo instalar y usar Invoice Ninja 5: Facturación, Proyectos y Seguimiento de Tiempo Autoalojado en el canal GENBYTE:
¿Qué es Invoice Ninja 5: Facturación, Proyectos y Seguimiento de Tiempo Autoalojado?
Invoice Ninja es una aplicación source-available diseñada para la gestión completa de facturación, envío de presupuestos, administración de proyectos y seguimiento de tiempo. Desarrollada sobre Laravel, ofrece una alternativa autoalojada a los servicios SaaS de facturación, permitiendo a empresas y freelancers mantener el control total sobre sus datos e infraestructura. El proyecto incluye en su código fuente todas las características de los planes Pro y Enterprise de la versión alojada, y se distribuye bajo la licencia Elastic License 2.0, que permite uso, copia, distribución y obras derivadas con restricciones sobre la oferta como servicio gestionado a terceros.
Características principales
Facturación y presupuestos
Creación, envío y gestión de facturas y presupuestos profesionales con plantillas personalizables, soporte para facturación recurrente y múltiples monedas.
Gestión de proyectos y tareas
Organización de proyectos con tableros Kanban, asignación de tareas, seguimiento de progreso y colaboración en equipo.
Seguimiento de tiempo
Registro de horas trabajadas por proyecto y tarea, con temporizadores integrados y generación de informes de tiempo facturable.
Portal de clientes
Área privada para que los clientes vean, descarguen y paguen facturas, aprueben presupuestos y consulten el estado de proyectos.
Pagos en línea
Integración con pasarelas de pago como Stripe, PayPal, GoCardless y otras para cobro automático de facturas.
Gestión de gastos
Registro y categorización de gastos, vinculación a proyectos o clientes, y generación de informes de gastos.
Aplicaciones nativas multiplataforma
Apps oficiales para iOS, Android (Google Play y F-Droid), macOS, Windows, Linux (Snap y Flatpak) que se conectan a la instancia autoalojada.
API REST y SDKs
API documentada para integración con sistemas externos; SDK disponible para Go y webhooks para automatizaciones.
Opciones de despliegue flexibles
Instalación en servidor/VM, Docker, Cloudron, Softaculous, Elestio, YunoHost; compatible con bases de datos MySQL/MariaDB y colas Redis.
Marca blanca opcional
Licencia anual de 40 USD para eliminar la marca Invoice Ninja de las partes visibles para clientes.
Requisitos del sistema
- Servidor con PHP 8.1 o superior
- Composer para dependencias PHP
- Node.js y npm para compilación de assets frontend (Vite, TailwindCSS)
- Base de datos MySQL 5.7+ o MariaDB 10.3+
- Redis para colas, caché y broadcasting (opcional pero recomendado)
- Servidor web Nginx o Apache con soporte para PHP-FPM
- Extensiones PHP: BCMath, Ctype, Fileinfo, JSON, Mbstring, OpenSSL, PDO, Tokenizer, XML, GD o Imagick, ZIP
- Mínimo 1 GB de RAM (2 GB recomendados para producción)
- Espacio en disco: 2 GB base + espacio para PDFs, backups y archivos adjuntos
Instalación con Docker Compose
Clonar repositorio y preparar entorno
Clona la versión estable etiquetada (reemplaza v5.11.53 por la etiqueta más reciente) y copia el archivo de entorno de ejemplo.
cd invoiceninja
cp .env.example .env
Instalar dependencias PHP (producción)
Instala dependencias de Composer optimizadas para producción sin herramientas de desarrollo.
Configurar variables de entorno
Edita el archivo .env con tus valores: APP_KEY (genera con php artisan key:generate), APP_URL, credenciales de base de datos (DB_HOST, DB_DATABASE, DB_USERNAME, DB_PASSWORD), configuración de correo (MAIL_MAILER, SMTP), Redis (REDIS_HOST, REDIS_PORT), PDF_GENERATOR (hosted_ninja, snappdf, gotenberg, phantom), y demás parámetros según .env.example.
php artisan key:generate
# Editar .env con tu editor preferido
nano .env
Ejecutar migraciones y seeders (opcional: datos de prueba)
Crea las tablas y, si deseas datos de ejemplo, ejecuta los seeders y el comando de datos de prueba.
Compilar assets frontend
Instala dependencias Node y compila los assets para producción.
npm run production
Configurar servidor web (Nginx ejemplo)
Apunta el root al directorio public/ y configura PHP-FPM. Asegura que APP_URL coincida con el dominio y que REQUIRE_HTTPS=true si usas TLS.
server {
listen 80;
server_name tu-dominio.com;
root /ruta/a/invoiceninja/public;
index index.php;
location / {
try_files $uri $uri/ /index.php?$query_string;
}
location ~ \.php$ {
fastcgi_pass unix:/run/php/php8.2-fpm.sock;
fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
include fastcgi_params;
}
}
Despliegue con Docker (imagen oficial)
La imagen oficial en Docker Hub (invoiceninja/invoiceninja) permite despliegue rápido. Requiere base de datos y Redis externos. Consulta la guía oficial para docker-compose.yml completo.
docker run -d \
–name invoiceninja \
-p 80:80 \
-e APP_URL=http://tu-dominio.com \
-e DB_HOST=db \
-e DB_DATABASE=ninja \
-e DB_USERNAME=ninja \
-e DB_PASSWORD=secreto \
-e REDIS_HOST=redis \
invoiceninja/invoiceninja:latest
Acceder al proyecto
Asistente de configuración inicial
Si no cargaste datos de prueba, accede a http://tu-dominio.com/setup para configurar la empresa, usuario administrador y ajustes básicos.
Panel de administración
Accede a http://tu-dominio.com/ con el usuario administrador creado en el setup o, si usaste datos de prueba: [email protected] / password.
Portal de clientes
Disponible en http://tu-dominio.com/client/login. Con datos de prueba: [email protected] / password.
API REST
Endpoints bajo /api/v1/. Documentación en https://api-docs.invoicing.co/. Requiere token API generado en la interfaz de administración.
Casos de uso
- Freelancers y consultores que necesitan facturación profesional, control de horas y portal de clientes sin depender de SaaS externo.
- Pequeñas y medianas empresas que requieren gestión de proyectos con Kanban, seguimiento de tiempo facturable y emisión de facturas recurrentes.
- Agencias y estudios que desean autoalojar su sistema de facturación para cumplimiento de privacidad de datos (RGPD, LOPD) y soberanía del dato.
- Equipos de desarrollo que integran facturación y pagos en sus propios productos mediante la API REST y webhooks.
- Organizaciones que prefieren infraestructura propia y usan Docker, Cloudron, YunoHost u otros instaladores de aplicaciones self-hosted.
Configuración avanzada
Generación de PDF
Configura PDF_GENERATOR en .env. Opciones: hosted_ninja (servicio oficial, requiere conexión externa), snappdf (binario local, alto rendimiento), gotenberg (servicio Docker), phantom (PhantomJS Cloud, clave demo limitada). Para producción se recomienda snappdf o gotenberg self-hosted.
# Requiere binario snappdf en PATH o ruta configurada
Colas y tareas programadas
Configura QUEUE_CONNECTION=redis y SUPERVISOR para workers. Programa el scheduler de Laravel en cron para tareas automáticas (facturación recurrente, recordatorios, limpieza).
* * * * * cd /ruta/a/invoiceninja && php artisan schedule:run >> /dev/null 2>&1
# Supervisor worker ejemplo
[program:invoiceninja-queue]
command=php artisan queue:work redis –sleep=3 –tries=3
numprocs=2
autostart=true
autorestart=true
Autenticación SSO / OIDC
Habilita inicio de sesión único configurando variables OIDC_* en .env: OIDC_ISSUER, OIDC_CLIENT_ID, OIDC_CLIENT_SECRET, OIDC_SCOPES, OIDC_PROVIDER_LABEL. La URL de redirección es $APP_URL/auth/oidc.
OIDC_CLIENT_ID=tu-client-id
OIDC_CLIENT_SECRET=tu-client-secret
OIDC_SCOPES="openid profile email"
OIDC_PROVIDER_LABEL="Mi SSO"
Multi-empresa (MULTI_DB_ENABLED)
Activa MULTI_DB_ENABLED=true para aislar datos de cada empresa en bases de datos separadas. Requiere configuración adicional de conexiones y migraciones por tenant.
# Configurar conexiones en config/database.php y migraciones por tenant
Marca blanca (White-label)
Adquiere licencia anual de 40 USD en https://www.invoiceninja.com para eliminar la marca Invoice Ninja de PDFs, portal de clientes y correos. Se aplica mediante clave de licencia en la interfaz de administración.
Gestión y mantenimiento
Actualización a nueva versión
Descarga la nueva etiqueta, actualiza dependencias, ejecuta migraciones y recompila assets. Haz backup de base de datos y .env antes de proceder.
git checkout v5.XX.XX
composer i -o –no-dev
php artisan migrate –force
npm ci && npm run production
php artisan config:cache
php artisan route:cache
php artisan view:cache
Backup de base de datos y archivos
Realiza copias de seguridad periódicas de la base de datos y del directorio storage/ (PDFs, adjuntos, backups internos). Las variables DELETE_PDF_DAYS y DELETE_BACKUP_DAYS controlan la retención interna.
mysqldump -u ninja -p ninja > backup_$(date +%F).sql
# Backup storage
tar -czf storage_backup_$(date +%F).tar.gz storage/
Limpieza de archivos temporales y logs
Laravel genera logs en storage/logs/. Configura rotación de logs y limpieza de archivos temporales antiguos.
/var/www/invoiceninja/storage/logs/*.log {
daily
missingok
rotate 14
compress
notifempty
create 0640 www-data www-data
}
Monitoreo de colas y trabajos fallidos
Supervisa la tabla failed_jobs y la longitud de colas Redis. Reintenta o elimina trabajos fallidos según necesidad.
php artisan queue:retry all
php artisan queue:flush
Stack técnico
- PHP 8.1+
- Laravel 10.x
- MySQL / MariaDB
- Redis
- Node.js / Vite
- TailwindCSS
- Alpine.js / Vue.js (frontend reactivo)
- Docker (imagen oficial)
- Composer
- PHPUnit / Playwright (testing)
Referencias oficiales
- Repositorio oficial GitHub: https://github.com/invoiceninja/invoiceninja
- Sitio web oficial: https://invoiceninja.com
- Guía de instalación autoalojada: https://invoiceninja.github.io/en/self-host-installation/
- Documentación de usuario: https://invoiceninja.github.io/en/user-guide/
- Guía de desarrollador: https://invoiceninja.github.io/en/developer-guide/
- Documentación API: https://api-docs.invoicing.co/
- Imagen Docker oficial: https://hub.docker.com/r/invoiceninja/invoiceninja
- Licencia Elastic License 2.0: https://invoiceninja.github.io/docs/legal/license/
- Foro de soporte: https://forum.invoiceninja.com
- Comunidad Discord: https://discord.gg/ZwEdtfCwXA
Apoya el canal GENBYTE
¿Te ha sido útil este contenido?
Suscríbete a YouTube
Newsletter GENBYTE
Ko-fi
Contacto: [email protected]