API de exportación de métricas

Extrae datos de series temporales procesados y listos para informes de tus plantas en una sola llamada — para un parque, varios parques o portfolios completos. El sistema de exportación se basa en plantillas que definen qué métricas exportar y en qué orden, de modo que los mismos números que ves en un informe generado son los números que extraes a través de la API.

La descarga CSV canónica es GET /v1/export/metrics/template/{template_uid}. Una variante JSON y una exportación de series temporales en bruto independiente cubren los gráficos dentro de la aplicación y las curvas de potencia de alta resolución; las tres se describen a continuación.

Abrir en Mirox

Crea y ejecuta una exportación de forma interactiva en Exportación de datos ▸ Constructor, o gestiona tus plantillas en Exportación de datos ▸ Plantillas. Las mismas plantillas y métricas descritas aquí alimentan tanto el constructor dentro de la aplicación como la API.

Comprensión de los tipos de métricas

La plataforma Mirox trabaja con dos tipos distintos de métricas que cumplen propósitos diferentes:

Recopilación de métricas en bruto

Las métricas en bruto son la base de la infraestructura de datos de la plataforma. Estas métricas son:

Recopiladas directamente del hardware: extraídas de inversores, sensores y data loggers
Almacenadas tal cual en la base de datos de series temporales: conservan la granularidad y la estructura originales
Optimizadas para la monitorización en tiempo real: permiten paneles en vivo y consultas instantáneas
Multidimensionales: usan etiquetas para dividir los datos por componente, ubicación o tipo
Contadores acumulativos: a menudo almacenan valores de energía total que aumentan con el tiempo
Alta frecuencia: pueden recopilarse cada pocos segundos o minutos

Las métricas en bruto son esenciales para el funcionamiento del sistema, pero no están optimizadas para una exportación de datos fácil de usar. Requieren transformación, agregación e interpretación para convertirse en métricas de negocio significativas.

Para información detallada sobre la recopilación de métricas en bruto, consulta Arquitectura de recopilación de métricas.

Métricas de exportación

Las métricas de exportación son métricas procesadas y fáciles de usar, diseñadas específicamente para la exportación de datos y la elaboración de informes:

Preagregadas: calculadas a diario de forma predeterminada
Limpiadas y validadas: se aplican comprobaciones de calidad de los datos
Nomenclatura fácil de usar: identificadores claros y descriptivos
Unidades coherentes: estandarizadas en todas las métricas
Listas para el análisis: no requieren ninguna transformación adicional
Orientadas al negocio: centradas en los KPI y las necesidades de informes

Las métricas de exportación se identifican mediante cadenas metric_id (p. ej., energy_grid_daily, availability_technical) y constituyen la base del sistema de exportación.

Consejos

Cuando utilizas la API de exportación de métricas, siempre trabajas con métricas de exportación. La recopilación de métricas en bruto se transforma automáticamente a estos formatos listos para exportación por parte de la plataforma.

Funcionalidades clave

Exportaciones basadas en plantillas: define configuraciones de métricas reutilizables
Soporte multiparque: exporta datos agregados de varios parques o portfolios en una sola solicitud
Múltiples formatos de exportación: CSV con separadores configurables para compatibilidad internacional, además de una variante JSON para gráficos dentro de la aplicación
Rangos de tiempo flexibles: exporta por año, trimestre, mes, semana o un solo día
Opciones de agregación: agregación diaria, semanal, mensual, trimestral o anual
Soporte internacional: formatos de fecha y separadores decimales personalizables
Métricas personalizadas: define tus propias métricas mediante fórmulas MiroxQL

Elegir la exportación adecuada

La plataforma ofrece tres rutas de exportación distintas. Elige la que se ajuste a tu objetivo:

