API de Exportação de Métricas

Extraia dados de séries temporais processados e prontos para relatório das suas centrais numa única chamada — num parque, em vários parques ou em carteiras inteiras. O sistema de exportação está construído em torno de modelos que definem que métricas exportar e por que ordem, pelo que os mesmos números que vê num relatório gerado são os números que extrai através da API.

O download canónico de CSV é GET /v1/export/metrics/template/{template_uid}. Uma variante JSON e uma exportação separada de séries temporais em bruto cobrem os gráficos na aplicação e as curvas de potência de alta resolução; todos os três são descritos abaixo.

Abrir na Mirox

Crie e execute uma exportação de forma interativa em Exportação de Dados ▸ Builder, ou faça a gestão dos seus modelos em Exportação de Dados ▸ Modelos. Os mesmos modelos e métricas aqui descritos alimentam tanto o builder na aplicação como a API.

Compreender os Tipos de Métricas

A plataforma Mirox trabalha com dois tipos distintos de métricas que servem propósitos diferentes:

Recolha de Métricas em Bruto

As métricas em bruto são a base da infraestrutura de dados da plataforma. Estas métricas são:

Recolhidas diretamente do hardware: extraídas de inversores, sensores e data loggers
Armazenadas tal como estão na base de dados de séries temporais: preserva a granularidade e a estrutura originais
Otimizadas para monitorização em tempo real: permite dashboards ao vivo e consultas instantâneas
Multidimensionais: usa labels para dividir os dados por componente, localização ou tipo
Contadores cumulativos: frequentemente armazena valores totais de energia que aumentam ao longo do tempo
Alta frequência: podem ser recolhidas a cada poucos segundos ou minutos

As métricas em bruto são essenciais para o funcionamento do sistema, mas não estão otimizadas para uma exportação de dados amigável. Necessitam de transformação, agregação e interpretação para se tornarem métricas de negócio significativas.

Para informação detalhada sobre a recolha de métricas em bruto, consulte Arquitetura de Recolha de Métricas.

Métricas de Exportação

As métricas de exportação são métricas processadas e amigáveis, concebidas especificamente para a exportação de dados e a elaboração de relatórios:

Pré-agregadas: calculadas numa base diária por predefinição
Limpas e validadas: aplicados controlos de qualidade dos dados
Nomenclatura amigável: identificadores claros e descritivos
Unidades consistentes: normalizadas em todas as métricas
Prontas para análise: não requerem transformação adicional
Orientadas para o negócio: focadas em KPIs e necessidades de relatório

As métricas de exportação são identificadas por strings metric_id (p. ex. energy_grid_daily, availability_technical) e formam a base do sistema de exportação.

Dica

Ao utilizar a API de Exportação de Métricas, está sempre a trabalhar com métricas de exportação. A recolha de métricas em bruto é automaticamente transformada nestes formatos prontos para exportação pela plataforma.

Funcionalidades Principais

Exportações Baseadas em Modelos: defina configurações de métricas reutilizáveis
Suporte Multi-Parque: exporte dados agregados de vários parques ou carteiras num único pedido
Múltiplos Formatos de Exportação: CSV com separadores configuráveis para compatibilidade internacional, mais uma variante JSON para gráficos na aplicação
Intervalos de Tempo Flexíveis: exporte por ano, trimestre, mês, semana ou um único dia
Opções de Agregação: agregação diária, semanal, mensal, trimestral ou anual
Suporte Internacional: formatos de data e separadores decimais personalizáveis
Métricas Personalizadas: defina as suas próprias métricas usando fórmulas MiroxQL

Escolher a Exportação Certa

A plataforma oferece três caminhos de exportação distintos. Escolha aquele que corresponde ao seu objetivo:

Exportação	Endpoint	Saída	Melhor Para
Modelo CSV	`GET /v1/export/metrics/template/{template_uid}`	Download CSV	Relatórios, folhas de cálculo, faturação — colunas pré-definidas, agregadas e com fórmulas em um ou vários parques
Modelo JSON	`POST /v1/export/metrics/query`	JSON	Gráficos e pré-visualizações dentro da sua própria aplicação — o mesmo motor de agregação, devolve linhas de valores datados
Séries Temporais em Bruto	`POST /v1/export/raw/query`	JSON	Curvas de potência de alta resolução no passo que escolher (5m, 15m, 1h, 1d) — consultas em bruto arbitrárias, não agregadas

A rota Modelo CSV é a exportação de métricas canónica e o foco deste guia. Para acesso programático e orientado por fórmulas aos seus dados, consulte Linguagem de Consulta MiroxQL — a forma suportada de consultar e moldar valores em bruto em métricas personalizadas.

Multi-Parque numa Única Chamada

As exportações Modelo CSV e JSON aceitam parâmetros de consulta park e portfolio separados por vírgulas, pelo que pode obter uma agregação ao nível da carteira num único pedido. Quando ambos são fornecidos, os parques de cada carteira são unidos com os parques explicitamente listados.

Sistema de Modelos

O que são Modelos de Exportação?

Os modelos de exportação são configurações predefinidas ou personalizadas que especificam:

Que métricas incluir na exportação
A ordem das métricas na saída
Metadados sobre cada métrica (nome, unidade, categoria, descrição)

Os modelos permitem exportações consistentes e repetíveis e podem ser partilhados numa organização. Para criar, editar ou partilhar modelos sem escrever código, abra Exportação de Dados ▸ Modelos na Mirox.

Modelo de Sistema Predefinido

O sistema disponibiliza um modelo predefinido abrangente que inclui todas as métricas essenciais para a monitorização e a elaboração de relatórios de parques solares.

Modelo Report Technical v1 (UID: ABCD12340001):

Este modelo abrangente é utilizado tanto para a geração de relatórios PDF como para exportações CSV. Inclui:

Métricas de Séries Temporais:

Energy Production (kWh) - energy_grid_daily
Energy Radiation Total (kWh) - energy_radiation_daily
GTI Sensor (kWh/m²) - gti_sensor_daily
GTI Weather (kWh/m²) - gti_weather_daily
Sunhours (h) - sunhours_daily
Availability Inverter (%) - availability_inverter
Availability Energy (%) - availability_energy
Availability Data (%) - availability_data
Availability Sensor (%) - availability_sensor
Energy Shutdown by Grid (kWh) - energy_shutdown_grid_daily
Energy Shutdown by External (kWh) - energy_shutdown_external_daily

Métricas de Configuração de Relatório:

Energy Report (kWh) - energy_report
GTI Report Incident (kWh/m²) - gti_report
GTI Report Effective (kWh/m²) - gti_report_eff
PR Report Target (%) - pr_report

Métricas Calculadas (usando MiroxQL):

Análise de irradiância (real, utilização meteorológica, diferença sensor-meteorologia)
Metas de produção (baseada em meteorologia, baseada em sensor, real, corrigida)
Performance ratios (meteorologia, sensor, real, corrigida)
Rendimento específico (Wh/W)
Análise de perdas (perdas não compensáveis)

Dados Consistentes em Relatórios e Exportações

Este modelo é utilizado tanto para a Geração de Relatórios PDF como para as exportações da API, garantindo que os relatórios gerados internamente e os dados exportados pelo utilizador contêm exatamente as mesmas métricas e cálculos. Esta consistência é uma funcionalidade central da plataforma, permitindo a validação e a comparação fiáveis de dados.

Para informação sobre métricas calculadas personalizadas, consulte Linguagem de Consulta MiroxQL.

Métricas de Exportação Disponíveis

Todas as métricas são calculadas numa base diária e podem ser agregadas em intervalos semanais, mensais, trimestrais ou anuais. Cada métrica inclui uma fórmula simplificada que mostra como o valor é derivado das métricas em bruto.

Métricas de Produção de Energia

