Invox - Gestor de Facturas para PYMES

Gestor de facturación para autónomos y pequeñas empresas. Clientes, proformas y facturas en un solo sitio, sin complicaciones.

🔗 App en vivo: https://sample-service-name-t672.onrender.com

Invox es una aplicación web full-stack para gestionar la facturación de un negocio: alta de clientes con validación de NIF intracomunitario contra VIES, creación de proformas editables, emisión de facturas con numeración correlativa, cálculo automático de IVA e IRPF, y seguimiento del estado de cobro. Incluye un panel con métricas de actividad.

Proyecto final del bootcamp Full Stack Developer de 4Geeks Academy.

---

Características

• Autenticación segura con JWT y contraseñas cifradas (bcrypt): registro, inicio de sesión y restablecimiento de contraseña.
• Gestión de clientes (CRUD completo) con validación de NIF/VAT intracomunitario en tiempo real contra la API oficial de VIES (Comisión Europea), con autorrelleno de nombre y dirección cuando el operador está registrado.
• Proformas y facturas: las proformas son borradores editables; al emitirse se convierten en facturas con número correlativo por año (formato 2026/0001) y quedan bloqueadas (no se pueden modificar ni eliminar), respetando la lógica fiscal española.
• Cálculo automático de base imponible, IVA e IRPF en el servidor, con totales recalculados en vivo mientras se editan las líneas.
• Seguimiento de cobro: cada factura se marca como pagada o pendiente.
• Panel de inicio con métricas: total facturado, cobrado, pendiente de cobro y número de clientes.
• Aislamiento de datos por usuario: cada usuario solo accede a sus propios clientes y facturas.

---

Stack tecnológico

Frontend

• React (Vite)
• React Router
• Context API + useReducer (patrón Flux) para el estado global
• Bootstrap 5

Backend

• Python / Flask
• SQLAlchemy (ORM) + Flask-Migrate (Alembic)
• Flask-JWT-Extended (autenticación)
• Flask-Bcrypt (cifrado de contraseñas)
• Gunicorn (servidor de producción)

Base de datos

• PostgreSQL

Integraciones

• VIES REST API (validación de IVA intracomunitario)

Despliegue

• Render

---

Estructura del proyecto

src/
├── api/
│   ├── models.py        # Modelos: User, Client, Invoice, InvoiceItem
│   ├── routes.py        # Endpoints de la API
│   ├── utils.py         # Utilidades (validación VIES, etc.)
│   ├── admin.py
│   └── commands.py
├── app.py               # Punto de entrada de Flask
└── front/
    ├── pages/           # Login, ResetPassword, Dashboard, Clients, Invoices, InvoiceDetail
    ├── components/      # Sidebar, ClientFormModal, etc.
    ├── services/        # Capa de llamadas a la API (api, auth, clients, invoices)
    ├── hooks/           # useGlobalReducer
    └── store.js         # Reducer y estado global

---

Instalación local

Requisitos

• Python 3.10
• Node.js
• PostgreSQL
• Pipenv

Backend

Instala las dependencias:

pipenv install

Crea una base de datos PostgreSQL y configura el archivo .env (ver más abajo). Aplica las migraciones:

pipenv run upgrade

Arranca el servidor (puerto 3001):

python -m pipenv run start

Frontend

npm install
npm run dev

El frontend arranca en el puerto 3000.

Nota para Windows: usa 127.0.0.1 en lugar de localhost en VITE_BACKEND_URL para evitar problemas de resolución por IPv6.

---

Variables de entorno

Crea un archivo .env en la raíz del proyecto:

DATABASE_URL=postgresql://usuario:password@127.0.0.1:5432/facturacion
FLASK_APP=src/app.py
FLASK_DEBUG=1
FLASK_APP_KEY=tu_clave_secreta
VITE_BASENAME=/
VITE_BACKEND_URL=http://127.0.0.1:3001

Variable	Descripción
DATABASE_URL	Cadena de conexión a PostgreSQL
FLASK_APP	Punto de entrada de Flask (src/app.py)
FLASK_APP_KEY	Clave secreta para firmar los tokens JWT
VITE_BACKEND_URL	URL del backend que consume el frontend

---

API

Todos los endpoints cuelgan del prefijo /api. Los marcados con 🔒 requieren un token JWT en la cabecera Authorization: Bearer <token>.

Método	Ruta	Descripción
POST	/register	Crear usuario
POST	/login	Iniciar sesión (devuelve token)
GET	/me 🔒	Datos del usuario autenticado
POST	/forgot-password	Solicitar token de restablecimiento
POST	/reset-password	Cambiar contraseña con token
GET	/clients 🔒	Listar clientes
POST	/clients 🔒	Crear cliente
PUT	/clients/<id> 🔒	Editar cliente
DELETE	/clients/<id> 🔒	Eliminar cliente
GET	/validate-vat/<country>/<vat> 🔒	Validar NIF intracomunitario (VIES)
GET	/invoices 🔒	Listar facturas y proformas
GET	/invoices/<id> 🔒	Ver una factura con sus líneas
POST	/invoices 🔒	Crear proforma
PUT	/invoices/<id> 🔒	Editar proforma (solo borradores)
DELETE	/invoices/<id> 🔒	Eliminar proforma (solo borradores)
POST	/invoices/<id>/issue 🔒	Emitir factura (asigna número correlativo y bloquea)
PATCH	/invoices/<id>/payment 🔒	Marcar cobro (pagada/pendiente)

---

Despliegue

La aplicación está desplegada en Render mediante un Blueprint (render.yaml), que crea la base de datos PostgreSQL y el servicio web. El proceso de build construye el frontend, instala las dependencias del backend y aplica las migraciones automáticamente.

Variables de entorno necesarias en producción: DATABASE_URL, FLASK_APP, FLASK_APP_KEY, FLASK_DEBUG, PYTHON_VERSION, VITE_BASENAME y VITE_BACKEND_URL (con la URL pública del servicio).

---

Mejoras futuras

• Envío del enlace de restablecimiento de contraseña por email.
• Generación de facturas en PDF.
• Filtro por rango de fechas en el listado de facturas.
• Documentación interactiva de la API.

---

Autor

Desarrollado por Toro Development — torodevelop.com