openapi: 3.0.3
info:
  title: API de Gestión de la Energía
  description: |
    API para la gestión y consulta de información de puntos de suministro eléctrico.
    
    Esta API proporciona acceso a información del Sistema de Información del Punto de Suministro (SIPS),
    permitiendo consultar datos de CUPS, consumos mensualizados, consumos por períodos tarifarios
    y datos históricos anuales.
    
    ## Características principales
    
    - Consulta de información de puntos de suministro por CUPS
    - Obtención de consumos mensualizados
    - Consulta de consumos desglosados por períodos
    - Datos históricos anuales
    - Integración con sistema SIPS
    - Respuestas en formato JSON y XML
    
    ## Autenticación
    
    La API gestiona automáticamente la autenticación con el sistema SIPS.
    No se requiere autenticación adicional del cliente en esta versión.
    
    ## Límites de uso
    
    Se recomienda implementar caché en el lado del cliente para optimizar
    el número de consultas al sistema SIPS.
    
  version: 1.0.0
  contact:
    name: Equipo de Desarrollo
    email: desarrollo@example.com
  license:
    name: Propietario

security:
  - bearerAuth: []
    
servers:
  - url: http://localhost:5000
    description: Servidor de desarrollo local
  - url: https://api.example.com
    description: Servidor de producción

tags:
  - name: SIPS
    description: Endpoints de consulta al Sistema de Información del Punto de Suministro
  - name: Consumos
    description: Endpoints relacionados con consultas de consumo energético
  - name: Mendix
    description: Endpoints con formato compatible con Mendix
  - name: Comparador
    description: Endpoints para la comparación y estimación de ofertas energéticas
  - name: Gas
    description: Endpoints para consulta de puntos de suministro de Gas Natural