Metric ID	Nome	Unidade	Descrição	Fórmula
`energy_grid_daily`	Energy Production	kWh	Energia diária injetada na rede	`sum(delta(grid_energy_total))` por componente
`energy_ac_daily`	AC Production	kWh	Produção diária de energia AC	`sum(delta(ac_energy_total))` por componente
`energy_inverter_daily`	Inverter Production	kWh	Produção diária de energia dos inversores	`sum(delta(inverter_ac_energy_total))` por inversor
`energy_radiation_daily`	Energy Radiation Total	kWh	Radiação de energia total diária	`sum(delta(radiation_energy_total))` por componente

Métricas de Corte/Perda

Metric ID	Nome	Unidade	Descrição	Fórmula
`energy_shutdown_grid_daily`	Energy Shutdown by Grid	kWh	Perda diária de energia devido a restrições da rede	`sum(delta(energy_loss_total))` onde type='grid', por componente
`energy_shutdown_external_daily`	Energy Shutdown by External	kWh	Perda diária de energia devido a controlo externo	`sum(delta(energy_loss_total))` onde type='external', por componente

Métricas de Irradiância

As métricas de Global Tilted Irradiance (GTI) são comparáveis e medem a radiação solar no plano inclinado dos módulos solares.

Metric ID	Nome	Unidade	Descrição	Fórmula
`gti_sensor_daily`	GTI Sensor	kWh/m²	Irradiação inclinada global diária a partir de sensores	`avg(delta(irradiation_total))` onde position='module-level' ou fallback
`gti_weather_daily`	GTI Weather	kWh/m²	Irradiação inclinada global diária a partir da previsão meteorológica	`sum(weather_gti) / 4`, amostragem: intervalos de 15min
`gti_report`	GTI Report	kWh/m²	Meta de GTI a partir da configuração do parque	valor da configuração do parque

Métricas Meteorológicas

Metric ID	Nome	Unidade	Descrição	Fórmula
`solar_radiation_daily`	Solar Radiation	Wh	Radiação solar diária média	`avg(solar_radiation)` ao longo de 24h
`sunhours_daily`	Sunhours	h	Horas diárias de sol	`count(weather_gti > 0) / 4`, amostragem: 15min

Métricas Ambientais

Metric ID	Nome	Unidade	Descrição	Fórmula
`temperature_ambient_avg`	Ambient Temperature	°C	Temperatura ambiente diária média	`avg(ambient_temperature)` ao longo de 24h
`temperature_module_avg`	Module Temperature	°C	Temperatura diária média dos módulos	`avg(module_temperature)` ao longo de 24h
`wind_speed_avg`	Wind Speed	m/s	Velocidade do vento diária média	`avg(wind_speed)` ao longo de 24h
`humidity_avg`	Humidity	%	Humidade diária média	`avg(humidity)` ao longo de 24h

Métricas de Disponibilidade

Metric ID	Nome	Unidade	Descrição	Fórmula
`availability_inverter`	Availability Inverter	%	Disponibilidade do inversor com base na potência de saída e nas condições de GTI	`avg(1 - count(inverter_power ≤ 0 AND weather_gti > 100))`, amostragem: 15min
`availability_technical`	Availability Technical	%	Disponibilidade técnica do sistema	`avg(sum(scraper_health == 1) / count(scraper_health))` por fonte, amostragem: 15min
`availability_data`	Availability Data	%	Disponibilidade de dados a partir da central	`1 - avg(count(grid_energy_total))` onde ausente, amostragem: 15min
`availability_sensor`	Availability Sensor	%	Disponibilidade do sensor	`1 - avg(count(solar_radiation))` onde ausente, amostragem: 15min
`availability_energy`	Availability Energy	%	Aproximação de disponibilidade baseada em energia	`1 - (sum(energy_loss_total) / (sum(grid_energy_total) + sum(energy_loss_total)))`

A Disponibilidade Técnica Muda ao Longo do Tempo