Exportación	Endpoint	Salida	Ideal para
CSV de plantilla	`GET /v1/export/metrics/template/{template_uid}`	Descarga CSV	Informes, hojas de cálculo, facturación — columnas predefinidas, agregadas y compatibles con fórmulas para uno o varios parques
JSON de plantilla	`POST /v1/export/metrics/query`	JSON	Gráficos y vistas previas dentro de tu propia aplicación — mismo motor de agregación, devuelve filas de valores fechados
Series temporales en bruto	`POST /v1/export/raw/query`	JSON	Curvas de potencia de alta resolución con el paso que elijas (5m, 15m, 1h, 1d) — consultas en bruto arbitrarias, sin agregar

La ruta CSV de plantilla es la exportación de métricas canónica y el foco de esta guía. Para un acceso programático y basado en fórmulas a tus datos, consulta Lenguaje de consulta MiroxQL — la forma admitida de consultar y dar forma a las cifras en bruto para convertirlas en métricas personalizadas.

Multiparque en una sola llamada

Las exportaciones CSV y JSON de plantilla aceptan parámetros de consulta park y portfolio separados por comas, de modo que puedes extraer una agregación de todo un portfolio en una sola solicitud. Cuando se proporcionan ambos, los parques de cada portfolio se unen con los parques listados explícitamente.

Sistema de plantillas

¿Qué son las plantillas de exportación?

Las plantillas de exportación son configuraciones predefinidas o personalizadas que especifican:

Qué métricas incluir en la exportación
El orden de las métricas en la salida
Metadatos sobre cada métrica (nombre, unidad, categoría, descripción)

Las plantillas permiten exportaciones coherentes y repetibles, y pueden compartirse en toda una organización. Para crear, editar o compartir plantillas sin escribir código, abre Exportación de datos ▸ Plantillas en Mirox.

Plantilla de sistema predefinida

El sistema proporciona una plantilla predeterminada completa que incluye todas las métricas esenciales para la monitorización y la elaboración de informes de parques solares.

Plantilla Report Technical v1 (UID: ABCD12340001):

Esta plantilla completa se utiliza tanto para la generación de informes PDF como para las exportaciones CSV. Incluye:

Métricas de series temporales:

Producción de energía (kWh) - energy_grid_daily
Energía de radiación total (kWh) - energy_radiation_daily
Sensor GTI (kWh/m²) - gti_sensor_daily
GTI meteorológico (kWh/m²) - gti_weather_daily
Horas de sol (h) - sunhours_daily
Disponibilidad de inversor (%) - availability_inverter
Disponibilidad de energía (%) - availability_energy
Disponibilidad de datos (%) - availability_data
Disponibilidad de sensor (%) - availability_sensor
Energía de parada por red (kWh) - energy_shutdown_grid_daily
Energía de parada por control externo (kWh) - energy_shutdown_external_daily

Métricas de configuración de informe:

Energía de informe (kWh) - energy_report
GTI incidente de informe (kWh/m²) - gti_report
GTI efectivo de informe (kWh/m²) - gti_report_eff
PR objetivo de informe (%) - pr_report

Métricas calculadas (mediante MiroxQL):

Análisis de irradiancia (real, uso meteorológico, diferencia sensor-meteorología)
Objetivos de producción (basados en meteorología, basados en sensor, real, corregido)
Performance ratios (meteorología, sensor, real, corregido)
Rendimiento específico (Wh/W)
Análisis de pérdidas (pérdidas no compensables)

Datos coherentes entre informes y exportaciones

Esta plantilla se utiliza tanto para la generación de informes PDF como para las exportaciones de la API, lo que garantiza que los informes generados internamente y los datos exportados por el usuario contengan exactamente las mismas métricas y cálculos. Esta coherencia es una funcionalidad central de la plataforma, que permite una validación y comparación de datos fiables.

Para información sobre métricas calculadas personalizadas, consulta Lenguaje de consulta MiroxQL.

Métricas de exportación disponibles

Todas las métricas se calculan a diario y pueden agregarse a intervalos semanales, mensuales, trimestrales o anuales. Cada métrica incluye una fórmula simplificada que muestra cómo se deriva el valor a partir de las métricas en bruto.

Métricas de producción de energía