paths:
  /sips/{cups}:
    get:
      tags:
        - SIPS
      summary: Consulta de datos de CUPS
      description: |
        Obtiene información completa de un punto de suministro mediante su código CUPS.
        
        Este endpoint consulta el sistema SIPS y devuelve información detallada que incluye:
        - Datos del titular del contrato
        - Dirección del punto de suministro
        - Características técnicas (potencia, tensión, tipo de contador)
        - Información de tarifa contratada
        - Comercializadora y distribuidora
        - Estado actual del suministro
        - Última lectura disponible
        
        **Nota:** Este es el endpoint principal recomendado para validar la existencia
        de un CUPS antes de realizar otras operaciones.
        
      operationId: getDatosCups
      parameters:
        - name: cups
          in: path
          required: true
          description: |
            Código CUPS (Código Universal del Punto de Suministro) del punto de suministro.
            Debe ser un código válido de 20-22 caracteres alfanuméricos.
            
            Ejemplo: ES0031405678912345AB1F
          schema:
            type: string
            minLength: 20
            maxLength: 22
            pattern: '^ES[0-9]{16}[A-Z]{2}[0-9A-Z]{0,2}$'
            example: ES0031405678912345AB1F
      responses:
        '200':
          description: Información del CUPS obtenida exitosamente
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DatosCups'
              examples:
                ejemplo_completo:
                  summary: Respuesta completa con todos los datos
                  value:
                    cups: ES0031405678912345AB1F
                    direccion:
                      tipo_via: CALLE
                      nombre_via: MAYOR
                      numero: "15"
                      escalera: A
                      piso: "3"
                      puerta: B
                      codigo_postal: "28013"
                      municipio: MADRID
                      provincia: MADRID
                    titular:
                      nombre: JUAN GARCIA LOPEZ
                      tipo_documento: NIF
                      numero_documento: 12345678A
                      telefono: "666555444"
                      email: juan.garcia@email.com
                    caracteristicas_tecnicas:
                      tension: Baja Tensión
                      potencia_contratada:
                        p1: 3.45
                        p2: 3.45
                      potencia_maxima: 10.0
                      tipo_contador: Digital
                      telemedida: true
                    tarifa:
                      codigo: 2.0TD
                      descripcion: Tarifa 2.0TD - Baja tensión con discriminación horaria
                      peajes: 2.0TD
                    comercializadora:
                      nombre: COMERCIALIZADORA EJEMPLO S.A.
                      codigo: "0123"
                    distribuidora:
                      nombre: DISTRIBUIDORA ELECTRICA S.A.
                      codigo: "0001"
                    estado: activo
                    fecha_alta: "2020-05-15"
                    ultima_lectura:
                      fecha: "2025-11-30"
                      tipo: Real
                      activa: 1523.5
                      reactiva: 45.2
        '400':
          description: CUPS inválido o mal formado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: El código CUPS proporcionado no es válido
        '404':
          description: CUPS no proporcionado o no encontrado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: CUPS parameter is required
        '500':
          description: Error interno del servidor o error de conexión con SIPS
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Se ha producido un error interno contacte con em

  /sips_datos_consumos_mendix/{cups}:
    get:
      tags:
        - SIPS
        - Consumos
        - Mendix
      summary: Obtener consumos mensualizados (Mendix)
      description: |
        Obtiene los datos de consumo mensualizado de un punto de suministro en formato Mendix (XML).
        
        Este endpoint devuelve un histórico de consumos mensuales que incluye:
        - Consumo activo mensual
        - Consumo reactivo (si aplica)
        - Fechas de lectura
        - Información del periodo
        
        **Formato de respuesta:** XML
      operationId: getDatosConsumosMendix
      parameters:
        - name: cups
          in: path
          required: true
          description: Código CUPS del punto de suministro
          schema:
            type: string
            example: ES0031405678912345AB1F
      responses:
        '200':
          description: Datos de consumo mensualizado en formato XML
          content:
            application/xml:
              schema:
                type: string
                format: xml
              example: |
                <?xml version="1.0" encoding="UTF-8"?>
                <consumos>
                  <periodo>
                    <mes>2025-11</mes>
                    <consumo_activo>350.5</consumo_activo>
                    <consumo_reactivo>12.3</consumo_reactivo>
                    <fecha_lectura>2025-11-30</fecha_lectura>
                  </periodo>
                  <periodo>
                    <mes>2025-10</mes>
                    <consumo_activo>380.2</consumo_activo>
                    <consumo_reactivo>15.1</consumo_reactivo>
                    <fecha_lectura>2025-10-31</fecha_lectura>
                  </periodo>
                </consumos>
        '404':
          description: CUPS no proporcionado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Error interno del servidor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /sips_datos_consumos_periodos_mendix/{cups}:
    get:
      tags:
        - SIPS
        - Consumos
        - Mendix
      summary: Obtener consumos por períodos tarifarios (Mendix)
      description: |
        Obtiene los datos de consumo mensualizado desglosados por períodos tarifarios
        en formato Mendix (XML).
        
        Este endpoint es útil para:
        - Análisis detallado de facturación
        - Optimización de consumo por períodos
        - Cálculo de costes por tarifa horaria
        
        Los períodos pueden ser P1, P2, P3, etc., dependiendo de la tarifa contratada.
        
        **Formato de respuesta:** XML
      operationId: getDatosConsumosPeriodosMendix
      parameters:
        - name: cups
          in: path
          required: true
          description: Código CUPS del punto de suministro
          schema:
            type: string
            example: ES0031405678912345AB1F
      responses:
        '200':
          description: Datos de consumo por períodos en formato XML
          content:
            application/xml:
              schema:
                type: string
                format: xml
              example: |
                <?xml version="1.0" encoding="UTF-8"?>
                <consumos_periodos>
                  <periodo_mensual>
                    <mes>2025-11</mes>
                    <p1>120.5</p1>
                    <p2>150.3</p2>
                    <p3>79.7</p3>
                  </periodo_mensual>
                  <periodo_mensual>
                    <mes>2025-10</mes>
                    <p1>135.2</p1>
                    <p2>165.8</p2>
                    <p3>79.2</p3>
                  </periodo_mensual>
                </consumos_periodos>
        '404':
          description: CUPS no proporcionado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Error interno del servidor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /sips_datos_anuales_mendix/{cups}:
    get:
      tags:
        - SIPS
        - Consumos
        - Mendix
      summary: Obtener consumos anuales agregados (Mendix)
      description: |
        Obtiene los datos de consumo agregados anualmente por períodos tarifarios
        en formato Mendix (JSON).
        
        Este endpoint es ideal para:
        - Comparativas anuales de consumo
        - Planificación energética a largo plazo
        - Análisis de tendencias de consumo
        - Reporting anual
        
        Los datos incluyen el total anual desglosado por períodos P1, P2, P3, etc.
        
        **Formato de respuesta:** JSON
      operationId: getDatosAnualesMendix
      parameters:
        - name: cups
          in: path
          required: true
          description: Código CUPS del punto de suministro
          schema:
            type: string
            example: ES0031405678912345AB1F
      responses:
        '200':
          description: Datos de consumo anual agregado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsumosAnuales'
              example:
                cups: ES0031405678912345AB1F
                año: 2025
                consumo_total: 4250.5
                consumo_por_periodos:
                  p1: 1450.2
                  p2: 1820.5
                  p3: 979.8
                unidad: kWh
        '404':
          description: CUPS no proporcionado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Error interno del servidor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'


  /sips_datos_anuales_mendix_por_meses/{cups}:
    get:
      tags:
        - SIPS
        - Consumos
      summary: Obtener consumos anuales con detalle mensual (JSON)
      description: |
        Obtiene los datos de consumo del último año móvil desglosados mes a mes y por períodos tarifarios.
        
        Este nuevo endpoint devuelve un objeto JSON que incluye:
        - `desglose_mensual`: Array de objetos con el consumo P1-P6 de cada mes.
        - Datos técnicos del suministro (CUPS, Tarifa ATR, etc).
        
        Es el endpoint utilizado por la interfaz web para generar los gráficos de consumo.
      operationId: getDatosAnualesMeses
      parameters:
        - name: cups
          in: path
          required: true
          description: Código CUPS del punto de suministro
          schema:
            type: string
            example: ES0031405678912345AB1F
      responses:
        '200':
          description: Datos de consumo mensualizados obtenidos exitosamente
          content:
            application/json:
              schema:
                type: object
                properties:
                  cups:
                    type: string
                  desglose_mensual:
                    type: array
                    items:
                      type: object
                      properties:
                        mes:
                          type: string
                          example: "2025-01"
                        consumoEnergiaActivaEnWhP1:
                          type: number
                        consumoEnergiaActivaEnWhP2:
                          type: number
        '404':
          description: CUPS no encontrado
        '500':
          description: Error interno

  /sips_gas/{cups}:
    get:
      tags:
        - Gas
        - SIPS
      summary: Consulta de datos de CUPS (Gas)
      description: |
        Obtiene información completa de un punto de suministro de GAS mediante su código CUPS.
        
        A diferencia del endpoint de electricidad, este utiliza campos específicos para gas como `codigoPeajeEnVigor`.
      operationId: getDatosCupsGas
      parameters:
        - name: cups
          in: path
          required: true
          description: Código CUPS del punto de suministro de gas
          schema:
            type: string
            example: ES0201000000000000AB1F
      responses:
        '200':
          description: Información del CUPS de gas obtenida exitosamente
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DatosCupsGas'
        '404':
          description: CUPS no encontrado
        '500':
          description: Error interno

  /sips_datos_consumos_gas_mendix/{cups}:
    get:
      tags:
        - Gas
        - Consumos
        - Mendix
      summary: Consumos mensualizados de gas (Mendix)
      description: |
        Obtiene consumos históricos de gas en formato Mendix (XML).
      operationId: getConsumosGasMendix
      parameters:
        - name: cups
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: XML de consumos de gas
          content:
            application/xml:
              schema:
                type: string

  /sips_datos_consumos_periodos_gas_mendix/{cups}:
    get:
      tags:
        - Gas
        - Consumos
        - Mendix
      summary: Consumos de gas por períodos (Mendix)
      description: |
        Obtiene consumos de gas desglosados por períodos (P1 y P2) en formato Mendix (XML).
      operationId: getConsumosPeriodosGasMendix
      parameters:
        - name: cups
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: XML de consumos por períodos (Gas)
          content:
            application/xml:
              schema:
                type: string

  /sips_datos_anuales_gas_mendix/{cups}:
    get:
      tags:
        - Gas
        - Consumos
        - Mendix
      summary: Consumos anuales de gas agregados (Mendix)
      description: |
        Obtiene el resumen anual de consumo de gas desglosado por períodos P1 y P2 en formato Mendix (JSON).
      operationId: getConsumosAnualesGasMendix
      parameters:
        - name: cups
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: JSON de consumos anuales de gas
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsumosAnualesGas'

  /sips_datos_anuales_gas_mendix_por_meses/{cups}:
    get:
      tags:
        - Gas
        - Consumos
      summary: Detalle mensual de consumo anual de gas (JSON)
      description: |
        Endpoint utilizado para visualización de gráficos de gas. Devuelve el desglose mensual del último año.
      operationId: getConsumosAnualesMesesGas
      parameters:
        - name: cups
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: JSON con desglose mensual de gas
          content:
            application/json:
              schema:
                type: object

  /tarifas:
    get:
      tags:
        - Comparador
      summary: Listado de Tarifas disponibles
      description: |
        Obtiene el listado completo de tarifas que se pueden usar para realizar 
        comparaciones de estimación anual.
        
        **Nota:** Este endpoint requiere que el JWT original del usuario sea enviado 
        en la cabecera, ya que actúa como un proxy seguro hacia el microservicio de tarifas.
      operationId: getTarifas
      responses:
        '200':
          description: Listado de tarifas obtenido exitosamente
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                    nombre:
                      type: string
                    descripcion:
                      type: string
                    codigo_atr:
                      type: string
                      description: Código técnico de la tarifa (ej. 018 para 2.0TD)
                    alias_externo:
                      type: string
                    tipo_tarifa_precio:
                      type: string
                      enum: [Fijo, Indexado]
                    precio_potencia_boe:
                      type: string
                      enum: [S, N]
        '500':
          description: Error interno del servidor

  /comparador_anual_tarifas_bulk:
    post:
      tags:
        - Comparador
      summary: Comparador anual masivo (Bulk)
      description: |
        Realiza el cálculo de estimación anual para múltiples tarifas en una sola petición.
        
        Este es el endpoint recomendado para la interfaz web, ya que optimiza el uso de la 
        caché interna y reduce la latencia al consolidar las peticiones.
      operationId: postComparadorAnualTarifasBulk
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - cups
                - id_tarifas
              properties:
                cups:
                  type: string
                id_tarifas:
                  type: array
                  items:
                    type: string
                incluir_detalle_mensual:
                  type: boolean
                  default: false
      responses:
        '200':
          description: Mapa de resultados por ID de tarifa
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  $ref: '#/components/schemas/ResultadoComparacion'
        '401':
          description: No autorizado
        '500':
          description: Error interno del servidor

  /comparador_anual_tarifa:
    post:
      tags:
        - Comparador
      summary: Comparador anual por ID de tarifa
      description: |
        Calcula una estimación anual de costes comparando los datos de consumo del CUPS 
        contra una tarifa específica identificada por su ID.
        
        **Optimización:** Para tarifas de precio fijo, el sistema ahora utiliza sumas 
        directas mensuales en lugar de generar curvas horarias, lo que mejora significativamente 
        la velocidad de respuesta.
      operationId: postComparadorAnualTarifa
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - cups
                - id_tarifa
              properties:
                cups:
                  type: string
                id_tarifa:
                  type: string
                incluir_detalle_mensual:
                  type: boolean
                  description: Si es true, incluye el array `resultado_mensual` en la respuesta.
                  default: true
      responses:
        '200':
          description: Estimación calculada exitosamente
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultadoComparacion'
        '401':
          description: No autorizado (JWT inválido o ausente)
        '404':
          description: CUPS o Tarifa no encontrados
        '500':
          description: Error interno del servidor

  /comparador_anual_manual:
    post:
      tags:
        - Comparador
      summary: Comparador anual con datos manuales
      description: |
        Realiza una estimación anual de costes permitiendo especificar manualmente 
        los parámetros de la oferta (precios de energía, potencia, fees, etc.).
      operationId: postComparadorAnualManual
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PeticionComparadorManual'
      responses:
        '200':
          description: Estimación calculada exitosamente
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultadoComparacion'
        '401':
          description: No autorizado (JWT inválido o ausente)
        '400':
          description: Datos de entrada inválidos
        '500':
          description: Error interno del servidor

