📝 Descripción General

Los endpoints de comparador permiten realizar cálculos estimativos de costes anuales basados en los datos de consumo real de un punto de suministro (CUPS).

Existen dos grandes familias de endpoints:

• Estimación Anual (B2B / análisis):
  • POST /comparador_anual_tarifa — Comparación por ID de Tarifa.
  • POST /comparador_anual_tarifas_bulk — Comparación masiva (varias tarifas a la vez).
  • POST /comparador_anual_manual — Estimación con parámetros manuales.
• Comparador Web (frontend / portal cliente):
  • POST /comparador_web_cups — Comparativa mensual a partir del CUPS y todas las tarifas activas.
  • POST /comparador_web_factura — Comparativa de una factura real (CUPS + datos de la factura).
  • POST /comparador_web_datos_input — Comparativa sin CUPS, solo con los datos manuales del cliente (tarifa ATR + consumos + potencias).

🔍 Comparador Anual por Tarifa

Calcula el coste estimado anual aplicando las condiciones de una tarifa específica del sistema al histórico de consumo del CUPS.

Cuerpo de la Petición (JSON)

Ejemplo de Petición cURL

curl -X POST "http://localhost:5000/comparador_anual_tarifa" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"cups": "ES0031...", "id_tarifa": "123", "incluir_detalle_mensual": true}'

🚀 Comparador Anual Masivo (Bulk)

Calcula las estimaciones para una lista de tarifas en una única petición. Es el endpoint óptimo para interfaces que muestran comparativas completas.

Cuerpo de la Petición (JSON)

🛠️ Comparador Anual Manual

Realiza una estimación personalizada permitiendo configurar manualmente precios, fees y otros parámetros comerciales.

Cuerpo de la Petición (JSON)

Ejemplo de Petición

{
  "cups": "ES0031405678912345AB1F",
  "tipo_precio": "fijo",
  "precios_energia": {
    "p1": 0.15,
    "p2": 0.12,
    "p3": 0.08
  },
  "precios_potencia": {
    "p1": 35.5,
    "p2": 1.2
  }
}

📤 Estructura de Respuesta (Estimación Anual)

Los endpoints /comparador_anual_* devuelven un objeto con el resumen de la estimación y, opcionalmente, el detalle mensual.

{
  "cups": "ES0031405678912345AB1F",
  "tarifa_atr": "2.0TD",
  "tipo_precio": "fijo",
  "consumo_total_kwh": 4250.50,
  "coste_energia": 645.20,
  "coste_potencia": 320.15,
  "total": 965.35,
  "resultado_mensual": [
    {
      "mes_referencia": "01",
      "coste_total": 110.50,
      "coste_energia": 80.25,
      "coste_potencia": 30.25,
      ...
    }
  ]
}

🌐 Comparador Web

Familia de endpoints pensados para el portal web del cliente. Devuelven, para todas las tarifas activas en el sistema, una estimación completa de factura (energía + potencia + bono social + alquiler + impuestos) y señalan automáticamente la mejor tarifa (la de menor importe total).

🔍 Comparador Web por CUPS

Calcula la factura mensual equivalente que pagaría el cliente con cada una de las tarifas activas, utilizando el histórico de consumo real del CUPS obtenido de SIPS. Internamente calcula la factura anual con todos los conceptos (incluyendo IE, IVA, bono social y alquiler) y la divide entre 12.

Cuerpo de la Petición (JSON)

Ejemplo de Petición cURL

curl -X POST "http://localhost:5000/comparador_web_cups" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"cups": "ES0031405678912345AB1F", "origen": "web"}'

Ejemplo de Respuesta