O âmbito da métrica availability_technical expande-se à medida que são adicionadas novas funcionalidades da plataforma. Isto pode fazer com que o valor diminua quando novas funcionalidades são implementadas, mesmo que os sistemas existentes funcionem normalmente. Para comparações históricas estáveis, utilize métricas específicas como availability_inverter, availability_data ou availability_sensor.

Métricas de Bateria

As agregações de bateria operam ao nível da caixa (box) da hierarquia BESS — a vista canónica de "BESS completo" definida pelo enum BATTERY. Consulte a página Recolha de Métricas para a hierarquia completa de componentes (ambiente / caixa / armazenamento / módulo / célula).

Metric ID	Nome	Unidade	Descrição	Fórmula
`battery_energy_in_daily`	Battery Energy Charged	kWh	Energia DC diária carregada na bateria	`sum(delta(battery_box_energy_dc_in_total))` por caixa
`battery_energy_out_daily`	Battery Energy Discharged	kWh	Energia DC diária descarregada da bateria	`sum(delta(battery_box_energy_dc_out_total))` por caixa
`battery_soc_avg`	Battery State of Charge	%	Estado de carga médio diário ao nível da caixa	`avg(battery_box_soc)` ao longo de 24h
`battery_soh_avg`	Battery State of Health	%	Estado de saúde médio diário ao nível da caixa	`avg(battery_box_soh)` ao longo de 24h
`battery_energy_charged_avg`	Battery Stored Energy	kWh	Energia média diária atualmente armazenada	`avg(sum(battery_box_energy_charged))` ao longo de 24h
`temperature_battery_avg`	Battery Temperature	°C	Temperatura média diária da bateria ao nível da caixa	`avg(battery_box_temperature)` ao longo de 24h

Métricas de Relatório

Metric ID	Nome	Unidade	Descrição	Fórmula
`energy_report`	Energy Report	kWh	Meta de energia a partir da configuração do parque	`value from park configuration`

Intervalo de Tempo e Agregação

Selecionar o Intervalo de Tempo

Escolha que fatia do histórico exportar com estes seletores:

Ano: um ano civil completo
Trimestre: um trimestre de um determinado ano
Mês: um único mês civil
Semana: uma única semana civil
Dia: um único dia (requer que esteja definido um mês)

Resolução da Agregação

Dentro do intervalo selecionado, os valores diários são consolidados na resolução que escolher. As métricas baseadas em energia e em horas são somadas; todas as restantes são calculadas pela média.

Agregação Diária

Valores diários em bruto do armazenamento de séries temporais da plataforma
A maior granularidade disponível
Melhor para análise detalhada e resolução de problemas
Tamanho do ficheiro: Grande

Agregação Semanal

Dados agregados por semana ISO (de segunda a domingo)
Inclui colunas de número da semana e semana civil
Uma opção full_week estende as primeiras e últimas semanas parciais para semanas ISO completas
Adequada para análise de tendências
Tamanho do ficheiro: Médio

Agregação Mensal

Dados agregados por mês civil
Inclui a coluna "Days in Month" para normalização
Melhor para relatórios e tendências de longo prazo
Tamanho do ficheiro: Pequeno

Agregação Trimestral e Anual

Dados consolidados em trimestres civis ou anos completos
Melhor para resumos executivos e comparação ano a ano
Tamanho do ficheiro: Mínimo

Suporte de Formatos Internacionais

Separadores CSV

A API suporta múltiplos separadores CSV para compatibilidade regional:

Vírgula (,): padrão nos EUA/Reino Unido
Ponto e vírgula (;): padrão na Alemanha e em muitos países europeus
Tabulação (\t): universal, bom para importação no Excel
Barra vertical (|): alternativa para casos especiais

Separadores Decimais

Ponto (.): padrão nos EUA/Reino Unido (p. ex. 1234.56)
Vírgula (,): padrão na Alemanha e em muitos países europeus (p. ex. 1234,56)

Cuidado

O separador CSV e o separador decimal têm de ser diferentes para evitar problemas de análise (parsing).

Formatos de Data

