📝 Descripción

Dado un rango futuro (fecha de inicio + duración en meses) y un consumo expresado bien como CUPS (uno o varios), bien como tarifa_atr + consumo (total o por periodos), el ofertador:

1. Perfila el consumo del cliente sobre el último año móvil disponible en prices.precios_ofertador_a2_c2.
2. Calcula el hedging promediando settlement_price_electric en prices.futuros_electricos para los date del rango de oferta.
3. Aplica el apuntamiento proyectado por periodo, los componentes horarios (SSAA, pagos por capacidad), los regulados BOE del year_regulado (por defecto, año en curso) y los aportes secuenciales de pérdidas, tasa y coste financiero.
4. Suma comision y risk_premium para consolidar el precio_total.
5. Opcionalmente aplica un reajuste post-cálculo por tarifa (mover precio_total de periodos concretos preservando el ponderado por consumo).

Si se aportan varios CUPS, los válidos se agrupan por tarifa ATR y se genera un lote por tarifa. Los CUPS que fallan quedan en entrada.cups_invalidos.

🔐 Autenticación

Cabecera Authorization: Bearer <TOKEN>. Acepta token estático API_SECUR_TOKEN o JWT firmado con JWT_SECRET / JWT_SECRET_1.

📥 Cuerpo de la petición

Campos requeridos

Entrada del consumo — elige UN camino

Camino A: por CUPS (recomendado si se dispone del CUPS).

Camino B: sin CUPS, aportando tarifa + consumo.

Parámetros de la oferta (opcionales)

Reajuste post-cálculo (opcional)

Ejemplo — oferta con lista de CUPS

{
  "fecha_inicio_oferta": "2026-08-01",
  "duracion_meses": 12,
  "cups": ["ES0021000013654684FH", "ES0021000012601426YE"],
  "tipo_campania": "campaña",
  "comision_eur_mwh": 0.5,
  "risk_premium_eur_mwh": 0.6,
  "coste_financiero_pct": 0.25,
  "servicios_ajuste_eur_mwh": 12
}

Ejemplo — sin CUPS con consumo por periodos y reajuste

{
  "fecha_inicio_oferta": "2026-08-01",
  "duracion_meses": 12,
  "tarifa_atr": "3.0TD",
  "consumo_periodos_kwh": {
    "P1": 200000, "P2": 150000, "P3": 250000,
    "P4": 100000, "P5": 120000, "P6": 180000
  },
  "tipo_campania": "campaña",
  "comision_eur_mwh": 0.5,
  "risk_premium_eur_mwh": 0.6,
  "servicios_ajuste_eur_mwh": 12,
  "hedging_eur_mwh": 60.0,
  "ajustes_por_tarifa": {
    "3.0TD": {"P1": -3.0, "P4": 1.0, "delta_ponderado": 0.2}
  },
  "metodo_ajuste": "inverso_peso"
}

Ejemplo — fee de campaña manual (tipo_campania='manual')

Cuando la combinación (tarifa, tipo_campania) no está en la tabla o se quiere probar un fee "a mano" sin tocarla, se usa 'manual' y se aportan las componentes del fee como parámetros (desvios_eur_mwh, margen_eur_mwh, gos_eur_mwh obligatorios; resto_eur_mwh opcional, default 0). En este modo la tabla no se consulta.

{
  "fecha_inicio_oferta": "2026-08-01",
  "duracion_meses": 12,
  "tarifa_atr": "3.0TD",
  "consumo_total_kwh": 500000,
  "tipo_campania": "manual",
  "desvios_eur_mwh": 2.5,
  "margen_eur_mwh": 6.0,
  "gos_eur_mwh": 1.2,
  "resto_eur_mwh": 0.0,
  "comision_eur_mwh": 0.5,
  "risk_premium_eur_mwh": 0.6,
  "servicios_ajuste_eur_mwh": 12
}

📤 Respuesta exitosa (200 OK)

El resultado se estructura en 4 bloques de nivel superior (oferta, parametros, entrada, lotes). Cada lote contiene los sub-bloques consumo, inputs_calculo, energia_eur_mwh, potencia_eur_kw_anio, componentes_precio_final y opcionalmente ajuste.

Principios de diseño del payload:

• Cada dato aparece una sola vez. Los escalares comunes a todos los periodos viven en energia_eur_mwh.escalares_comunes y no se repiten dentro de cada por_periodo[Pi].
• Energía y potencia separadas (bloques energia_eur_mwh vs potencia_eur_kw_anio).
• Periodos como claves en los dicts de vista por periodo: {"P1": {...}, ..., "P6": {...}, "ponderado": {...}}. El ponderado por consumo es una entrada más con las mismas claves.
• Los sufijos _eur_mwh / _eur_kw_anio se omiten dentro de bloques cuyo nombre ya lo indica.

Estructura general

{
  "oferta": {
    "fecha_inicio": "2026-08-01",
    "fecha_fin": "2027-07-31",
    "duracion_meses": 12,
    "geo_zone": "PENINSULA",
    "tipo_campania": "campaña",
    "rango_historico": {"fecha_inicio": "2025-01-01", "fecha_fin": "2025-12-31"}
  },
  "parametros": {
    "hedging_eur_mwh": 68.4321,
    "comision_eur_mwh": 0.5,
    "risk_premium_eur_mwh": 0.6,
    "servicios_ajuste_eur_mwh": 12.0,
    "coste_financiero_pct": 0.25,
    "year_regulado": 2026
  },
  "entrada": {
    "cups_invalidos": [{"cups": "ES...", "error": "SIPS timeout"}]
  },
  "lotes": [ /* ver más abajo */ ]
}

Cada lote (caso OK)

{
  "tarifa_atr": "3.0TD",
  "cups": ["ES0021000013654684FH", "ES0021000012601426YE"],
  "num_cups": 2,

  "consumo": {
    "total_kwh": 1234567.89,
    "por_periodo_kwh": {"P1": 200000, "P2": 150000, "P3": 250000,
                        "P4": 100000, "P5": 120000, "P6": 180000},
    "peso_periodo":    {"P1": 0.1621, "P2": 0.1216, "P3": 0.2027,
                        "P4": 0.0811, "P5": 0.0973, "P6": 0.1459}
  },

  "inputs_calculo": {
    "fee_campania_eur_mwh": {
      "desvios": 0.75, "margen": 6.5, "gos": 1.2, "resto": 2.05, "fnee": 3.5
    },
    "regulados_boe_eur_mwh": {
      "peajes_cargos":   {"P1": 24.31, "P2": 18.09, "P3": 4.83, "P4": 4.83, "P5": 4.83, "P6": 0.83},
      "pagos_capacidad": {"P1":  3.05, "P2":  1.52, "P3": 0.19, "P4": 0.19, "P5": 0.19, "P6": 0.19},
      "remuneracion_omie": 0.12,
      "remuneracion_ree":  0.24
    }
  },

  "energia_eur_mwh": {
    "escalares_comunes": {
      "hedging":            68.4321,
      "remuneracion_omie":   0.12,
      "remuneracion_ree":    0.24,
      "desvios":             0.75,
      "gdos_solares":        1.20,
      "margen_neto":         6.50,
      "aportacion_fondos":   5.55,
      "comision":            0.50,
      "risk_premium":        0.60
    },
    "por_periodo": {
      "P1": {
        "apuntamiento_pct":          8.4321,
        "apuntamiento":              5.7712,
        "servicios_ajuste":         12.0000,
        "pagos_capacidad":           3.0512,
        "peajes_cargos":            24.3110,
        "perdidas":                  6.4210,
        "tasa_municipal":            2.0140,
        "coste_financiero":          0.3430,
        "precio_indexado":         128.9155,
        "precio_indexado_efectivo":137.6935,
        "precio_total":            138.7935
      },
      "P2": { ... }, "P3": { ... }, "P4": { ... }, "P5": { ... }, "P6": { ... },
      "ponderado": { /* mismas claves que un periodo */ }
    }
  },

  "potencia_eur_kw_anio": {
    "P1": 22.980000, "P2": 18.440000, "P3": 11.120000,
    "P4":  8.310000, "P5":  5.020000, "P6":  0.650000
  },

  "componentes_precio_final": {
    "P1": {
      "PRECIO TERMINO DE ENERGIA":       138.79,
      "HEDGING":                          68.43,
      "APUNTAMIENTO":                      5.77,
      "SERVICIOS DE AJUSTE":              12.00,
      "DESVIOS":                           0.75,
      "GDOS SOLARES":                      1.20,
      "PERDIDAS":                          6.42,
      "RISK PREMIUM":                      0.60,
      "APORTACION FONDOS":                 5.55,
      "MARGEN NETO":                       6.50,
      "COMISION":                          0.50,
      "PEAJES, CARGOS Y PAGOS CAPAC.":    27.36,
      "OTROS COSTES":                      2.72
    },
    "P2": { /* 13 categorías */ }, ..., "P6": { /* 13 categorías */ },
    "ponderado": { /* 13 categorías */ }
  }
}