{
  "cups": {
    "cups": "ES0031405678912345AB1F",
    "tarifa_atr": "2.0TD",
    "geo_zone": "PENINSULA",
    "provincia": "28",
    "potencias_kw": { "P1": 4.6, "P2": 4.6 },
    "consumo_total_anual_kwh": 4250.50,
    "consumo_periodos_anual_kwh": { "P1": 1500.0, "P2": 1250.5, "P3": 1500.0 },
    "consumo_medio_mensual_kwh": 354.21,
    "consumo_periodos_medio_kwh": { "P1": 125.0, "P2": 104.21, "P3": 125.0 },
    "origen": "web"
  },
  "tarifas": [
    {
      "tarifa_id": "123",
      "nombre_tarifa_precio": "Tarifa Plana 2.0TD",
      "alias_precio": "PLANA-2TD",
      "tipo_precio": "fijo",
      "coste_energia": 53.77,
      "coste_potencia": 26.68,
      "bono_social": 0.04,
      "alquiler": 0.81,
      "base_imponible": 81.30,
      "impuesto_electrico": 2.74,
      "iva": 17.65,
      "total_factura": 101.69
    },
    {
      "tarifa_id": "124",
      "nombre_tarifa_precio": "Tarifa Indexada PVPC+",
      "alias_precio": "IDX-PVPC",
      "tipo_precio": "indexado",
      "coste_energia": 49.10,
      "coste_potencia": 26.68,
      "bono_social": 0.04,
      "alquiler": 0.81,
      "base_imponible": 76.63,
      "impuesto_electrico": 2.58,
      "iva": 16.63,
      "total_factura": 95.84
    }
  ],
  "mejor_tarifa": {
    "tarifa_id": "124",
    "nombre_tarifa_precio": "Tarifa Indexada PVPC+",
    "alias_precio": "IDX-PVPC",
    "tipo_precio": "indexado",
    "total_factura": 95.84
  },
  "cups_imagina": 1
}

🧾 Comparador Web por Factura

Compara una factura real aportada por el cliente contra todas las tarifas activas. La tarifa ATR y la zona geográfica se obtienen automáticamente del CUPS, mientras que los consumos, potencias e importes los aporta el usuario tal y como aparecen en su factura. La comparativa se realiza para el periodo indicado (fecha_inicio_periodo – fecha_fin_periodo).

Cuerpo de la Petición (JSON)

Ejemplo de Petición cURL

curl -X POST "http://localhost:5000/comparador_web_factura" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "cups": "ES0031405678912345AB1F",
    "fecha_inicio_periodo": "2026-01-01",
    "fecha_fin_periodo":    "2026-01-31",
    "consumo_p1_kwh": 150.0,
    "consumo_p2_kwh": 120.0,
    "consumo_p3_kwh": 100.0,
    "potencia_p1_kw": 4.6,
    "potencia_p2_kw": 4.6,
    "total_potencia_eur": 26.50,
    "total_energia_eur": 55.20,
    "total_sin_impuestos_eur": 81.70,
    "total_impuestos_eur": 20.30,
    "total_factura_eur": 102.00,
    "referencia_externa": "fact-2026-0001",
    "origen": "web"
  }'

Ejemplo de Respuesta

{
  "factura_real": {
    "cups": "ES0031405678912345AB1F",
    "fecha_inicio_periodo": "2026-01-01",
    "fecha_fin_periodo": "2026-01-31",
    "dias_intervalo": 30,
    "tarifa_atr": "2.0TD",
    "geo_zone": "PENINSULA",
    "provincia": "28",
    "consumo_total_kwh": 370.0,
    "consumo_por_periodo_kwh": { "P1": 150.0, "P2": 120.0, "P3": 100.0, "P4": 0, "P5": 0, "P6": 0 },
    "potencias_kw": { "P1": 4.6, "P2": 4.6, "P3": 0, "P4": 0, "P5": 0, "P6": 0 },
    "total_potencia_eur": 26.50,
    "total_energia_eur": 55.20,
    "total_factura_eur": 102.00,
    "total_sin_impuestos_eur": 81.70,
    "total_impuestos_eur": 20.30,
    "referencia_externa": "fact-2026-0001",
    "origen": "web"
  },
  "tarifas": [
    {
      "tarifa_id": "123",
      "nombre_tarifa_precio": "Tarifa Plana 2.0TD",
      "alias_precio": "PLANA-2TD",
      "tipo_precio": "fijo",
      "coste_energia": 52.10,
      "coste_potencia": 25.80,
      "bono_social": 0.04,
      "alquiler": 0.78,
      "base_imponible": 78.72,
      "impuesto_electrico": 2.65,
      "iva": 17.09,
      "total_factura": 98.46,
      "ahorro_vs_factura_real": 3.54,
      "porcentaje_ahorro": 3.47
    }
  ],
  "mejor_tarifa": {
    "tarifa_id": "123",
    "nombre_tarifa_precio": "Tarifa Plana 2.0TD",
    "total_factura": 98.46,
    "ahorro_vs_factura_real": 3.54,
    "porcentaje_ahorro": 3.47
  },
  "cups_imagina": 1
}