Podem ser especificados formatos de data e hora personalizados usando a sintaxe strftime do Python:

Formatos comuns:

%Y-%m-%d: formato ISO (2025-03-15)
%d/%m/%Y: formato europeu (15/03/2025)
%m/%d/%Y: formato dos EUA (03/15/2025)
%d.%m.%Y: formato alemão (15.03.2025)
%Y-%m: apenas o mês (2025-03)
%Y-W%W: formato de semana ISO (2025-W11)

Formato de Saída CSV

Os ficheiros CSV exportados incluem cabeçalhos com nomes e unidades das métricas. A estrutura varia consoante o intervalo de agregação:

Exportação Mensal

Inclui uma coluna "Days in Month" para normalização.

Exportação Semanal

Inclui as colunas "Date" (formato de semana ISO) e "Calendar Week" (número da semana).

Exportação Diária

Uma linha por dia, com a data no formato especificado.

Casos de Utilização

Relatórios Personalizados

Crie modelos de exportação especializados para:

Relatórios de desempenho mensais
Atualizações trimestrais para stakeholders
Relatórios de conformidade anuais
Acompanhamento de KPIs personalizados

Integração com Terceiros

Exporte dados para integração com:

Sistemas de gestão de energia
Plataformas de business intelligence
Software de contabilidade de carbono
Ferramentas de gestão de carteiras

Análise de Dados

Alimente os valores exportados na sua própria análise:

Benchmarking de desempenho
Análise de tendências sazonais
Alimentação de pipelines de business intelligence e relatórios

Autenticação e Permissões

Todos os endpoints de exportação requerem uma sessão autenticada. Pode acioná-los a partir de uma sessão de navegador ou com um token de API que possua o grupo de permissões reporting.

O que necessita:

Gestão de Modelos: direitos para ler, criar, modificar ou eliminar modelos de exportação na sua organização. Os modelos de sistema são só de leitura para todos.
Exportação de Métricas: acesso de leitura para exportar relatórios.
Acesso aos Parques: só recebe dados dos parques e carteiras que tem permissão para ver. Os parques solicitados a que não pode aceder são silenciosamente filtrados — e, se nenhum permanecer acessível, o pedido é rejeitado.

Boas Práticas

Escolha Modelos Adequados: utilize modelos predefinidos sempre que possível e crie modelos personalizados para necessidades específicas
Selecione a Agregação Correta: utilize a mensal para relatórios e a diária para análise detalhada
Defina os Separadores Corretos: faça corresponder às definições locais do seu Excel/CSV
Exportações Multi-Parque: tire partido das capacidades multi-parque para análise ao nível da carteira
Reutilização de Modelos: crie modelos para toda a organização para relatórios consistentes
Utilize MiroxQL: defina métricas calculadas personalizadas para análise avançada

Exemplo Prático

Para um exemplo completo de implementação de geração de relatórios personalizados usando a API de Exportação de Métricas, consulte o Exemplo de Gerador de Relatórios. Este exemplo demonstra como obter dados da API, processá-los e gerar relatórios personalizados com visualizações.

Tratamento de Erros

Respostas de erro comuns:

404 Not Found: o modelo, parque ou carteira não existe
403 Forbidden: permissões insuficientes ou nenhum parque acessível
422 Validation Error: parâmetros inválidos (p. ex. metric IDs inválidos)
400 Bad Request: combinações de parâmetros inválidas (p. ex. o mesmo separador CSV e decimal)
409 Conflict: o nome do modelo já existe na organização

Funcionalidades Relacionadas

Linguagem de Consulta MiroxQL — defina métricas calculadas personalizadas para os seus modelos
Geração Externa de Relatórios — automatize as exportações de modelos CSV no seu próprio fluxo de relatórios
Exemplo de Gerador de Relatórios — um exemplo Python executável de ponta a ponta
Relatórios — geração automatizada de relatórios PDF usando os mesmos modelos
Guia de Tokens de API — configure um token de API para autenticar as exportações