Notas sobre los bloques

• consumo: por_periodo_kwh viene siempre relleno (derivado del perfilado, aunque el input haya sido consumo_total_kwh). peso_periodo es la fracción de consumo de cada periodo sobre el total.
• energia_eur_mwh: precio_total = precio_indexado_efectivo + escalares_comunes.comision + escalares_comunes.risk_premium. Los escalares se aplican una sola vez; NO están repetidos dentro de por_periodo[Pi]. apuntamiento_pct del ponderado se recalcula como apuntamiento / hedging · 100.
• potencia_eur_kw_anio: peajes + cargos BOE de potencia por periodo, en €/kW·año. Independiente de la energía.
• componentes_precio_final: vista comercial invertida (periodo → 13 categorías) lista para pintar como tabla (columna por periodo + columna ponderado).

♻️ Reajuste inline (lote.ajuste)

Si se informa ajustes_por_tarifa en la petición, cada lote afectado devuelve inline el bloque ajuste con el resumen. Los lotes sin ajuste no llevan esa clave.

"ajuste": {
  "tarifa_atr":                 "3.0TD",
  "ponderado_original_eur_mwh": 148.32,
  "ponderado_objetivo_eur_mwh": 148.52,
  "ponderado_final_eur_mwh":    148.52,
  "deltas_aplicados_eur_mwh":   {"P1": -3.0, "P2": 0.84, "P3": 0.84,
                                 "P4": 1.84, "P5": 0.84, "P6": 0.84}
}

Además, dentro de energia_eur_mwh.por_periodo[P] aparece la clave reajuste con el delta neto acumulado aplicado a ese periodo (positivo = subida). Se acumula si el ajuste se invoca varias veces sobre el mismo lote.

❌ Lote con error

Cuando el lote no puede calcularse (fee de campaña ausente para el par (tarifa_atr, tipo_campania), sin datos horarios, etc.), el lote lleva solo tarifa_atr, cups, num_cups y la clave error. Ni consumo, ni inputs_calculo, ni energia_eur_mwh, ni potencia_eur_kw_anio aparecen en ese caso. El resto de lotes se calcula normalmente.

{
  "tarifa_atr": "6.4TD",
  "cups": [...],
  "num_cups": 3,
  "error": "fee indexado: No hay precio campaña en precios_campania_index_b2b para tarifa=6.4TD tipo=campaña"
}

❌ Errores HTTP

💻 Ejemplos

cURL

curl -X POST "https://api.imaginaenergia.com/ofertar" \
  -H "Authorization: Bearer <JWT>" \
  -H "Content-Type: application/json" \
  -d '{
    "fecha_inicio_oferta": "2026-08-01",
    "duracion_meses": 12,
    "tarifa_atr": "3.0TD",
    "consumo_total_kwh": 1000000,
    "tipo_campania": "campaña",
    "comision_eur_mwh": 0.5,
    "risk_premium_eur_mwh": 0.6,
    "servicios_ajuste_eur_mwh": 12
  }'

Python (requests)

import requests

body = {
    "fecha_inicio_oferta": "2026-08-01",
    "duracion_meses": 12,
    "cups": ["ES0021000013654684FH", "ES0021000012601426YE"],
    "tipo_campania": "campaña",
    "comision_eur_mwh": 0.5,
    "risk_premium_eur_mwh": 0.6,
    "servicios_ajuste_eur_mwh": 12,
    "ajustes_por_tarifa": {
        "3.0TD": {"P1": -3.0, "delta_ponderado": 0.2}
    },
}
r = requests.post(
    "https://api.imaginaenergia.com/ofertar",
    headers={"Authorization": f"Bearer {jwt}"},
    json=body,
    timeout=120,
)
res = r.json()
for lote in res["lotes"]:
    if "error" in lote:
        print(lote["tarifa_atr"], "→", lote["error"])
        continue
    pond = lote["energia_eur_mwh"]["por_periodo"]["ponderado"]
    print(lote["tarifa_atr"], "€/MWh medio:", pond["precio_total"])