📝 Comparador Web por Datos Manuales (sin CUPS)

Igual que /comparador_web_factura pero sin CUPS. El cliente introduce manualmente la tarifa_atr que tiene contratada y el resto de datos de la factura. Útil para simulaciones rápidas en formularios web cuando todavía no se dispone (o no se quiere consultar) el CUPS.

Cuerpo de la Petición (JSON)

Ejemplo de Petición cURL

curl -X POST "http://localhost:5000/comparador_web_datos_input" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tarifa_atr": "2.0TD",
    "fecha_inicio_periodo": "2026-01-01",
    "fecha_fin_periodo":    "2026-01-31",
    "consumo_p1_kwh": 150.0,
    "consumo_p2_kwh": 120.0,
    "consumo_p3_kwh": 100.0,
    "potencia_p1_kw": 4.6,
    "potencia_p2_kw": 4.6,
    "total_factura_eur": 102.00,
    "origen": "web"
  }'

Ejemplo de Respuesta

{
  "factura_real": {
    "fecha_inicio_periodo": "2026-01-01",
    "fecha_fin_periodo": "2026-01-31",
    "dias_intervalo": 31,
    "tarifa_atr": "2.0TD",
    "geo_zone": "PENINSULA",
    "consumo_total_kwh": 370.0,
    "consumo_por_periodo_kwh": { "P1": 150.0, "P2": 120.0, "P3": 100.0, "P4": 0, "P5": 0, "P6": 0 },
    "potencias_kw": { "P1": 4.6, "P2": 4.6, "P3": 0, "P4": 0, "P5": 0, "P6": 0 },
    "total_potencia_eur": null,
    "total_energia_eur": null,
    "total_factura_eur": 102.00,
    "total_sin_impuestos_eur": null,
    "total_impuestos_eur": null,
    "origen": "web"
  },
  "tarifas": [
    {
      "tarifa_id": "123",
      "nombre_tarifa_precio": "Tarifa Plana 2.0TD",
      "tipo_precio": "fijo",
      "coste_energia": 53.81,
      "coste_potencia": 26.66,
      "bono_social": 0.04,
      "alquiler": 0.81,
      "base_imponible": 81.32,
      "impuesto_electrico": 2.74,
      "iva": 17.65,
      "total_factura": 101.71,
      "ahorro_vs_factura_real": 0.29,
      "porcentaje_ahorro": 0.28
    }
  ],
  "mejor_tarifa": {
    "tarifa_id": "123",
    "nombre_tarifa_precio": "Tarifa Plana 2.0TD",
    "total_factura": 101.71,
    "ahorro_vs_factura_real": 0.29,
    "porcentaje_ahorro": 0.28
  },
  "cups_imagina": 0
}

📤 Estructura de Respuesta (Comparador Web)

Los endpoints /comparador_web_* comparten una estructura común:

• cups / factura_real: datos del suministro o de la factura introducida.
• tarifas: array con la simulación de cada tarifa activa. Para cada tarifa se devuelven los importes desglosados (coste_energia, coste_potencia, bono_social, alquiler, base_imponible, impuesto_electrico, iva, total_factura) y, en los endpoints de factura, el ahorro_vs_factura_real y el porcentaje_ahorro.
• mejor_tarifa: la tarifa con menor total_factura.
• cups_imagina: 1 si el CUPS pertenece a un contrato activo de Imagina (id_estado = 3 en public.contratos_suministro), 0 en caso contrario. En /comparador_web_datos_input siempre vale 0 (no hay CUPS).

❌ Errores Comunes