ID de métrica	Nombre	Unidad	Descripción	Fórmula
`energy_grid_daily`	Producción de energía	kWh	Energía diaria inyectada en la red	`sum(delta(grid_energy_total))` por componente
`energy_ac_daily`	Producción CA	kWh	Producción diaria de energía CA	`sum(delta(ac_energy_total))` por componente
`energy_inverter_daily`	Producción de inversor	kWh	Producción diaria de energía de los inversores	`sum(delta(inverter_ac_energy_total))` por inversor
`energy_radiation_daily`	Energía de radiación total	kWh	Energía de radiación total diaria	`sum(delta(radiation_energy_total))` por componente

Métricas de parada/pérdida

ID de métrica	Nombre	Unidad	Descripción	Fórmula
`energy_shutdown_grid_daily`	Energía de parada por red	kWh	Pérdida de energía diaria por restricciones de la red	`sum(delta(energy_loss_total))` donde type='grid', por componente
`energy_shutdown_external_daily`	Energía de parada por control externo	kWh	Pérdida de energía diaria por control externo	`sum(delta(energy_loss_total))` donde type='external', por componente

Métricas de irradiancia

Las métricas de irradiancia global inclinada (GTI) son comparables y miden la radiación solar sobre el plano inclinado de los módulos solares.

ID de métrica	Nombre	Unidad	Descripción	Fórmula
`gti_sensor_daily`	Sensor GTI	kWh/m²	Irradiación global inclinada diaria a partir de sensores	`avg(delta(irradiation_total))` donde position='module-level' o alternativa
`gti_weather_daily`	GTI meteorológico	kWh/m²	Irradiación global inclinada diaria a partir de la previsión meteorológica	`sum(weather_gti) / 4`, muestreo: intervalos de 15 min
`gti_report`	GTI de informe	kWh/m²	Objetivo de GTI a partir de la configuración del parque	valor de la configuración del parque

Métricas meteorológicas

ID de métrica	Nombre	Unidad	Descripción	Fórmula
`solar_radiation_daily`	Radiación solar	Wh	Radiación solar diaria media	`avg(solar_radiation)` durante 24 h
`sunhours_daily`	Horas de sol	h	Horas de sol diarias	`count(weather_gti > 0) / 4`, muestreo: 15 min

Métricas ambientales

ID de métrica	Nombre	Unidad	Descripción	Fórmula
`temperature_ambient_avg`	Temperatura ambiente	°C	Temperatura ambiente media diaria	`avg(ambient_temperature)` durante 24 h
`temperature_module_avg`	Temperatura de módulo	°C	Temperatura de módulo media diaria	`avg(module_temperature)` durante 24 h
`wind_speed_avg`	Velocidad del viento	m/s	Velocidad del viento media diaria	`avg(wind_speed)` durante 24 h
`humidity_avg`	Humedad	%	Humedad media diaria	`avg(humidity)` durante 24 h

Métricas de disponibilidad

ID de métrica	Nombre	Unidad	Descripción	Fórmula
`availability_inverter`	Disponibilidad de inversor	%	Disponibilidad del inversor basada en la potencia de salida y las condiciones de GTI	`avg(1 - count(inverter_power ≤ 0 AND weather_gti > 100))`, muestreo: 15 min
`availability_technical`	Disponibilidad técnica	%	Disponibilidad técnica del sistema	`avg(sum(scraper_health == 1) / count(scraper_health))` por fuente, muestreo: 15 min
`availability_data`	Disponibilidad de datos	%	Disponibilidad de datos de la planta	`1 - avg(count(grid_energy_total))` donde está ausente, muestreo: 15 min
`availability_sensor`	Disponibilidad de sensor	%	Disponibilidad del sensor	`1 - avg(count(solar_radiation))` donde está ausente, muestreo: 15 min
`availability_energy`	Disponibilidad de energía	%	Aproximación de disponibilidad basada en energía	`1 - (sum(energy_loss_total) / (sum(grid_energy_total) + sum(energy_loss_total)))`

La disponibilidad técnica cambia con el tiempo

