API de Gestión de la Energía
Documentación Completa
🚀 Bienvenido a la Documentación
Encuentra toda la información necesaria para integrar con la API de Gestión de la Energía. Nuestra documentación está diseñada para desarrolladores y proporciona ejemplos prácticos, guías de uso y referencias completas de todos nuestros endpoints.
Consultar datos de CUPS
Obtén información detallada de puntos de suministro mediante código CUPS
Datos de consumo mensualizados
Accede a consumos históricos mensualizados en formato compatible con Mendix
Consumos por períodos
Consulta consumos desglosados por períodos tarifarios
Datos anuales agregados
Obtén información de consumos anuales para análisis de tendencias
Integración con SIPS
Conecta directamente con el Sistema de Información del Punto de Suministro
Gráficos de Consumo
Visualización interactiva de consumos mensuales mediante Chart.js
Exportación de Datos
Exporta históricos de consumo directamente a formato CSV para análisis externo
Cálculos Optimizados
Algoritmos de alto rendimiento para estimaciones de precio fijo
📚 Endpoints Disponibles
Explora los diferentes endpoints disponibles en nuestra API.
/sips/<cups>
🔍 Consulta de Datos CUPS
Recupera información completa de un punto de suministro mediante su código CUPS. Incluye datos del cliente, características técnicas del punto de suministro y estado actual.
/sips_datos_consumos_mendix/<cups>
📊 Consumos Mensualizados (Mendix)
Obtiene los datos de consumo mensualizado en formato Mendix (XML). Ideal para integraciones con sistemas empresariales.
/sips_datos_consumos_periodos_mendix/<cups>
⚡ Consumos por Períodos (Mendix)
Devuelve consumos mensualizados desglosados por períodos tarifarios en formato Mendix (XML). Perfecto para análisis detallados de facturación.
/sips_datos_anuales_mendix/<cups>
📅 Consumos Anuales (Mendix)
Consulta datos de consumo agregados anualmente por períodos en formato Mendix (JSON). Útil para comparativas anuales y planificación energética.
/comparador_anual_...
⚖️ Comparador de Ofertas
Realiza estimaciones de ahorro y comparativas de costes anuales basadas en el consumo real del CUPS, ya sea contra tarifas existentes o parámetros manuales.
🌐 Comparador Web (Portal Cliente)
/comparador_web_cups
🔍 Comparador Web por CUPS
Devuelve la factura mensual equivalente con cada tarifa activa, calculada a partir del histórico real de consumo del CUPS. Incluye IE, IVA, bono social, alquiler y la mejor tarifa.
/comparador_web_factura
🧾 Comparador Web por Factura
Compara una factura real (CUPS + consumos + potencias + importes) contra todas las tarifas activas y devuelve el ahorro estimado por tarifa.
/comparador_web_datos_input
📝 Comparador Web por Datos Manuales
Comparativa sin CUPS: el cliente introduce manualmente la tarifa ATR, consumos, potencias y (opcionalmente) los importes de su factura para simular el ahorro.
🔥 Endpoints de Gas Natural
/sips_gas/<cups>
🔍 Consulta de Datos CUPS (Gas)
Recupera información completa de un punto de suministro de gas. Incluye peajes, distribuidora y estado.
/sips_datos_consumos_gas_mendix/<cups>
📊 Consumos Gas (Mendix)
Consumos históricos de gas en formato Mendix (XML).
/sips_..._periodos_gas_mendix/<cups>
⚡ Consumos Períodos Gas (Mendix)
Consumos desglosados por períodos tarifarios de gas (P1, P2) en formato Mendix (XML).
/sips_datos_anuales_gas_mendix/<cups>
📅 Consumos Anuales Gas (Mendix)
Resumen anual de consumo de gas por períodos en formato Mendix (JSON).
/sips_datos_anuales_gas_mendix_por_meses/<cups>
📈 Histórico Mensual Gas
Detalle mensual de consumo de gas para visualización de gráficos.
🛠️ Utilidades y Endpoints Adicionales
/sips/internal · /sips/external
🔁 Consulta global SIPS (elec / gas)
Endpoint unificado que devuelve los datos del CUPS según el type (elec
o gas). Si SIPS está vacío para el tipo solicitado, prueba el otro tipo y
distingue entre "CUPS no reconocido como electricidad/gas" y
"No hay datos para el CUPS". Las rutas internal y external
comparten handler.
/calcular_precios_finales
💶 Cálculo de precios finales
Calcula los precios finales de energía (EUR/kWh) y potencia (EUR/kW/año) sumando los
precios base de la tarifa (v_precios_base_materializada) más los extras
comerciales (extrae1..6 en EUR/MWh y extrap1..6 en EUR/kW/año).
Acepta un objeto, una lista o {"items":[...]} y devuelve siempre una lista
en el mismo orden.
/sips_datos_anuales_mendix_pre/<cups>
🧪 Consumos Anuales (Mendix PRE)
Variante del endpoint anual usada por el entorno PRE de Mendix. Misma estructura que
/sips_datos_anuales_mendix/<cups>.
/tarifas
📋 Listado de Tarifas
Listado completo de tarifas activas (proxy autenticado al microservicio de tarifas).
Incluye precios por período, codigo_atr, alias externo y modo de potencia
(BOE o libre).
📖 Recursos Adicionales
Documentación API Swagger
Explora nuestra documentación interactiva completa con Swagger UI. Prueba los endpoints, consulta esquemas y ejecuta solicitudes en tiempo real.
INTERACTIVODescargar OpenAPI Spec
Descarga el archivo YAML de especificación OpenAPI para importar en tus herramientas de desarrollo o generar código cliente.
YAMLGuía Completa Endpoint SIPS
Documentación detallada del endpoint principal de consulta de CUPS con ejemplos de uso, respuestas y manejo de errores.
GUÍAGuía de Comparador de Ofertas
Instrucciones detalladas para utilizar los endpoints de estimación anual, ejemplos de payloads para el comparador manual y desgloses de respuesta.
GUÍA📋 Changelog - Historial de Cambios
Lanzamiento API de Gestión de la Energía
- 🚀 Lanzamiento de la API de gestión de energía
- 🔍 Endpoint de consulta de datos CUPS desde SIPS
- 📊 Endpoints de consumos mensualizados en formato Mendix
- ⚡ Consulta de consumos por períodos tarifarios
- 📅 Endpoint de datos de consumo anuales agregados
- 📚 Documentación interactiva OpenAPI/Swagger
- 🔐 Integración segura con Sistema SIPS
Endpoints de Comparador
- ⚖️ Añadidos endpoints de comparación anual por tarifa e introducción manual
- 🔐 Implementación de seguridad JWT para endpoints de negocio
- 📖 Nueva documentación detallada para procesos de estimación
Optimización y Visualización
- 🚀 **Optimización Crítica:** Los cálculos de precio fijo ahora son instantáneos al evitar el perfilado horario innecesario.
- 📊 **Visualización de Datos:** Integración de Chart.js para mostrar el desglose mensual de consumos.
- 📥 **Exportación CSV:** Añadida funcionalidad para descargar los consumos históricos en formato CSV.
- ⚡ **Nuevo Endpoint:** `/sips_datos_anuales_mendix_por_meses` para obtener el histórico mensual detallado en JSON.
Caché, Bulk y Filtrado Técnico
- 🚀 **Bulk Estimation:** Nuevo endpoint `/comparador_anual_tarifas_bulk` para calcular múltiples ofertas en una sola llamada.
- ⚡ **Caché Inteligente:** Implementación de caché en memoria para datos SIPS (consumos perfilados), reduciendo latencia en cálculos masivos.
- 🔍 **Filtro ATR por Código:** El listado de tarifas ahora se filtra usando el código técnico `codigo_atr` (ej. 018) para máxima precisión.
- 🗺️ **Filtrado Geográfico:** Refinado el filtro por zona (`_PEN`, `_BAL`, `_CAN`) basado en el sistema eléctrico del SIPS.
- 📱 **UI Horizontal:** Nueva interfaz de listado compacta con estimaciones directas en cada tarjeta.
Soporte para Suministros de Gas
- 🔥 **Endpoints de Gas:** Añadida integración completa para consulta de CUPS de gas (`/sips_gas`).
- 📊 **Consumos Gas:** Nuevos endpoints para consumos mensualizados y por períodos específicos de gas.
- 📈 **Visualización:** Soporte para desglose mensual de gas compatible con los gráficos de la interfaz.
- 📖 **Documentación:** Actualizada la especificación OpenAPI y creadas guías específicas para integración de gas.
Endpoints unificados, precios finales y fallback inteligente de SIPS
- 🔁 **Consulta global SIPS:** Nuevos endpoints `POST /sips/internal` y `POST /sips/external` que reciben `{cups, type}` y devuelven los datos del CUPS sin tener que elegir endpoint específico por tipo (elec/gas).
- 🧠 **Fallback de tipo:** Si `obtener_datos_cups_global` recibe vacío para el tipo solicitado, prueba automáticamente el otro tipo y distingue entre **"CUPS no reconocido como electricidad/gas"** y **"No hay datos para el CUPS"**.
- 💶 **Nuevo endpoint `/calcular_precios_finales`:** Calcula los precios finales por período (P1–P6) de energía y potencia sumando los precios base (`v_precios_base_materializada`) más los extras comerciales (`extrae*`, `extrap*`). Soporta objeto único, lista o `{"items":[...]}`.
- 🧪 **Nuevo endpoint `/sips_datos_anuales_mendix_pre/{cups}`:** Variante usada por el entorno PRE de Mendix para el consumo anual agregado.
- 🔐 **Autenticación dual:** Confirmada la compatibilidad con token estático (`API_SECUR_TOKEN`) y JWT (`JWT_SECRET` / `JWT_SECRET_1`) vía el decorador `require_any_auth`.
- 📖 **Documentación:** OpenAPI y portal actualizados con los nuevos endpoints, schemas (`PeticionSipsGlobal`, `PeticionCalcularPreciosFinales`, `ResultadoCalcularPreciosFinales`) y comportamiento de fallback.