Diagrama de Facturacion Electronica

Resumen del Sistema

🎯 Operaciones Principales

• CONSULTAR: Lista de ingresos con opción de facturación electrónica
• VALIDAR: Verificación completa del ingreso y datos del tercero
• CONFIGURAR: Formulario de facturación con información pre-cargada
• PROCESAR: Generación de factura electrónica a través de API de Factus
• RESULTADO: Mostrar estado de la factura generada

🔧 Componentes Técnicos

• Controlador: FactusController para manejo de rutas y vistas
• Servicios: FacturaService, AuthService, CatalogService para lógica de negocio
• Vistas: Formulario de facturación y vista de resultados
• Rutas: RESTful con prefijos específicos para facturación electrónica
• Modelos: ingresos, terceros, credenciales_facturacion, users

🛡️ Características de Seguridad

• Autenticación requerida para acceder a facturación
• Validación de permisos por usuario (solo sus ingresos)
• Credenciales de Factus por usuario individual
• Tokens de acceso con cache y renovación automática
• Validación robusta de datos antes de envío a API

📊 Flujo de Facturación

1. Inicio del Proceso

• Usuario accede a lista de ingresos
• Selecciona ingreso para facturar electrónicamente
• Sistema valida que el ingreso pertenezca al usuario

2. Validación Previa

• Validar Ingreso: Verificar que tenga todos los datos necesarios
• Validar Tercero: Confirmar información del cliente
• Validar Credenciales: Verificar credenciales de Factus del usuario
• Validar Rangos: Confirmar rangos de numeración activos

3. Preparación de Datos

• Mapear Cliente: Convertir datos del tercero al formato de Factus
• Mapear Productos: Procesar productos/servicios del ingreso
• Calcular IVA: Determinar impuestos y descuentos
• Generar Referencia: Crear referencia única para la factura
• Determinar Forma de Pago: Configurar método y forma de pago

4. Comunicación con Factus

• Obtener Token: Autenticación con API de Factus
• Enviar Datos: Solicitud de validación de factura
• Procesar Respuesta: Manejo de éxito o errores

5. Resultado Final

• Éxito: Mostrar información de factura generada
• Error: Mostrar mensajes de error específicos
• Opciones: Descargar PDF, ver detalles, etc.

🔌 APIs de Factus Utilizadas

Autenticación

• POST /oauth/token: Obtener token de acceso

Facturación

• POST /v1/bills/validate: Validar y generar factura
• GET /v1/bills/show/{numero}: Obtener detalles de factura
• GET /v1/bills/download-pdf/{numero}: Descargar PDF

Catálogos

• GET /v1/numbering-ranges: Rangos de numeración
• GET /v1/municipalities: Municipios de Colombia
• GET /v1/tributes: Tributos e impuestos
• GET /v1/unit-measures: Unidades de medida

📄 Tipos de Datos Procesados

Información del Cliente

• Identificación (CC, NIT, CE, etc.)
• Datos personales/empresariales
• Dirección y ubicación geográfica
• Información de contacto

Información de Productos

• Código de referencia
• Nombre y descripción
• Cantidad y precio unitario
• IVA y descuentos
• Unidad de medida

Información de Pago

• Forma de pago (contado/crédito)
• Método de pago (efectivo, tarjeta, etc.)
• Fecha de vencimiento (si aplica)
• Observaciones

⚙️ Arquitectura Escalable

• Servicios Especializados: Separación de responsabilidades
• Cache Inteligente: Tokens y catálogos en memoria
• Manejo de Errores: Logging completo y mensajes específicos
• Validación Robusta: Múltiples capas de validación
• Configuración Flexible: Entornos de prueba y producción

🌐 Integración Externa

• Factus API: Proveedor de facturación electrónica
• Entornos: Sandbox para pruebas, Producción para facturas reales
• Credenciales: Por usuario para aislamiento de datos
• Sincronización: Catálogos actualizados automáticamente

📋 Rutas Disponibles

• GET /facturacion-electronica/{ingresoId}: Mostrar formulario
• POST /facturacion-electronica/procesar/{ingresoId}: Procesar factura
• POST /facturacion-electronica/generar/{ingresoId}: Generar factura
• GET /factus/probar-conexion: Probar conexión con Factus
• GET /factus/municipios: Obtener municipios
• POST /factus/municipio-id: Buscar ID de municipio
• GET /facturas/: Listar facturas generadas
• GET /facturas/{numeroFactura}: Ver detalles de factura
• GET /facturas/{numeroFactura}/descargar: Descargar PDF