El alcance de la métrica availability_technical se amplía a medida que se añaden nuevas funcionalidades a la plataforma. Esto puede hacer que el valor disminuya cuando se implementan nuevas funcionalidades, incluso si los sistemas existentes funcionan con normalidad. Para comparaciones históricas estables, utiliza métricas específicas como availability_inverter, availability_data o availability_sensor.

Métricas de batería

Las agregaciones de batería operan a nivel de box de la jerarquía BESS — la vista canónica de "todo el BESS" definida por el enum BATTERY. Consulta la página Recopilación de métricas para ver la jerarquía completa de componentes (entorno / box / almacenamiento / módulo / celda).

ID de métrica	Nombre	Unidad	Descripción	Fórmula
`battery_energy_in_daily`	Energía de batería cargada	kWh	Energía CC diaria cargada en la batería	`sum(delta(battery_box_energy_dc_in_total))` por box
`battery_energy_out_daily`	Energía de batería descargada	kWh	Energía CC diaria descargada de la batería	`sum(delta(battery_box_energy_dc_out_total))` por box
`battery_soc_avg`	Estado de carga de la batería	%	Estado de carga medio diario a nivel de box	`avg(battery_box_soc)` durante 24 h
`battery_soh_avg`	Estado de salud de la batería	%	Estado de salud medio diario a nivel de box	`avg(battery_box_soh)` durante 24 h
`battery_energy_charged_avg`	Energía almacenada en la batería	kWh	Energía media diaria almacenada actualmente	`avg(sum(battery_box_energy_charged))` durante 24 h
`temperature_battery_avg`	Temperatura de la batería	°C	Temperatura media diaria de la batería a nivel de box	`avg(battery_box_temperature)` durante 24 h

Métricas de informe

ID de métrica	Nombre	Unidad	Descripción	Fórmula
`energy_report`	Energía de informe	kWh	Objetivo de energía a partir de la configuración del parque	`valor de la configuración del parque`

Rango de tiempo y agregación

Selección del rango de tiempo

Elige qué porción del historial exportar con estos selectores:

Año: un año natural completo
Trimestre: un trimestre de un año determinado
Mes: un único mes natural
Semana: una única semana natural
Día: un único día (requiere que se haya definido un mes)

Resolución de agregación

Dentro del rango seleccionado, los valores diarios se agrupan a la resolución que elijas. Las métricas basadas en energía y horas se suman; todas las demás métricas se promedian.

Agregación diaria

Valores diarios en bruto del almacén de series temporales de la plataforma
Máxima granularidad disponible
Ideal para análisis detallados y resolución de problemas
Tamaño de archivo: grande

Agregación semanal

Datos agregados por semana ISO (de lunes a domingo)
Incluye columnas de número de semana y semana natural
Una opción full_week extiende las semanas inicial y final parciales a semanas ISO completas
Adecuada para análisis de tendencias
Tamaño de archivo: medio

Agregación mensual

Datos agregados por mes natural
Incluye una columna "Días del mes" para la normalización
Ideal para informes y tendencias a largo plazo
Tamaño de archivo: pequeño

Agregación trimestral y anual

Datos agrupados por trimestres naturales o años completos
Ideal para resúmenes ejecutivos y comparación interanual
Tamaño de archivo: el más pequeño

Soporte de formatos internacionales

Separadores CSV

La API admite varios separadores CSV para compatibilidad regional:

Coma (,): estándar en EE. UU./Reino Unido
Punto y coma (;): estándar en Alemania y muchos países europeos
Tabulador (\t): universal, adecuado para la importación en Excel
Barra vertical (|): alternativa para casos especiales

Separadores decimales

Punto (.): estándar en EE. UU./Reino Unido (p. ej., 1234.56)
Coma (,): estándar en Alemania y muchos países europeos (p. ej., 1234,56)

Advertencia

El separador CSV y el separador decimal deben ser diferentes para evitar problemas de análisis.

Formatos de fecha