components:
  schemas:
    DatosCups:
      type: object
      description: Información completa de un punto de suministro
      properties:
        cups:
          type: string
          description: Código CUPS del punto de suministro
          example: ES0031405678912345AB1F
        direccion:
          $ref: '#/components/schemas/Direccion'
        titular:
          $ref: '#/components/schemas/Titular'
        caracteristicas_tecnicas:
          $ref: '#/components/schemas/CaracteristicasTecnicas'
        tarifa:
          $ref: '#/components/schemas/Tarifa'
        comercializadora:
          $ref: '#/components/schemas/Empresa'
        distribuidora:
          $ref: '#/components/schemas/Empresa'
        estado:
          type: string
          description: Estado actual del suministro
          enum: [activo, suspendido, baja]
          example: activo
        fecha_alta:
          type: string
          format: date
          description: Fecha de alta del suministro
          example: "2020-05-15"
        ultima_lectura:
          $ref: '#/components/schemas/Lectura'
    
    Direccion:
      type: object
      description: Información de la dirección del punto de suministro
      properties:
        tipo_via:
          type: string
          example: CALLE
        nombre_via:
          type: string
          example: MAYOR
        numero:
          type: string
          example: "15"
        escalera:
          type: string
          example: A
        piso:
          type: string
          example: "3"
        puerta:
          type: string
          example: B
        codigo_postal:
          type: string
          example: "28013"
        municipio:
          type: string
          example: MADRID
        provincia:
          type: string
          example: MADRID
    
    Titular:
      type: object
      description: Información del titular del contrato
      properties:
        nombre:
          type: string
          example: JUAN GARCIA LOPEZ
        tipo_documento:
          type: string
          enum: [NIF, NIE, CIF, PASAPORTE]
          example: NIF
        numero_documento:
          type: string
          example: 12345678A
        telefono:
          type: string
          example: "666555444"
        email:
          type: string
          format: email
          example: juan.garcia@email.com
    
    CaracteristicasTecnicas:
      type: object
      description: Características técnicas del punto de suministro
      properties:
        tension:
          type: string
          example: Baja Tensión
        potencia_contratada:
          type: object
          properties:
            p1:
              type: number
              format: float
              example: 3.45
            p2:
              type: number
              format: float
              example: 3.45
        potencia_maxima:
          type: number
          format: float
          example: 10.0
        tipo_contador:
          type: string
          example: Digital
        telemedida:
          type: boolean
          example: true
    
    Tarifa:
      type: object
      description: Información de la tarifa contratada
      properties:
        codigo:
          type: string
          example: 2.0TD
        descripcion:
          type: string
          example: Tarifa 2.0TD - Baja tensión con discriminación horaria
        peajes:
          type: string
          example: 2.0TD
    
    Empresa:
      type: object
      description: Información de empresa (comercializadora o distribuidora)
      properties:
        nombre:
          type: string
          example: COMERCIALIZADORA EJEMPLO S.A.
        codigo:
          type: string
          example: "0123"
    
    Lectura:
      type: object
      description: Información de la última lectura del contador
      properties:
        fecha:
          type: string
          format: date
          example: "2025-11-30"
        tipo:
          type: string
          enum: [Real, Estimada]
          example: Real
        activa:
          type: number
          format: float
          description: Energía activa en kWh
          example: 1523.5
        reactiva:
          type: number
          format: float
          description: Energía reactiva en kVArh
          example: 45.2
    
    ConsumosAnuales:
      type: object
      description: Datos de consumo anual agregado
      properties:
        cups:
          type: string
          example: ES0031405678912345AB1F
        año:
          type: integer
          example: 2025
        consumo_total:
          type: number
          format: float
          description: Consumo total anual en kWh
          example: 4250.5
        consumo_por_periodos:
          type: object
          properties:
            p1:
              type: number
              format: float
              example: 1450.2
            p2:
              type: number
              format: float
              example: 1820.5
            p3:
              type: number
              format: float
              example: 979.8
        unidad:
          type: string
          example: kWh

    ConsumosAnualesGas:
      type: object
      description: Datos de consumo anual agregado para Gas
      properties:
        cups:
          type: string
        año:
          type: integer
        consumo_total:
          type: number
          description: Consumo total anual en kWh
        consumo_por_periodos:
          type: object
          properties:
            p1:
              type: number
            p2:
              type: number
        unidad:
          type: string
          default: kWh

    DatosCupsGas:
      type: object
      description: Información de un punto de suministro de gas
      properties:
        cups:
          type: string
        direccion:
          $ref: '#/components/schemas/Direccion'
        titular:
          $ref: '#/components/schemas/Titular'
        peaje:
          type: string
          example: RL.2
        comercializadora:
          type: string
        distribuidora:
          type: string
        estado:
          type: string
        fecha_alta:
          type: string
          format: date

    ResultadoComparacion:
      type: object
      description: Resultado del cálculo de estimación y comparación
      properties:
        cups:
          type: string
        resumen_anual:
          type: object
          properties:
            coste_total_estimado:
              type: number
            ahorro_estimado:
              type: number
        desglose_energia:
          type: object
        desglose_potencia:
          type: object
        resultados_mensuales:
          type: array
          description: Resultados detallados mes a mes
          items:
            type: object
            properties:
              mes:
                type: string
                example: "2025-01"
              coste_total:
                type: number
              coste_energia:
                type: number
              coste_potencia:
                type: number

    PeticionComparadorManual:
      type: object
      required:
        - cups
      properties:
        cups:
          type: string
        tipo_precio:
          type: string
          enum: [fijo, indexado]
        precios_energia:
          type: object
        precios_potencia:
          type: object
        fee:
          type: number

    Error:
      type: object
      description: Estructura de respuesta de error
      required:
        - error
      properties:
        error:
          type: string
          description: Mensaje descriptivo del error
          example: CUPS parameter is required

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |
        Utilice el token JWT obtenido a través del proceso de autenticación de Supabase.
        El token debe incluirse en la cabecera 'Authorization' con el prefijo 'Bearer '.
