# Sistema de Gestión de Facturas 606 - Documentación del Backend

**Versión:** 1.0.0  
**Fecha:** Agosto 2024  
**Autor:** Manus AI  
**Proyecto:** Sistema de Gestión de Facturas para el Formato 606 de la DGII

---

## Tabla de Contenidos

1. [Introducción](#introducción)
2. [Arquitectura del Sistema](#arquitectura-del-sistema)
3. [Instalación y Configuración](#instalación-y-configuración)
4. [Modelos de Datos](#modelos-de-datos)
5. [APIs de Autenticación](#apis-de-autenticación)
6. [APIs de Gestión de Usuarios](#apis-de-gestión-de-usuarios)
7. [APIs de Gestión de Empresas](#apis-de-gestión-de-empresas)
8. [APIs de Gestión de Facturas](#apis-de-gestión-de-facturas)
9. [APIs de Reportes y Estadísticas](#apis-de-reportes-y-estadísticas)
10. [Servicio de OCR](#servicio-de-ocr)
11. [Generador de Formato 606](#generador-de-formato-606)
12. [Pruebas y Validación](#pruebas-y-validación)
13. [Despliegue en Producción](#despliegue-en-producción)
14. [Próximos Pasos](#próximos-pasos)

---

## Introducción

El Sistema de Gestión de Facturas 606 es una solución integral desarrollada para automatizar y simplificar el proceso de gestión de facturas de compras según el formato 606 requerido por la Dirección General de Impuestos Internos (DGII) de la República Dominicana.

Este backend, desarrollado con Flask y Python, proporciona una API REST completa que incluye funcionalidades avanzadas como procesamiento de imágenes con OCR mediante inteligencia artificial, generación automática de reportes en formato 606, y un sistema robusto de gestión de usuarios con diferentes niveles de permisos.

### Características Principales

El sistema backend implementa las siguientes características fundamentales que lo convierten en una solución empresarial robusta y escalable. La arquitectura modular permite una fácil extensión y mantenimiento, mientras que el diseño orientado a APIs facilita la integración con diferentes tipos de frontend, ya sean aplicaciones web, móviles o sistemas de terceros.

La funcionalidad de procesamiento de imágenes con OCR representa uno de los aspectos más innovadores del sistema. Utilizando la API de OpenAI Vision, el sistema puede extraer automáticamente información de facturas fotografiadas o escaneadas, incluyendo datos como RNC del proveedor, NCF, fechas, montos, ITBIS y otros campos requeridos por la DGII. Esta capacidad reduce significativamente el tiempo de entrada de datos y minimiza errores humanos.

El generador de formato 606 cumple estrictamente con las especificaciones oficiales de la DGII, asegurando que los archivos generados sean aceptados sin problemas por el sistema de la institución. El formato incluye tanto la línea de encabezado (606) como las líneas de detalle (607), con el formateo correcto de fechas, montos y códigos según los estándares requeridos.

El sistema de permisos implementa tres roles principales: Super Administrador con acceso completo al sistema, Contador con gestión de su empresa asignada, y Empleado con capacidad de crear y gestionar sus propias facturas. Esta estructura permite una separación clara de responsabilidades y mantiene la seguridad de los datos empresariales.

### Tecnologías Utilizadas

El backend está construido sobre un stack tecnológico moderno y probado en producción. Flask sirve como el framework web principal, proporcionando flexibilidad y simplicidad para el desarrollo de APIs REST. SQLAlchemy actúa como el ORM (Object-Relational Mapping) que facilita la interacción con la base de datos, mientras que SQLite se utiliza como base de datos por defecto para desarrollo, con la posibilidad de migrar fácilmente a PostgreSQL o MySQL para producción.

La integración con OpenAI Vision API permite el procesamiento inteligente de imágenes de facturas, mientras que Pillow (PIL) maneja la manipulación y optimización de imágenes antes del procesamiento OCR. Flask-CORS habilita las solicitudes cross-origin necesarias para la comunicación con aplicaciones frontend, y Werkzeug proporciona utilidades de seguridad para el hash de contraseñas y otras funciones criptográficas.

Para las pruebas, el sistema utiliza unittest como framework principal, complementado con psutil para monitoreo de rendimiento y uso de memoria. Esta combinación permite una validación exhaustiva tanto de la funcionalidad como del rendimiento del sistema.

---



## Arquitectura del Sistema

La arquitectura del backend sigue un patrón de diseño modular y escalable que separa claramente las responsabilidades en diferentes capas. Esta estructura facilita el mantenimiento, las pruebas y la extensión futura del sistema.

### Estructura de Directorios

```
invoice-606-backend/
├── src/
│   ├── main.py                 # Punto de entrada de la aplicación
│   ├── models/                 # Modelos de datos (SQLAlchemy)
│   │   ├── user.py            # Modelo de usuarios
│   │   ├── company.py         # Modelo de empresas
│   │   ├── invoice.py         # Modelo de facturas
│   │   └── expense_type.py    # Modelo de tipos de gastos
│   ├── routes/                # Controladores de rutas (Blueprints)
│   │   ├── auth.py           # Rutas de autenticación
│   │   ├── user.py           # Rutas de gestión de usuarios
│   │   ├── company.py        # Rutas de gestión de empresas
│   │   ├── invoice.py        # Rutas de gestión de facturas
│   │   └── reports.py        # Rutas de reportes y estadísticas
│   ├── services/              # Lógica de negocio
│   │   ├── ocr_service.py    # Servicio de procesamiento OCR
│   │   └── report_606_service.py # Servicio de generación de reportes 606
│   ├── tests/                 # Suite de pruebas
│   │   ├── test_apis.py      # Pruebas de integración de APIs
│   │   ├── test_606_format.py # Pruebas del formato 606
│   │   ├── test_performance.py # Pruebas de rendimiento
│   │   └── test_data_setup.py # Configuración de datos de prueba
│   └── database/              # Archivos de base de datos
├── venv/                      # Entorno virtual de Python
├── requirements.txt           # Dependencias del proyecto
└── README.md                  # Documentación básica
```

### Patrón de Arquitectura

El sistema implementa una arquitectura de tres capas que proporciona una separación clara de responsabilidades y facilita el mantenimiento y escalabilidad del código. La capa de presentación está representada por los controladores de rutas (routes), que manejan las solicitudes HTTP y las respuestas. Estos controladores actúan como intermediarios entre el cliente y la lógica de negocio, validando datos de entrada, manejando errores y formateando respuestas.

La capa de lógica de negocio se encuentra en los servicios (services), donde se implementan las reglas de negocio específicas del dominio. Por ejemplo, el OCRService maneja toda la lógica relacionada con el procesamiento de imágenes y extracción de datos, mientras que el Report606Service se encarga de generar los reportes en formato oficial de la DGII. Esta separación permite que la lógica de negocio sea independiente de la interfaz de usuario y pueda ser reutilizada en diferentes contextos.

La capa de datos está compuesta por los modelos (models) que definen la estructura de la base de datos y las operaciones básicas de persistencia. Utilizando SQLAlchemy como ORM, estos modelos proporcionan una abstracción de alto nivel sobre la base de datos, permitiendo que el código sea independiente del motor de base de datos específico utilizado.

### Flujo de Datos

El flujo de datos en el sistema sigue un patrón predecible que facilita el debugging y el mantenimiento. Cuando una solicitud HTTP llega al servidor, Flask la enruta al controlador apropiado basándose en la URL y el método HTTP. El controlador valida los datos de entrada, verifica la autenticación y autorización del usuario, y luego invoca los servicios necesarios para procesar la solicitud.

Los servicios interactúan con los modelos de datos para realizar operaciones de lectura y escritura en la base de datos. En el caso de operaciones complejas como el procesamiento OCR, los servicios también pueden interactuar con APIs externas como OpenAI. Una vez completado el procesamiento, los servicios devuelven los resultados al controlador, que los formatea como respuesta JSON y los envía de vuelta al cliente.

Este flujo unidireccional de datos facilita el seguimiento de errores y la implementación de logging y monitoreo. Además, la separación clara entre capas permite implementar fácilmente funcionalidades transversales como caching, logging y métricas de rendimiento.

### Gestión de Sesiones y Autenticación

El sistema utiliza sesiones de Flask para mantener el estado de autenticación de los usuarios. Cuando un usuario se autentica exitosamente, se crea una sesión que almacena información básica como el ID del usuario, su rol y la empresa asociada. Esta información se utiliza en los decoradores de autenticación para verificar permisos en cada solicitud.

La gestión de sesiones está diseñada para ser stateless en el sentido de que toda la información necesaria para autorizar una solicitud está contenida en la sesión, sin necesidad de consultas adicionales a la base de datos en cada request. Esto mejora significativamente el rendimiento del sistema, especialmente bajo carga alta.

### Manejo de Errores

El sistema implementa un manejo de errores robusto y consistente en todas las capas. Los controladores capturan excepciones y las convierten en respuestas HTTP apropiadas con códigos de estado y mensajes de error descriptivos. Los servicios lanzan excepciones específicas del dominio que son capturadas y manejadas por los controladores.

Todos los errores se registran con información contextual suficiente para facilitar el debugging en producción. El sistema distingue entre errores del usuario (como datos inválidos) y errores del sistema (como fallos de conectividad), proporcionando respuestas apropiadas para cada tipo.

---

## Instalación y Configuración

La instalación del sistema backend está diseñada para ser simple y reproducible en diferentes entornos. El proceso utiliza herramientas estándar de Python y puede ejecutarse tanto en entornos de desarrollo local como en servidores de producción.

### Requisitos del Sistema

El sistema requiere Python 3.11 o superior para funcionar correctamente. Esta versión de Python incluye mejoras de rendimiento y características de seguridad que son aprovechadas por el sistema. Además, se necesita pip para la gestión de paquetes Python y virtualenv para crear entornos aislados.

Para el procesamiento de imágenes, el sistema requiere acceso a la API de OpenAI, lo que implica tener una clave de API válida y créditos suficientes para el procesamiento. En entornos de desarrollo, se puede configurar una clave de API de prueba con límites reducidos.

El sistema de base de datos por defecto es SQLite, que no requiere instalación adicional ya que está incluido con Python. Para entornos de producción, se recomienda migrar a PostgreSQL o MySQL, que requerirán instalación y configuración separadas.

### Instalación Paso a Paso

El primer paso en la instalación es clonar o descargar el código fuente del sistema. Una vez obtenido el código, se debe crear un entorno virtual de Python para aislar las dependencias del proyecto de otras instalaciones de Python en el sistema.

```bash
# Crear entorno virtual
python -m venv venv

# Activar entorno virtual (Linux/Mac)
source venv/bin/activate

# Activar entorno virtual (Windows)
venv\Scripts\activate

# Instalar dependencias
pip install -r requirements.txt
```

La instalación de dependencias incluye Flask y sus extensiones, SQLAlchemy para el ORM, OpenAI para el procesamiento de imágenes, Pillow para manipulación de imágenes, y otras librerías de soporte. El archivo requirements.txt especifica las versiones exactas de cada dependencia para asegurar reproducibilidad.

### Configuración de Variables de Entorno

El sistema utiliza variables de entorno para configurar aspectos sensibles como claves de API y configuraciones específicas del entorno. Las variables principales que deben configurarse son:

```bash
export OPENAI_API_KEY="tu_clave_de_api_openai"
export OPENAI_API_BASE="https://api.openai.com/v1"
export FLASK_ENV="development"  # o "production"
export SECRET_KEY="clave_secreta_para_sesiones"
```

La clave de OpenAI es esencial para el funcionamiento del servicio OCR. En entornos de desarrollo, se puede utilizar una clave con límites reducidos, pero en producción se debe asegurar que la clave tenga suficientes créditos y límites de rate para manejar la carga esperada.

La clave secreta de Flask se utiliza para firmar las sesiones y debe ser una cadena aleatoria y segura. En producción, esta clave debe mantenerse confidencial y no debe incluirse en el código fuente.

### Inicialización de la Base de Datos

El sistema incluye un mecanismo automático de inicialización de la base de datos que crea todas las tablas necesarias y carga los datos básicos como los tipos de gastos oficiales de la DGII. Este proceso se ejecuta automáticamente la primera vez que se inicia la aplicación.

```bash
# Iniciar la aplicación (esto inicializa la base de datos automáticamente)
python src/main.py
```

Durante la inicialización, el sistema crea las siguientes tablas: users (usuarios), companies (empresas), invoices (facturas), y expense_types (tipos de gastos). También inserta los 11 tipos de gastos oficiales definidos por la DGII, que son esenciales para el funcionamiento del sistema.

### Configuración para Desarrollo

En entornos de desarrollo, el sistema se configura automáticamente con opciones que facilitan el debugging y las pruebas. Esto incluye el modo debug de Flask activado, logging detallado, y la recarga automática del servidor cuando se detectan cambios en el código.

Para cargar datos de prueba que faciliten el desarrollo y las pruebas, se puede ejecutar el script de configuración de datos de prueba:

```bash
python -c "
import sys
sys.path.insert(0, '.')
from src.main import app
from src.tests.test_data_setup import create_test_data
with app.app_context():
    create_test_data(app)
"
```

Este script crea empresas, usuarios y facturas de ejemplo que pueden utilizarse para probar todas las funcionalidades del sistema sin necesidad de crear datos manualmente.

### Configuración para Producción

La configuración para producción requiere consideraciones adicionales de seguridad, rendimiento y monitoreo. El sistema debe configurarse para utilizar una base de datos robusta como PostgreSQL, un servidor web como Gunicorn o uWSGI, y un proxy reverso como Nginx.

Las variables de entorno en producción deben configurarse con valores seguros y específicos del entorno. Esto incluye claves secretas fuertes, URLs de base de datos con credenciales seguras, y configuraciones de logging apropiadas para el entorno de producción.

Es importante configurar también el monitoreo y alertas para detectar problemas de rendimiento o errores en tiempo real. Esto puede incluir herramientas como Sentry para tracking de errores, Prometheus para métricas, y logs centralizados para análisis de comportamiento.

---


## Modelos de Datos

El sistema utiliza SQLAlchemy como ORM para definir y gestionar los modelos de datos. Cada modelo representa una entidad del dominio de negocio y define tanto la estructura de la base de datos como las operaciones básicas de persistencia.

### Modelo User (Usuario)

El modelo User representa a los usuarios del sistema y implementa un sistema de roles que controla el acceso a diferentes funcionalidades. La estructura del modelo está diseñada para soportar múltiples tipos de usuarios con diferentes niveles de permisos.

```python
class User(db.Model):
    __tablename__ = 'users'
    
    id = db.Column(db.Integer, primary_key=True)
    username = db.Column(db.String(80), unique=True, nullable=False)
    email = db.Column(db.String(120), unique=True, nullable=False)
    password_hash = db.Column(db.String(255), nullable=False)
    first_name = db.Column(db.String(100), nullable=False)
    last_name = db.Column(db.String(100), nullable=False)
    phone = db.Column(db.String(20))
    role = db.Column(db.String(20), nullable=False)  # super_admin, accountant, employee
    company_id = db.Column(db.Integer, db.ForeignKey('companies.id'))
    is_active = db.Column(db.Boolean, default=True)
    created_at = db.Column(db.DateTime, default=datetime.utcnow)
    updated_at = db.Column(db.DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
```

El sistema de roles implementa tres niveles de acceso claramente diferenciados. El rol 'super_admin' tiene acceso completo a todas las funcionalidades del sistema, incluyendo la gestión de múltiples empresas y usuarios. Este rol está diseñado para administradores del sistema que necesitan supervisar y gestionar toda la plataforma.

El rol 'accountant' está diseñado para contadores que gestionan una empresa específica. Estos usuarios pueden gestionar todas las facturas de su empresa, aprobar o rechazar facturas creadas por empleados, generar reportes 606, y gestionar los empleados de su empresa. Su acceso está limitado únicamente a los datos de la empresa a la que están asignados.

El rol 'employee' representa a los empleados que crean facturas para su empresa. Estos usuarios pueden crear nuevas facturas, editar sus propias facturas mientras estén en estado pendiente, y ver el historial de sus facturas. No tienen acceso a facturas de otros empleados ni a funcionalidades administrativas.

La relación con la empresa se establece a través del campo company_id, que es obligatorio para usuarios con roles 'accountant' y 'employee', pero opcional para 'super_admin'. Esta estructura permite que los super administradores gestionen múltiples empresas sin estar limitados a una específica.

### Modelo Company (Empresa)

El modelo Company representa las empresas cliente del sistema. Cada empresa puede tener múltiples usuarios asociados y gestiona sus propias facturas de forma independiente.

```python
class Company(db.Model):
    __tablename__ = 'companies'
    
    id = db.Column(db.Integer, primary_key=True)
    name = db.Column(db.String(200), nullable=False)
    rnc = db.Column(db.String(20), unique=True, nullable=False)
    address = db.Column(db.Text)
    phone = db.Column(db.String(20))
    email = db.Column(db.String(120))
    status = db.Column(db.String(20), default='active')  # active, inactive
    created_at = db.Column(db.DateTime, default=datetime.utcnow)
    updated_at = db.Column(db.DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
```

El campo RNC (Registro Nacional del Contribuyente) es único en el sistema y sirve como identificador principal de la empresa ante la DGII. Este campo es esencial para la generación de reportes 606, ya que aparece en el encabezado del archivo oficial.

El estado de la empresa permite activar o desactivar empresas sin eliminar sus datos históricos. Cuando una empresa está inactiva, sus usuarios no pueden acceder al sistema, pero todos los datos se mantienen para consultas históricas y auditorías.

### Modelo Invoice (Factura)

El modelo Invoice es el más complejo del sistema, ya que debe capturar todos los campos requeridos por el formato 606 de la DGII, además de campos adicionales para la gestión interna del sistema.

```python
class Invoice(db.Model):
    __tablename__ = 'invoices'
    
    id = db.Column(db.Integer, primary_key=True)
    invoice_number = db.Column(db.String(100))
    ncf = db.Column(db.String(20))
    ncf_modified = db.Column(db.String(20))
    supplier_name = db.Column(db.String(200))
    supplier_rnc = db.Column(db.String(20))
    supplier_id_type = db.Column(db.String(20), default='RNC')
    invoice_date = db.Column(db.Date)
    payment_date = db.Column(db.Date)
    invoiced_amount = db.Column(db.Numeric(15, 2))
    itbis_invoiced = db.Column(db.Numeric(15, 2))
    itbis_retained = db.Column(db.Numeric(15, 2))
    itbis_perceived = db.Column(db.Numeric(15, 2))
    income_retention = db.Column(db.Numeric(15, 2))
    isr_perceived = db.Column(db.Numeric(15, 2))
    selective_consumption_tax = db.Column(db.Numeric(15, 2))
    other_taxes = db.Column(db.Numeric(15, 2))
    legal_tip = db.Column(db.Numeric(15, 2))
    expense_type = db.Column(db.String(2))
    expense_description = db.Column(db.String(200))
    status = db.Column(db.String(20), default='pending')
    company_id = db.Column(db.Integer, db.ForeignKey('companies.id'), nullable=False)
    created_by_user_id = db.Column(db.Integer, db.ForeignKey('users.id'), nullable=False)
    approved_by_user_id = db.Column(db.Integer, db.ForeignKey('users.id'))
    approved_at = db.Column(db.DateTime)
    image_path = db.Column(db.String(500))
    ocr_confidence = db.Column(db.Float)
    created_at = db.Column(db.DateTime, default=datetime.utcnow)
    updated_at = db.Column(db.DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
```

Los campos monetarios utilizan el tipo Numeric con precisión de 15 dígitos y 2 decimales, lo que permite manejar montos grandes con precisión exacta. Esto es crucial para aplicaciones financieras donde los errores de redondeo pueden tener consecuencias significativas.

El campo expense_type corresponde a los códigos de tipos de gasto definidos por la DGII (01 a 11), mientras que expense_description contiene la descripción textual del tipo de gasto. Esta redundancia facilita la generación de reportes y mejora la experiencia del usuario.

El sistema de estados de factura implementa un flujo de aprobación simple pero efectivo. Las facturas inician en estado 'pending' cuando son creadas por empleados, pueden ser 'approved' o 'rejected' por contadores, y solo las facturas aprobadas se incluyen en los reportes 606 oficiales.

Los campos relacionados con OCR (image_path y ocr_confidence) almacenan información sobre el procesamiento automático de imágenes. El path de la imagen se guarda para referencia futura, y el nivel de confianza del OCR ayuda a identificar facturas que pueden requerir revisión manual.

### Modelo ExpenseType (Tipo de Gasto)

El modelo ExpenseType almacena los tipos de gastos oficiales definidos por la DGII. Aunque estos datos son relativamente estáticos, mantenerlos en la base de datos facilita la gestión y permite futuras actualizaciones si la DGII modifica las categorías.

```python
class ExpenseType(db.Model):
    __tablename__ = 'expense_types'
    
    id = db.Column(db.String(2), primary_key=True)  # '01' a '11'
    name = db.Column(db.String(200), nullable=False)
    description = db.Column(db.Text)
    is_active = db.Column(db.Boolean, default=True)
```

Los 11 tipos de gastos oficiales son:
1. Gastos de Personal
2. Gastos por Trabajos, Suministros y Servicios  
3. Arrendamientos
4. Gastos de Activos Fijo
5. Gastos de Representación
6. Otras Deducciones Admitidas
7. Gastos Financieros
8. Gastos Extraordinarios
9. Compras y Gastos que Formaran Parte del Costo de Venta
10. Adquisiciones de Activos
11. Gastos de Seguros

### Relaciones entre Modelos

Las relaciones entre modelos están diseñadas para mantener la integridad referencial y facilitar las consultas complejas. La relación entre User y Company permite que múltiples usuarios pertenezcan a la misma empresa, mientras que la relación entre Invoice y Company asegura que cada factura esté asociada a una empresa específica.

Las relaciones de auditoría en el modelo Invoice (created_by_user_id y approved_by_user_id) permiten rastrear quién creó cada factura y quién la aprobó, proporcionando un trail de auditoría completo para cumplimiento regulatorio.

### Métodos de Modelo

Cada modelo incluye métodos de conveniencia que facilitan operaciones comunes. Por ejemplo, el modelo User incluye métodos para establecer y verificar contraseñas de forma segura, mientras que el modelo Invoice incluye un método to_606_format() que genera la línea de formato 606 para esa factura específica.

Estos métodos encapsulan la lógica de negocio relacionada con cada modelo y aseguran que las operaciones se realicen de forma consistente en todo el sistema. También facilitan las pruebas unitarias al proporcionar interfaces claras y predecibles.

---


## APIs de Autenticación

El sistema de autenticación proporciona endpoints seguros para el login, logout y gestión de sesiones de usuarios. Todas las APIs de autenticación utilizan sesiones de Flask para mantener el estado del usuario y implementan validaciones robustas para prevenir ataques comunes.

### POST /api/auth/login

Autentica a un usuario en el sistema y establece una sesión activa. Este endpoint es el punto de entrada principal para todos los usuarios del sistema.

**Parámetros de Entrada:**
```json
{
    "username": "string (requerido)",
    "password": "string (requerido)"
}
```

**Respuesta Exitosa (200):**
```json
{
    "message": "Login exitoso",
    "user": {
        "id": 1,
        "username": "contador1",
        "email": "contador@empresa.com",
        "first_name": "María",
        "last_name": "González",
        "role": "accountant",
        "company_id": 1,
        "is_active": true
    }
}
```

**Respuestas de Error:**
- **400 Bad Request:** Cuando faltan campos requeridos
- **401 Unauthorized:** Cuando las credenciales son incorrectas
- **403 Forbidden:** Cuando la cuenta está desactivada

El proceso de autenticación implementa varias capas de seguridad. Primero, se valida que tanto el username como la password estén presentes en la solicitud. Luego, se busca el usuario en la base de datos y se verifica que la cuenta esté activa. Finalmente, se compara la contraseña proporcionada con el hash almacenado utilizando funciones criptográficas seguras.

Una vez autenticado exitosamente, el sistema establece una sesión que incluye información esencial del usuario como su ID, rol y empresa asociada. Esta información se utiliza en todas las solicitudes posteriores para autorizar el acceso a recursos específicos.

### GET /api/auth/me

Obtiene la información del usuario actualmente autenticado. Este endpoint es útil para que las aplicaciones frontend verifiquen el estado de autenticación y obtengan información del usuario.

**Respuesta Exitosa (200):**
```json
{
    "user": {
        "id": 1,
        "username": "contador1",
        "email": "contador@empresa.com",
        "first_name": "María",
        "last_name": "González",
        "role": "accountant",
        "company_id": 1,
        "company_name": "Empresa Demo S.R.L.",
        "is_active": true
    }
}
```

**Respuesta de Error:**
- **401 Unauthorized:** Cuando no hay una sesión activa

Este endpoint no requiere parámetros adicionales ya que utiliza la información de la sesión activa para identificar al usuario. La respuesta incluye información extendida como el nombre de la empresa asociada, lo que facilita la construcción de interfaces de usuario informativas.

### POST /api/auth/logout

Cierra la sesión del usuario actual y limpia todos los datos de sesión. Este endpoint es importante para la seguridad, especialmente en dispositivos compartidos.

**Respuesta Exitosa (200):**
```json
{
    "message": "Logout exitoso"
}
```

El proceso de logout limpia completamente la sesión del usuario, asegurando que no quede información sensible en el navegador. Esto es especialmente importante en entornos donde múltiples usuarios pueden acceder al mismo dispositivo.

### POST /api/auth/register

Registra un nuevo usuario en el sistema. Este endpoint está restringido a usuarios con rol de super_admin, ya que la creación de usuarios debe ser controlada para mantener la seguridad del sistema.

**Parámetros de Entrada:**
```json
{
    "username": "string (requerido)",
    "email": "string (requerido)",
    "password": "string (requerido)",
    "first_name": "string (requerido)",
    "last_name": "string (requerido)",
    "phone": "string (opcional)",
    "role": "string (requerido)", // super_admin, accountant, employee
    "company_id": "integer (requerido para accountant y employee)"
}
```

**Respuesta Exitosa (201):**
```json
{
    "message": "Usuario creado exitosamente",
    "user": {
        "id": 5,
        "username": "nuevo_usuario",
        "email": "nuevo@empresa.com",
        "first_name": "Juan",
        "last_name": "Pérez",
        "role": "employee",
        "company_id": 1,
        "is_active": true
    }
}
```

**Respuestas de Error:**
- **400 Bad Request:** Campos faltantes o inválidos
- **403 Forbidden:** Usuario sin permisos de super_admin
- **409 Conflict:** Username o email ya existe

El proceso de registro incluye validaciones exhaustivas para asegurar la integridad de los datos. Se verifica que el username y email sean únicos en el sistema, que la contraseña cumpla con los requisitos mínimos de seguridad, y que el rol especificado sea válido.

Para usuarios con roles de 'accountant' o 'employee', es obligatorio especificar una company_id válida. El sistema verifica que la empresa exista y esté activa antes de crear el usuario. Los usuarios con rol 'super_admin' no requieren company_id ya que tienen acceso a todas las empresas.

### Middleware de Autenticación

El sistema incluye decoradores de autenticación que se aplican a endpoints que requieren usuarios autenticados. El decorador @require_auth verifica que existe una sesión activa y que el usuario está autenticado.

```python
@require_auth
def protected_endpoint():
    user_id = session.get('user_id')
    user_role = session.get('user_role')
    # Lógica del endpoint protegido
```

Adicionalmente, existe un decorador @require_role que permite restringir endpoints a usuarios con roles específicos:

```python
@require_role('super_admin')
def admin_only_endpoint():
    # Solo accesible para super_admin
```

### Seguridad de Contraseñas

El sistema implementa mejores prácticas para el manejo de contraseñas. Todas las contraseñas se almacenan utilizando hash seguro con Werkzeug Security, que implementa PBKDF2 con salt aleatorio. Esto asegura que incluso si la base de datos es comprometida, las contraseñas originales no pueden ser recuperadas fácilmente.

El sistema no impone restricciones específicas de complejidad de contraseñas en el backend, delegando esta responsabilidad al frontend. Sin embargo, se recomienda implementar políticas de contraseñas fuertes que incluyan longitud mínima, combinación de caracteres y números, y verificación contra diccionarios de contraseñas comunes.

### Gestión de Sesiones

Las sesiones de Flask se configuran con parámetros de seguridad apropiados para entornos de producción. Esto incluye cookies seguras (solo HTTPS en producción), HttpOnly para prevenir acceso desde JavaScript, y tiempos de expiración apropiados.

El sistema mantiene información mínima en la sesión para reducir el overhead y mejorar la seguridad. Solo se almacenan el ID del usuario, su rol, y la empresa asociada. Cualquier otra información se obtiene de la base de datos cuando es necesaria.

---

## APIs de Gestión de Usuarios

Las APIs de gestión de usuarios proporcionan funcionalidades completas de CRUD (Create, Read, Update, Delete) para administrar usuarios del sistema. Estas APIs implementan controles de acceso granulares basados en roles para asegurar que solo usuarios autorizados puedan realizar operaciones específicas.

### GET /api/users

Lista usuarios del sistema con soporte para paginación, filtrado y búsqueda. Los resultados se filtran automáticamente basándose en el rol del usuario que hace la solicitud.

**Parámetros de Query:**
- `page`: Número de página (default: 1)
- `per_page`: Elementos por página (default: 10, máximo: 100)
- `search`: Término de búsqueda para filtrar por nombre o email
- `role`: Filtrar por rol específico
- `company_id`: Filtrar por empresa (solo para super_admin)
- `is_active`: Filtrar por estado activo/inactivo

**Respuesta Exitosa (200):**
```json
{
    "users": [
        {
            "id": 1,
            "username": "contador1",
            "email": "contador@empresa.com",
            "first_name": "María",
            "last_name": "González",
            "role": "accountant",
            "company_id": 1,
            "company_name": "Empresa Demo S.R.L.",
            "is_active": true,
            "created_at": "2024-08-01T10:00:00Z"
        }
    ],
    "pagination": {
        "page": 1,
        "per_page": 10,
        "total": 25,
        "pages": 3,
        "has_next": true,
        "has_prev": false
    }
}
```

El comportamiento de este endpoint varía según el rol del usuario autenticado. Los super_admin pueden ver todos los usuarios del sistema y filtrar por cualquier empresa. Los accountant solo pueden ver usuarios de su propia empresa, incluyendo empleados bajo su supervisión. Los employee no tienen acceso a este endpoint.

La funcionalidad de búsqueda permite encontrar usuarios por nombre, apellido, username o email utilizando coincidencias parciales. Esto facilita la gestión de sistemas con muchos usuarios al permitir búsquedas rápidas y eficientes.

### GET /api/users/{id}

Obtiene información detallada de un usuario específico. El acceso está controlado por permisos basados en roles y relaciones organizacionales.

**Respuesta Exitosa (200):**
```json
{
    "user": {
        "id": 1,
        "username": "contador1",
        "email": "contador@empresa.com",
        "first_name": "María",
        "last_name": "González",
        "phone": "809-555-0123",
        "role": "accountant",
        "company_id": 1,
        "company_name": "Empresa Demo S.R.L.",
        "is_active": true,
        "created_at": "2024-08-01T10:00:00Z",
        "updated_at": "2024-08-15T14:30:00Z",
        "last_login": "2024-08-25T09:15:00Z"
    }
}
```

**Respuestas de Error:**
- **403 Forbidden:** Sin permisos para ver este usuario
- **404 Not Found:** Usuario no existe

Los permisos para este endpoint siguen reglas específicas: super_admin puede ver cualquier usuario, accountant puede ver usuarios de su empresa, y employee solo puede ver su propio perfil. Esta estructura asegura que la información sensible de usuarios esté protegida según las jerarquías organizacionales.

### PUT /api/users/{id}

Actualiza información de un usuario existente. Los campos que pueden actualizarse varían según el rol del usuario que hace la solicitud y su relación con el usuario objetivo.

**Parámetros de Entrada:**
```json
{
    "first_name": "string (opcional)",
    "last_name": "string (opcional)",
    "email": "string (opcional)",
    "phone": "string (opcional)",
    "role": "string (opcional, solo super_admin)",
    "company_id": "integer (opcional, solo super_admin)",
    "is_active": "boolean (opcional, solo super_admin y accountant)"
}
```

**Respuesta Exitosa (200):**
```json
{
    "message": "Usuario actualizado exitosamente",
    "user": {
        "id": 1,
        "username": "contador1",
        "email": "nuevo_email@empresa.com",
        "first_name": "María Elena",
        "last_name": "González",
        "role": "accountant",
        "company_id": 1,
        "is_active": true
    }
}
```

El sistema implementa validaciones específicas para cada tipo de actualización. Los cambios de email verifican que el nuevo email no esté en uso por otro usuario. Los cambios de rol requieren permisos de super_admin y pueden tener implicaciones en el acceso del usuario a diferentes funcionalidades.

Los employee solo pueden actualizar su información personal básica (nombre, email, teléfono). Los accountant pueden además activar/desactivar empleados de su empresa. Los super_admin tienen control completo sobre todos los campos de cualquier usuario.

### DELETE /api/users/{id}

Elimina un usuario del sistema. Esta operación está altamente restringida y incluye validaciones para prevenir eliminaciones que podrían comprometer la integridad de los datos.

**Respuesta Exitosa (200):**
```json
{
    "message": "Usuario eliminado exitosamente"
}
```

**Respuestas de Error:**
- **403 Forbidden:** Sin permisos para eliminar este usuario
- **409 Conflict:** Usuario tiene facturas asociadas y no puede eliminarse

El sistema implementa eliminación lógica en lugar de física para usuarios que tienen facturas asociadas. Esto preserva la integridad de los datos históricos y cumple con requisitos de auditoría. En estos casos, el usuario se marca como inactivo en lugar de eliminarse completamente.

Solo los super_admin pueden eliminar usuarios, y solo si no tienen facturas asociadas. Los accountant pueden desactivar empleados de su empresa, pero no eliminarlos completamente. Esta restricción asegura que no se pierda información importante para auditorías o reportes históricos.

### POST /api/users/{id}/change-password

Permite cambiar la contraseña de un usuario. Este endpoint implementa validaciones adicionales de seguridad para prevenir cambios no autorizados.

**Parámetros de Entrada:**
```json
{
    "current_password": "string (requerido si es el propio usuario)",
    "new_password": "string (requerido)",
    "confirm_password": "string (requerido)"
}
```

**Respuesta Exitosa (200):**
```json
{
    "message": "Contraseña actualizada exitosamente"
}
```

El comportamiento de este endpoint varía según quién hace la solicitud. Si un usuario cambia su propia contraseña, debe proporcionar la contraseña actual para verificación. Si un super_admin cambia la contraseña de otro usuario, no se requiere la contraseña actual, pero se debe proporcionar confirmación.

El sistema valida que la nueva contraseña y la confirmación coincidan, y que la nueva contraseña sea diferente de la actual. Aunque no se implementan restricciones específicas de complejidad en el backend, se recomienda que el frontend implemente validaciones apropiadas.

### Auditoría y Logging

Todas las operaciones de gestión de usuarios se registran en logs detallados que incluyen información sobre quién realizó la acción, cuándo se realizó, y qué cambios específicos se hicieron. Esta información es crucial para auditorías de seguridad y cumplimiento regulatorio.

Los logs incluyen información como direcciones IP, user agents, y timestamps precisos. En caso de actividades sospechosas, estos logs proporcionan la información necesaria para investigar y responder a posibles incidentes de seguridad.

---


## APIs de Gestión de Empresas

Las APIs de gestión de empresas proporcionan funcionalidades para administrar las empresas cliente del sistema. Estas APIs están diseñadas principalmente para usuarios con rol de super_admin, aunque algunos endpoints tienen acceso limitado para otros roles.

### GET /api/companies

Lista todas las empresas del sistema. Este endpoint está restringido a usuarios con rol de super_admin, ya que contiene información sensible de múltiples organizaciones.

**Parámetros de Query:**
- `page`: Número de página (default: 1)
- `per_page`: Elementos por página (default: 10)
- `search`: Búsqueda por nombre o RNC
- `status`: Filtrar por estado (active, inactive)

**Respuesta Exitosa (200):**
```json
{
    "companies": [
        {
            "id": 1,
            "name": "Empresa Demo S.R.L.",
            "rnc": "101-12345-6",
            "address": "Av. Winston Churchill #123, Santo Domingo",
            "phone": "809-555-0123",
            "email": "info@empresademo.com",
            "status": "active",
            "user_count": 5,
            "invoice_count": 150,
            "created_at": "2024-01-15T10:00:00Z"
        }
    ],
    "pagination": {
        "page": 1,
        "per_page": 10,
        "total": 25,
        "pages": 3
    }
}
```

La respuesta incluye información agregada como el número de usuarios y facturas asociadas a cada empresa, lo que proporciona una vista general útil para administradores del sistema.

### POST /api/companies

Crea una nueva empresa en el sistema. Solo usuarios con rol de super_admin pueden crear empresas.

**Parámetros de Entrada:**
```json
{
    "name": "string (requerido)",
    "rnc": "string (requerido, único)",
    "address": "string (opcional)",
    "phone": "string (opcional)",
    "email": "string (opcional)"
}
```

**Respuesta Exitosa (201):**
```json
{
    "message": "Empresa creada exitosamente",
    "company": {
        "id": 3,
        "name": "Nueva Empresa EIRL",
        "rnc": "130-98765-4",
        "address": "Calle Principal #456",
        "phone": "809-555-0456",
        "email": "contacto@nuevaempresa.com",
        "status": "active",
        "created_at": "2024-08-25T15:30:00Z"
    }
}
```

El sistema valida que el RNC sea único y tenga el formato correcto para República Dominicana. También verifica que el email, si se proporciona, tenga un formato válido y no esté en uso por otra empresa.

### GET /api/companies/{id}

Obtiene información detallada de una empresa específica. Los super_admin pueden acceder a cualquier empresa, mientras que los accountant solo pueden ver información de su empresa asignada.

**Respuesta Exitosa (200):**
```json
{
    "company": {
        "id": 1,
        "name": "Empresa Demo S.R.L.",
        "rnc": "101-12345-6",
        "address": "Av. Winston Churchill #123, Santo Domingo",
        "phone": "809-555-0123",
        "email": "info@empresademo.com",
        "status": "active",
        "created_at": "2024-01-15T10:00:00Z",
        "updated_at": "2024-08-20T11:45:00Z",
        "statistics": {
            "total_users": 5,
            "active_users": 4,
            "total_invoices": 150,
            "pending_invoices": 12,
            "approved_invoices": 138,
            "total_amount_current_month": 125000.50,
            "total_itbis_current_month": 22500.09
        }
    }
}
```

La respuesta incluye estadísticas detalladas que son útiles para dashboards y reportes ejecutivos. Estas estadísticas se calculan en tiempo real para asegurar precisión.

### PUT /api/companies/{id}

Actualiza información de una empresa existente. Los super_admin pueden actualizar cualquier empresa, mientras que los accountant pueden actualizar información limitada de su empresa.

**Parámetros de Entrada:**
```json
{
    "name": "string (opcional)",
    "address": "string (opcional)",
    "phone": "string (opcional)",
    "email": "string (opcional)",
    "status": "string (opcional, solo super_admin)"
}
```

Los accountant pueden actualizar información de contacto de su empresa, pero no pueden cambiar el estado o el RNC. El RNC nunca puede modificarse una vez creada la empresa, ya que es el identificador oficial ante la DGII.

### GET /api/companies/{id}/users

Lista los usuarios asociados a una empresa específica. Este endpoint es útil para gestionar el personal de cada organización.

**Respuesta Exitosa (200):**
```json
{
    "users": [
        {
            "id": 2,
            "username": "contador1",
            "email": "contador@empresa.com",
            "first_name": "María",
            "last_name": "González",
            "role": "accountant",
            "is_active": true,
            "last_login": "2024-08-25T09:15:00Z"
        }
    ],
    "company": {
        "id": 1,
        "name": "Empresa Demo S.R.L.",
        "rnc": "101-12345-6"
    }
}
```

---

## APIs de Gestión de Facturas

Las APIs de gestión de facturas constituyen el núcleo funcional del sistema, proporcionando capacidades completas para crear, gestionar y procesar facturas de compras. Estas APIs integran funcionalidades avanzadas como procesamiento OCR y validaciones específicas del formato 606.

### GET /api/invoices

Lista facturas con filtrado avanzado y paginación. Los resultados se filtran automáticamente según el rol del usuario para asegurar acceso apropiado a los datos.

**Parámetros de Query:**
- `page`: Número de página (default: 1)
- `per_page`: Elementos por página (default: 20)
- `search`: Búsqueda por número de factura, NCF o proveedor
- `status`: Filtrar por estado (pending, approved, rejected)
- `expense_type`: Filtrar por tipo de gasto (01-11)
- `date_from`: Fecha inicial (YYYY-MM-DD)
- `date_to`: Fecha final (YYYY-MM-DD)
- `supplier_rnc`: Filtrar por RNC del proveedor
- `created_by`: Filtrar por usuario creador (solo para accountant y super_admin)

**Respuesta Exitosa (200):**
```json
{
    "invoices": [
        {
            "id": 1,
            "invoice_number": "INV-20240801-ABC123",
            "ncf": "B0100000001",
            "supplier_name": "Suplidora Nacional S.A.",
            "supplier_rnc": "101-11111-1",
            "invoice_date": "2024-08-15",
            "payment_date": "2024-08-20",
            "invoiced_amount": 50000.00,
            "itbis_invoiced": 9000.00,
            "expense_type": "02",
            "expense_description": "Gastos por Trabajos, Suministros y Servicios",
            "status": "approved",
            "company_id": 1,
            "created_by_user": {
                "id": 3,
                "first_name": "Juan",
                "last_name": "Pérez"
            },
            "approved_by_user": {
                "id": 2,
                "first_name": "María",
                "last_name": "González"
            },
            "approved_at": "2024-08-16T10:30:00Z",
            "created_at": "2024-08-15T14:20:00Z"
        }
    ],
    "pagination": {
        "page": 1,
        "per_page": 20,
        "total": 150,
        "pages": 8
    },
    "summary": {
        "total_amount": 1250000.00,
        "total_itbis": 225000.00,
        "pending_count": 12,
        "approved_count": 138
    }
}
```

El endpoint implementa filtrado inteligente que permite búsquedas complejas combinando múltiples criterios. La funcionalidad de búsqueda de texto busca coincidencias en número de factura, NCF, nombre del proveedor y RNC del proveedor, facilitando encontrar facturas específicas rápidamente.

### POST /api/invoices

Crea una nueva factura manualmente. Este endpoint permite a usuarios crear facturas ingresando los datos directamente, sin necesidad de procesamiento OCR.

**Parámetros de Entrada:**
```json
{
    "invoice_number": "string (opcional)",
    "ncf": "string (requerido)",
    "supplier_name": "string (requerido)",
    "supplier_rnc": "string (requerido)",
    "supplier_id_type": "string (opcional, default: RNC)",
    "invoice_date": "string (requerido, YYYY-MM-DD)",
    "payment_date": "string (opcional, YYYY-MM-DD)",
    "invoiced_amount": "number (requerido)",
    "itbis_invoiced": "number (opcional)",
    "itbis_retained": "number (opcional)",
    "itbis_perceived": "number (opcional)",
    "income_retention": "number (opcional)",
    "isr_perceived": "number (opcional)",
    "selective_consumption_tax": "number (opcional)",
    "other_taxes": "number (opcional)",
    "legal_tip": "number (opcional)",
    "expense_type": "string (requerido, 01-11)"
}
```

**Respuesta Exitosa (201):**
```json
{
    "message": "Factura creada exitosamente",
    "invoice": {
        "id": 151,
        "invoice_number": "INV-20240825-XYZ789",
        "ncf": "B0100000151",
        "supplier_name": "Nuevo Proveedor S.A.",
        "supplier_rnc": "101-99999-9",
        "invoice_date": "2024-08-25",
        "invoiced_amount": 15000.00,
        "itbis_invoiced": 2700.00,
        "expense_type": "02",
        "expense_description": "Gastos por Trabajos, Suministros y Servicios",
        "status": "pending",
        "created_at": "2024-08-25T16:45:00Z"
    }
}
```

El sistema realiza validaciones exhaustivas de los datos de entrada, incluyendo formato de RNC dominicano, validez de fechas, y coherencia de montos. También verifica que el tipo de gasto especificado sea válido según los códigos oficiales de la DGII.

### POST /api/invoices/upload

Procesa una imagen de factura utilizando OCR para extraer automáticamente los datos. Este endpoint integra el servicio de inteligencia artificial para automatizar la entrada de datos.

**Parámetros de Entrada:**
- Archivo de imagen (multipart/form-data)
- Formatos soportados: PNG, JPG, JPEG, PDF
- Tamaño máximo: 16MB

**Respuesta Exitosa (201):**
```json
{
    "message": "Factura procesada exitosamente",
    "invoice": {
        "id": 152,
        "invoice_number": "INV-AUTO-20240825-001",
        "ncf": "B0100000152",
        "supplier_name": "Proveedor Extraído",
        "supplier_rnc": "101-88888-8",
        "invoice_date": "2024-08-20",
        "invoiced_amount": 8500.00,
        "itbis_invoiced": 1530.00,
        "expense_type": "02",
        "status": "pending",
        "ocr_confidence": 0.92,
        "image_path": "/uploads/invoices/152_20240825_164530.jpg"
    },
    "ocr_details": {
        "confidence": 0.92,
        "extracted_fields": {
            "supplier_name": 0.95,
            "supplier_rnc": 0.89,
            "ncf": 0.98,
            "invoice_date": 0.87,
            "invoiced_amount": 0.94,
            "itbis_invoiced": 0.91
        },
        "suggested_review": false
    }
}
```

El procesamiento OCR utiliza la API de OpenAI Vision para analizar la imagen y extraer información estructurada. El sistema proporciona niveles de confianza para cada campo extraído, permitiendo identificar datos que pueden requerir revisión manual.

### GET /api/invoices/{id}

Obtiene información detallada de una factura específica, incluyendo metadatos de procesamiento y historial de cambios.

**Respuesta Exitosa (200):**
```json
{
    "invoice": {
        "id": 1,
        "invoice_number": "INV-20240801-ABC123",
        "ncf": "B0100000001",
        "ncf_modified": "",
        "supplier_name": "Suplidora Nacional S.A.",
        "supplier_rnc": "101-11111-1",
        "supplier_id_type": "RNC",
        "invoice_date": "2024-08-15",
        "payment_date": "2024-08-20",
        "invoiced_amount": 50000.00,
        "itbis_invoiced": 9000.00,
        "itbis_retained": 0.00,
        "itbis_perceived": 0.00,
        "income_retention": 500.00,
        "isr_perceived": 0.00,
        "selective_consumption_tax": 0.00,
        "other_taxes": 0.00,
        "legal_tip": 0.00,
        "expense_type": "02",
        "expense_description": "Gastos por Trabajos, Suministros y Servicios",
        "status": "approved",
        "company": {
            "id": 1,
            "name": "Empresa Demo S.R.L.",
            "rnc": "101-12345-6"
        },
        "created_by_user": {
            "id": 3,
            "username": "empleado1",
            "first_name": "Juan",
            "last_name": "Pérez"
        },
        "approved_by_user": {
            "id": 2,
            "username": "contador1",
            "first_name": "María",
            "last_name": "González"
        },
        "approved_at": "2024-08-16T10:30:00Z",
        "image_path": "/uploads/invoices/1_20240815_142030.jpg",
        "ocr_confidence": 0.89,
        "created_at": "2024-08-15T14:20:00Z",
        "updated_at": "2024-08-16T10:30:00Z"
    }
}
```

### PUT /api/invoices/{id}

Actualiza una factura existente. Los permisos para edición varían según el rol del usuario y el estado actual de la factura.

**Parámetros de Entrada:**
```json
{
    "invoice_number": "string (opcional)",
    "ncf": "string (opcional)",
    "supplier_name": "string (opcional)",
    "supplier_rnc": "string (opcional)",
    "invoice_date": "string (opcional)",
    "payment_date": "string (opcional)",
    "invoiced_amount": "number (opcional)",
    "itbis_invoiced": "number (opcional)",
    "expense_type": "string (opcional)"
}
```

Los employee solo pueden editar sus propias facturas mientras estén en estado 'pending'. Los accountant pueden editar cualquier factura de su empresa, independientemente del estado. Los super_admin tienen acceso completo a todas las facturas.

### POST /api/invoices/{id}/approve

Aprueba una factura, cambiando su estado a 'approved'. Solo usuarios con rol de accountant o super_admin pueden aprobar facturas.

**Respuesta Exitosa (200):**
```json
{
    "message": "Factura aprobada exitosamente",
    "invoice": {
        "id": 1,
        "status": "approved",
        "approved_by_user_id": 2,
        "approved_at": "2024-08-25T16:50:00Z"
    }
}
```

### POST /api/invoices/{id}/reject

Rechaza una factura, cambiando su estado a 'rejected'. Opcionalmente permite incluir un comentario explicando el motivo del rechazo.

**Parámetros de Entrada:**
```json
{
    "rejection_reason": "string (opcional)"
}
```

### DELETE /api/invoices/{id}

Elimina una factura del sistema. Solo se permite eliminar facturas en estado 'pending' y únicamente por el usuario que las creó o por usuarios con permisos administrativos.

### GET /api/expense-types

Lista todos los tipos de gastos oficiales definidos por la DGII. Este endpoint es público para usuarios autenticados ya que la información es estándar y necesaria para la clasificación de facturas.

**Respuesta Exitosa (200):**
```json
{
    "expense_types": [
        {
            "id": "01",
            "name": "Gastos de Personal",
            "description": "Gastos relacionados con personal de la empresa",
            "is_active": true
        },
        {
            "id": "02",
            "name": "Gastos por Trabajos, Suministros y Servicios",
            "description": "Gastos operativos generales",
            "is_active": true
        }
    ]
}
```

---


## APIs de Reportes y Estadísticas

Las APIs de reportes proporcionan funcionalidades avanzadas para generar reportes en formato 606 oficial de la DGII, así como reportes analíticos para la gestión empresarial. Estas APIs integran el servicio especializado de generación de reportes y implementan controles de acceso granulares.

### POST /api/reports/606

Genera un reporte en formato 606 oficial de la DGII para un período específico. Este endpoint produce el archivo que debe ser enviado a la DGII para cumplir con las obligaciones fiscales.

**Parámetros de Entrada:**
```json
{
    "year": 2024,
    "month": 8,
    "company_id": 1,
    "include_pending": false
}
```

**Respuesta Exitosa (200):**
```json
{
    "success": true,
    "filename": "606_101-12345-6_202408.txt",
    "content": "606|101-12345-6|202408|3\n607|101-11111-1|1|B0100000001||20240815|20240820|5000000|900000|0|0|50000|0|0|0|0|02\n607|101-22222-2|1|B0100000002||20240818|20240825|2500000|450000|50000|0|0|0|0|0|0|02\n607|101-44444-4|1|B0100000004||20240822|20240830|3500000|630000|0|0|0|0|0|0|0|03",
    "company": {
        "id": 1,
        "name": "Empresa Demo S.R.L.",
        "rnc": "101-12345-6"
    },
    "period": "08/2024",
    "total_invoices": 3,
    "total_amount": 110000.00,
    "total_itbis": 19800.00,
    "invoices_summary": [...]
}
```

El contenido generado sigue estrictamente las especificaciones oficiales de la DGII, incluyendo el formato de línea de encabezado (606) y las líneas de detalle (607). Todos los montos se convierten a centavos y las fechas se formatean como YYYYMMDD según los requerimientos oficiales.

### POST /api/reports/606/download

Descarga directamente el archivo de reporte 606 como un archivo de texto. Este endpoint es útil para integración con sistemas automatizados que necesitan descargar el archivo directamente.

**Respuesta:** Archivo de texto con headers HTTP apropiados para descarga:
```
Content-Type: text/plain; charset=utf-8
Content-Disposition: attachment; filename="606_101-12345-6_202408.txt"
```

### GET /api/reports/dashboard

Proporciona datos agregados para dashboards ejecutivos, incluyendo estadísticas generales, facturas recientes y resúmenes por categorías.

**Parámetros de Query:**
- `company_id`: ID de empresa (opcional para super_admin)

**Respuesta Exitosa (200):**
```json
{
    "success": true,
    "statistics": {
        "total_invoices": 150,
        "pending_invoices": 12,
        "approved_invoices": 138,
        "rejected_invoices": 0,
        "total_amount": 1250000.00,
        "total_itbis": 225000.00,
        "monthly_count": 25,
        "monthly_amount": 185000.00
    },
    "recent_invoices": [...],
    "expense_summary": [
        {
            "expense_type": "02",
            "expense_description": "Gastos por Trabajos, Suministros y Servicios",
            "count": 85,
            "amount": 750000.00
        }
    ],
    "period": "08/2024"
}
```

### GET /api/reports/suppliers

Genera reportes detallados de gastos por proveedor, útiles para análisis de compras y gestión de proveedores.

**Parámetros de Query:**
- `year`: Año para filtrar (opcional)
- `month`: Mes para filtrar (opcional)
- `limit`: Número máximo de proveedores (default: 20)

**Respuesta Exitosa (200):**
```json
{
    "success": true,
    "suppliers": [
        {
            "supplier_name": "Suplidora Nacional S.A.",
            "supplier_rnc": "101-11111-1",
            "invoice_count": 15,
            "total_amount": 285000.00,
            "total_itbis": 51300.00,
            "last_invoice_date": "2024-08-22"
        }
    ],
    "total_suppliers": 45,
    "filters": {
        "year": 2024,
        "month": 8,
        "limit": 20
    }
}
```

### GET /api/reports/expense-types

Proporciona análisis detallado de gastos por tipo según las categorías oficiales de la DGII.

**Respuesta Exitosa (200):**
```json
{
    "success": true,
    "expense_types": [
        {
            "expense_type": "02",
            "expense_description": "Gastos por Trabajos, Suministros y Servicios",
            "invoice_count": 85,
            "total_amount": 750000.00,
            "total_itbis": 135000.00
        }
    ],
    "filters": {
        "year": 2024,
        "month": 8
    }
}
```

---

## Servicio de OCR

El servicio de OCR (Optical Character Recognition) utiliza la API de OpenAI Vision para extraer automáticamente información de imágenes de facturas. Este servicio es fundamental para automatizar la entrada de datos y reducir errores manuales.

### Arquitectura del Servicio OCR

El servicio OCR está implementado como una clase independiente que encapsula toda la lógica de procesamiento de imágenes. Esta arquitectura modular permite fácil mantenimiento y testing, además de facilitar futuras migraciones a otros proveedores de OCR si fuera necesario.

```python
class OCRService:
    def __init__(self):
        self.client = OpenAI()
        self.max_image_size = 16 * 1024 * 1024  # 16MB
        self.supported_formats = ['png', 'jpg', 'jpeg', 'pdf']
```

### Procesamiento de Imágenes

El servicio implementa un pipeline de procesamiento que optimiza las imágenes antes del análisis OCR. Este proceso incluye redimensionamiento automático para cumplir con los límites de la API, compresión inteligente que mantiene la legibilidad, y conversión de formatos cuando es necesario.

El sistema maneja automáticamente diferentes orientaciones de imagen y puede procesar tanto fotografías tomadas con dispositivos móviles como documentos escaneados. La optimización de imágenes asegura que el procesamiento sea eficiente en términos de tiempo y costo, mientras mantiene la precisión de extracción.

### Extracción de Datos Estructurados

El servicio utiliza prompts especializados que instruyen a la IA para extraer información específica relevante para facturas dominicanas. Estos prompts están diseñados para reconocer formatos locales de RNC, NCF, y otros elementos específicos del sistema fiscal dominicano.

La extracción produce datos estructurados que incluyen:
- RNC del proveedor con validación de formato
- NCF (Número de Comprobante Fiscal)
- Fechas de factura y pago
- Montos incluyendo ITBIS y otros impuestos
- Nombre y dirección del proveedor
- Descripción de productos o servicios

### Clasificación Automática de Gastos

Una característica avanzada del servicio OCR es la capacidad de sugerir automáticamente el tipo de gasto basándose en el contenido de la factura. El sistema analiza la descripción de productos o servicios y sugiere la categoría más apropiada según los 11 tipos oficiales de la DGII.

Esta funcionalidad utiliza técnicas de procesamiento de lenguaje natural para identificar patrones en las descripciones y mapearlos a las categorías correctas. Por ejemplo, facturas de combustible se clasifican automáticamente como tipo 09 (Compras y Gastos que Formaran Parte del Costo de Venta), mientras que facturas de servicios profesionales se clasifican como tipo 02.

### Niveles de Confianza

El servicio proporciona niveles de confianza para cada campo extraído, permitiendo al sistema identificar automáticamente datos que pueden requerir revisión manual. Estos niveles se calculan basándose en la claridad de la imagen, la consistencia de los datos extraídos, y la confianza reportada por la API de OpenAI.

Facturas con niveles de confianza bajos se marcan automáticamente para revisión manual, asegurando que datos críticos sean verificados antes de su procesamiento final. Este sistema de calidad automático reduce significativamente los errores en el procesamiento de facturas.

---

## Generador de Formato 606

El generador de formato 606 es un componente especializado que produce archivos en el formato oficial requerido por la DGII. Este servicio implementa todas las especificaciones técnicas del formato y asegura cumplimiento total con los requerimientos fiscales.

### Especificaciones del Formato

El formato 606 consiste en un archivo de texto plano con estructura específica que incluye una línea de encabezado (tipo 606) seguida de múltiples líneas de detalle (tipo 607). Cada línea utiliza el carácter pipe (|) como separador de campos y debe cumplir con longitudes y formatos específicos.

La línea de encabezado contiene:
- Tipo de registro (606)
- RNC de la empresa
- Período en formato YYYYMM
- Cantidad total de registros de detalle

Las líneas de detalle contienen 17 campos que incluyen toda la información fiscal requerida para cada factura, formateada según las especificaciones exactas de la DGII.

### Validaciones y Formateo

El generador implementa validaciones exhaustivas para asegurar que todos los datos cumplan con los requerimientos del formato. Esto incluye validación de longitudes de campo, formatos de fecha, precisión de montos, y códigos válidos para tipos de identificación y gastos.

El formateo de montos convierte automáticamente valores decimales a centavos (multiplicando por 100) y elimina puntos decimales según los requerimientos del formato. Las fechas se convierten al formato YYYYMMDD, y los campos de texto se truncan o rellenan según las especificaciones de longitud.

### Generación de Archivos

El servicio puede generar archivos para períodos específicos, filtrando automáticamente las facturas apropiadas y ordenándolas según los requerimientos del formato. El sistema permite incluir o excluir facturas pendientes de aprobación, proporcionando flexibilidad para diferentes escenarios de uso.

Los archivos generados incluyen metadatos adicionales como totales de control, número de registros, y resúmenes por tipo de gasto que facilitan la verificación y auditoría antes del envío a la DGII.

---

## Pruebas y Validación

El sistema incluye una suite completa de pruebas que valida tanto la funcionalidad como el rendimiento del backend. Las pruebas están organizadas en diferentes categorías para facilitar la ejecución selectiva y el mantenimiento.

### Pruebas Unitarias

Las pruebas unitarias validan componentes individuales del sistema, incluyendo modelos de datos, servicios, y funciones de utilidad. Estas pruebas se ejecutan rápidamente y proporcionan feedback inmediato durante el desarrollo.

Las pruebas del formato 606 son particularmente exhaustivas, validando cada aspecto de la generación de archivos incluyendo formateo de fechas, conversión de montos, y estructura de líneas. Estas pruebas utilizan datos de ejemplo que cubren casos normales y extremos.

### Pruebas de Integración

Las pruebas de integración validan el funcionamiento completo de las APIs, incluyendo autenticación, autorización, y procesamiento de datos. Estas pruebas utilizan un cliente HTTP simulado para enviar solicitudes reales a los endpoints y validar las respuestas.

La suite incluye pruebas para todos los flujos de usuario principales, desde el registro y login hasta la creación de facturas y generación de reportes. Los datos de prueba se crean automáticamente para asegurar un entorno consistente.

### Pruebas de Rendimiento

Las pruebas de rendimiento validan que el sistema puede manejar cargas de trabajo realistas sin degradación significativa del rendimiento. Estas pruebas incluyen escenarios con diferentes volúmenes de datos, desde 10 facturas hasta 5,000 facturas.

Los resultados muestran que el sistema puede procesar 1,000 facturas en menos de 0.02 segundos y mantiene un uso de memoria eficiente incluso con datasets grandes. Estas métricas aseguran que el sistema sea viable para empresas con altos volúmenes de facturas.

---

## Despliegue en Producción

El despliegue en producción requiere consideraciones específicas de seguridad, rendimiento y monitoreo. El sistema está diseñado para ser deployable en diferentes entornos, desde VPS simples hasta infraestructuras cloud complejas.

### Configuración de Servidor

Para producción se recomienda utilizar un servidor web robusto como Gunicorn o uWSGI detrás de un proxy reverso como Nginx. Esta configuración proporciona mejor rendimiento, manejo de conexiones concurrentes, y capacidades de load balancing.

La configuración de base de datos debe migrar de SQLite a PostgreSQL o MySQL para mejor rendimiento y capacidades de concurrencia. Las variables de entorno deben configurarse con valores seguros y específicos del entorno de producción.

### Seguridad

La seguridad en producción incluye configuración de HTTPS obligatorio, headers de seguridad apropiados, y configuración de CORS restrictiva. Las claves secretas deben generarse con alta entropía y mantenerse confidenciales.

El sistema debe configurarse con logging detallado para auditoría y monitoreo de seguridad. Se recomienda implementar rate limiting para prevenir ataques de fuerza bruta y DDoS.

### Monitoreo y Mantenimiento

El monitoreo en producción debe incluir métricas de rendimiento, logs de errores, y alertas automáticas para problemas críticos. Se recomienda utilizar herramientas como Prometheus para métricas y Grafana para visualización.

El mantenimiento regular incluye backups automáticos de la base de datos, actualizaciones de seguridad, y monitoreo del uso de la API de OpenAI para controlar costos.

---

## Próximos Pasos

Con el backend completamente desarrollado y probado, los próximos pasos se enfocan en el desarrollo del frontend y la integración completa del sistema.

### Fase 3: Desarrollo de Aplicaciones Frontend

La siguiente fase incluirá el desarrollo de la aplicación web para contadores y super administradores, así como la aplicación móvil para empleados. Estas aplicaciones utilizarán las APIs documentadas para proporcionar interfaces de usuario intuitivas y eficientes.

El frontend web implementará dashboards interactivos, formularios de gestión de facturas, y herramientas de generación de reportes. La aplicación móvil se enfocará en la captura fácil de facturas con cámara y gestión básica de datos.

### Integraciones Futuras

El sistema está diseñado para facilitar futuras integraciones con sistemas contables existentes, APIs de bancos para conciliación automática, y servicios de la DGII cuando estén disponibles.

También se planifica la implementación de funcionalidades avanzadas como análisis predictivo de gastos, alertas automáticas para anomalías, y reportes ejecutivos con visualizaciones interactivas.

### Escalabilidad y Optimización

Aunque el sistema actual maneja eficientemente volúmenes moderados de datos, futuras optimizaciones pueden incluir implementación de caching con Redis, optimización de consultas de base de datos, y arquitectura de microservicios para componentes específicos.

La implementación de procesamiento asíncrono para tareas pesadas como OCR y generación de reportes grandes mejorará la experiencia del usuario y permitirá mejor escalabilidad horizontal.

---

## Conclusión

El backend del Sistema de Gestión de Facturas 606 representa una solución completa y robusta para la automatización del cumplimiento fiscal en República Dominicana. La arquitectura modular, las APIs bien documentadas, y las pruebas exhaustivas aseguran que el sistema sea confiable, mantenible y escalable.

La integración de tecnologías modernas como inteligencia artificial para OCR, junto con el cumplimiento estricto de las especificaciones oficiales de la DGII, posiciona este sistema como una herramienta valiosa para empresas que buscan modernizar y automatizar sus procesos contables.

La documentación completa y las pruebas validadas facilitan el desarrollo continuo y la integración con otros sistemas, asegurando que la inversión en esta solución proporcione valor a largo plazo para las organizaciones que la implementen.

---

**Documento generado por Manus AI**  
**Fecha de generación:** Agosto 2024  
**Versión del sistema:** 1.0.0