Se pueden especificar formatos de fecha y hora personalizados mediante la sintaxis strftime de Python:

Formatos comunes:

%Y-%m-%d: formato ISO (2025-03-15)
%d/%m/%Y: formato europeo (15/03/2025)
%m/%d/%Y: formato estadounidense (03/15/2025)
%d.%m.%Y: formato alemán (15.03.2025)
%Y-%m: solo el mes (2025-03)
%Y-W%W: formato de semana ISO (2025-W11)

Formato de salida CSV

Los archivos CSV exportados incluyen encabezados con los nombres y las unidades de las métricas. La estructura varía según el intervalo de agregación:

Exportación mensual

Incluye una columna "Días del mes" para la normalización.

Exportación semanal

Incluye columnas tanto de "Fecha" (formato de semana ISO) como de "Semana natural" (número de semana).

Exportación diaria

Una fila por día con la fecha en el formato especificado.

Casos de uso

Informes personalizados

Crea plantillas de exportación especializadas para:

Informes de rendimiento mensuales
Actualizaciones trimestrales para partes interesadas
Informes de cumplimiento anuales
Seguimiento de KPI personalizados

Integración de terceros

Exporta datos para integrarlos con:

Sistemas de gestión energética
Plataformas de inteligencia de negocio
Software de contabilidad de carbono
Herramientas de gestión de portfolios

Análisis de datos

Alimenta tus propios análisis con las cifras exportadas:

Evaluación comparativa de rendimiento
Análisis de tendencias estacionales
Alimentación de pipelines de inteligencia de negocio e informes

Autenticación y permisos

Todos los endpoints de exportación requieren una sesión autenticada. Puedes utilizarlos desde una sesión de navegador o con un token de API que tenga el grupo de permisos reporting.

Lo que necesitas:

Gestión de plantillas: derechos para leer, crear, modificar o eliminar plantillas de exportación dentro de tu organización. Las plantillas de sistema son de solo lectura para todos.
Exportación de métricas: acceso de lectura para exportar informes.
Acceso a parques: solo recibes datos de los parques y portfolios que tienes permiso para ver. Los parques solicitados a los que no puedes acceder se filtran de forma silenciosa — y si no queda ninguno accesible, la solicitud se rechaza.

Buenas prácticas

Elige plantillas adecuadas: utiliza plantillas predefinidas siempre que sea posible y crea plantillas personalizadas para necesidades específicas
Selecciona la agregación correcta: usa la mensual para informes y la diaria para análisis detallados
Configura los separadores adecuados: ajústalos a tu configuración local de Excel/CSV
Exportaciones multiparque: aprovecha las capacidades multiparque para el análisis a nivel de portfolio
Reutilización de plantillas: crea plantillas para toda la organización con el fin de obtener informes coherentes
Usa MiroxQL: define métricas calculadas personalizadas para análisis avanzados

Ejemplo práctico

Para un ejemplo de implementación completo de generación de informes personalizados mediante la API de exportación de métricas, consulta el Ejemplo de generador de informes. Este ejemplo demuestra cómo obtener datos de la API, procesarlos y generar informes personalizados con visualizaciones.

Gestión de errores

Respuestas de error comunes:

404 Not Found: la plantilla, el parque o el portfolio no existe
403 Forbidden: permisos insuficientes o ningún parque accesible
422 Validation Error: parámetros no válidos (p. ej., IDs de métrica no válidos)
400 Bad Request: combinaciones de parámetros no válidas (p. ej., mismo separador CSV y decimal)
409 Conflict: el nombre de la plantilla ya existe en la organización

Funcionalidades relacionadas

Lenguaje de consulta MiroxQL — define métricas calculadas personalizadas para tus plantillas
Generación de informes externos — automatiza las exportaciones CSV de plantilla en tu propio flujo de trabajo de informes
Ejemplo de generador de informes — un ejemplo de Python ejecutable de principio a fin
Informes — generación automatizada de informes PDF utilizando las mismas plantillas
Guía de tokens de API — configura un token de API para autenticar las exportaciones