API de exportação legada

Esta página descreve as ligações de exportação que existiam antes da exportação de métricas. São legadas: são servidas sem alterações, com os mesmos parâmetros, IDs de métricas e colunas, e já não são ampliadas.

Rotas

Todos os caminhos são relativos a https://service.mirox.io/api. Um token de API do grupo Metric Export lê todas elas.

O que está obsoleto

Uma rota obsoleta continua a responder, mas pode ser removida numa versão posterior, e a referência interativa da API marca-a como obsoleta.

• A rota de modelo para uma só central em /v1/export/report/{park_uid}/data/template/…. Use antes a exportação por modelo; aceita os mesmos modelos.
• As três rotas POST que respondiam às exportações em JSON. A API de exportação de métricas responde em JSON com format=json.
• GET /v1/export/template/metrics, a lista de IDs de métricas legadas para o editor de modelos. O catálogo de métricas substitui-a.

Tudo o resto nesta página é legado, mas não obsoleto.

Várias centrais: combinar ou separar

As quatro exportações aceitam os parâmetros park e portfolio separados por vírgulas. Quando ambos são indicados, as centrais de cada carteira são acrescentadas às centrais listadas.

multi_park_agg decide como várias centrais são representadas. Está disponível na exportação por modelo, por ID de métrica e bruta; a exportação de componentes tem, em vez dele, multi_component_agg.

Com uma única central, os dois são idênticos e o parâmetro é ignorado.

Exportação por modelo

GET /v1/export/metrics/template/{template_uid}

curl "https://service.mirox.io/api/v1/export/metrics/template/ABCD12340001?park=ABC123DEF456&resolution=monthly" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Modelos do sistema legados

Na aplicação, estes cinco são substituídos pelos seus sucessores no separador Modelos. As suas ligações continuam a responder como antes.

Report Technical v1 (ABCD12340001) contém:

Métricas de séries temporais:

1. Energy Production (kWh) - energy_grid_daily
2. Energy Radiation Total (kWh) - energy_radiation_daily
3. GTI Sensor (kWh/m²) - gti_sensor_daily
4. GTI Weather (kWh/m²) - gti_weather_daily
5. Sunhours (h) - sunhours_daily
6. Availability Inverter (%) - availability_inverter
7. Availability Energy (%) - availability_energy
8. Availability Data (%) - availability_data
9. Availability Sensor (%) - availability_sensor
10. Energy Shutdown by Grid (kWh) - energy_shutdown_grid_daily
11. Energy Shutdown by External (kWh) - energy_shutdown_external_daily

Métricas de configuração do 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 (com MiroxQL):

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

Modelos da exportação de métricas nesta rota

A exportação por modelo também aceita o ID de um modelo da exportação de métricas, por exemplo CAFE1000CAFE. Responde então com a exportação de métricas desse modelo: os parâmetros de calendário selecionam o período, resolution seleciona o passo, e o ficheiro segue as convenções da exportação de métricas. Não tem coluna «Days in Month» nem «Calendar Week», e os erros são respondidos com um code. Sem resolution, aplica-se o passo do modelo.

A rota obsoleta para uma só central não aceita um modelo destes e responde 400 com a ligação a usar.

Saída CSV

Os ficheiros têm uma linha de cabeçalho com os nomes das métricas e as unidades. A estrutura segue a resolução:

• Diária — uma linha por dia.
• Semanal — uma coluna «Date» em formato de semana ISO e uma coluna «Calendar Week» com o número da semana.
• Mensal — uma coluna «Days in Month» para normalização.

Os valores são agregados por dia e depois consolidados: a energia e as horas são somadas, de tudo o resto é feita a média. Um dia é um dia UTC. Um valor em falta é escrito como 0.

Exportação por ID de métrica

GET /v1/export/metrics/query exporta um conjunto de IDs de métricas legadas sem modelo, com os parâmetros de período e o formato CSV da exportação por modelo.

Exportação de séries temporais brutas

GET /v1/export/raw/query devolve séries temporais brutas ao nível da central. GET /v1/metrics/raw lista cada ID bruto com o seu nome, unidade, categoria e o operador que aplica entre séries (sum, avg, min ou max).

curl --compressed "https://service.mirox.io/api/v1/export/raw/query?metrics=raw_grid_energy_total&park=ABC123DEF456&start=2026-07-01T00:00:00Z&end=2026-07-08T00:00:00Z&step=15m&value=use_delta" \
  -H "Authorization: Bearer YOUR_API_TOKEN" -o production_week.csv

Date;Grid Production (Wh)
2026-07-01 00:00;0,00
2026-07-01 06:15;1250,50
...

A energia está em Wh, e a hora em UTC.

Exportação bruta de componentes

GET /v1/export/raw/component/query exporta as séries temporais brutas de componentes individuais — inversores, caixas de junção ou strings individuais — de exatamente uma central. Os IDs de métricas de componentes têm o prefixo comp_raw_ e estão listados, por tipo de componente, em GET /v1/metrics/components.

Limites

Ambas as exportações brutas recusam com 400 tudo o que for maior:

As respostas acima de cerca de 1 MB são comprimidas quando o pedido contém Accept-Encoding: gzip.

IDs de métricas legadas

As métricas diárias da exportação por modelo e por ID de métrica. Cada uma pode ser agregada em valores semanais, mensais, trimestrais ou anuais. A coluna da fórmula mostra, de forma simplificada, como um valor é derivado. A métrica que responde por cada ID na exportação de métricas está na correspondência de IDs.

Métricas de produção de energia

Métricas de corte e perda

Métricas de irradiância

Métricas meteorológicas

Métricas ambientais

Métricas de disponibilidade

Métricas de bateria

Métricas de relatório

Os IDs brutos e de componentes são listados por GET /v1/metrics/raw e GET /v1/metrics/components, e na correspondência de IDs.

Comportamento conhecido que se mantém

Os números das exportações legadas mantêm-se como estão, para que um livro mostre amanhã o que mostrou ontem. Isto inclui três leituras que a exportação de métricas faz de forma diferente:

Correções

Dois grupos de colunas da exportação de séries temporais brutas estavam vazios e passam a conter valores. Um livro que os leia mostra números onde antes mostrava células vazias.

Informações da central

GET /v1/export/report/{park_uid}/info

Responde com os dados base de uma central em JSON: nome, tipo e descrição, localização e fuso horário, potência de pico, organização e carteira, morada e datas de entrada em serviço. Há um exemplo no Gerador de relatórios externo.

Eventos

GET /v1/export/report/{park_uid}/events.csv

As colunas são Event ID, Start Date, End Date, Duration (hours), Type, Creator, Description e Priority. A data de fim de um evento ainda aberto é Ongoing. Uma prioridade de 1000 ou mais assinala um evento importante.

Funcionalidades relacionadas

• API de exportação de métricas — a exportação atual
• Migrar para a exportação de métricas — o que muda, e a correspondência de IDs
• Fórmulas MiroxQL — a API de fórmulas por detrás das colunas calculadas
• Gerador de relatórios externo — informações da central e eventos num exemplo em Python
• Tokens de API — o token Metric Export