ITENDE
Accedi al portale

Cosa puoi leggere

I dati sono organizzati per impianto. Questa pagina spiega i concetti, elenca gli endpoint e mostra due risposte tipiche: la potenza istantanea e i totali di energia.

Concetti

  • Impianto. L'unità di ogni richiesta. Ogni impianto ha un plant_id stabile (UUID), un nome, un paese e un fuso orario IANA.
  • Gateway. Il dispositivo in campo che invia i dati dell'impianto, identificato dal seriale stampato sull'unità (per esempio 2527-35520819PH). Un impianto ha uno o più gateway. I seriali compaiono nella connettività, nello stato di carica delle batterie e negli allarmi; per il resto i dati sono riferiti all'impianto.
  • Batterie. Lo stato di carica è riportato per gateway, come lista batteries: [{serial, soc_pct}]. Non viene mai mediato tra gateway: con batterie di capacità diversa una media sarebbe fuorviante.
  • Impianti con più gateway. La potenza fotovoltaica e quella di batteria sono la somma sui gateway. La potenza di rete e quella dei carichi sono quelle del punto di connessione alla rete, condiviso.
  • Periodi. I dati storici si chiedono con un period fisso, non con un intervallo di date libero:
Dati Periodo Finestra
Energia day, week, month di calendario, nel fuso dell'impianto: dalla mezzanotte locale (giorno), dal lunedì (settimana) o dal giorno 1 (mese) fino a ora
Serie di potenza hour, day mobile: ultimi 60 minuti, ultime 24 ore
Storico allarmi day, week, month mobile: ultime 24 ore, 7 giorni, 30 giorni

Endpoint per più impianti (bulk)

Per ogni lettura periodica di più impianti usa questi tre endpoint. Restituiscono, per una pagina fino a 100 impianti, esattamente ciò che l'endpoint per impianto restituisce per ciascuno, e contano come una sola richiesta.

Endpoint Scope Parametri Restituisce
GET /v1/telemetry/latest read:telemetry plant_ids, limit (1–100), cursor ultima potenza e stato di carica
GET /v1/connectivity read:plants plant_ids, limit (1–100), cursor online / offline per impianto e gateway
GET /v1/energy/totals read:energy period, plant_ids, limit (1–100), cursor totali di energia

Senza plant_ids coprono tutti gli impianti visibili al tuo client. Gli identificativi non visibili vengono esclusi dal risultato senza errore. I risultati sono ordinati per plant_id.

Endpoint per singolo impianto

Endpoint Scope Parametri Restituisce
GET /v1/plants read:plants limit (1–200), cursor impianti, paginati
GET /v1/plants/{plant_id} read:plants — dettaglio impianto con indirizzo
GET /v1/plants/{plant_id}/connectivity read:plants — online / offline per impianto e gateway
GET /v1/plants/{plant_id}/telemetry/latest read:telemetry — ultima potenza e stato di carica
GET /v1/plants/{plant_id}/telemetry/series read:telemetry period (hour, day), measures serie di potenza
GET /v1/plants/{plant_id}/energy/totals read:energy period (day, week, month) totali di energia
GET /v1/plants/{plant_id}/energy/series read:energy period (day, month), include_previous energia per sotto-periodo
GET /v1/plants/{plant_id}/alarms/active read:alarms — allarmi attualmente aperti
GET /v1/plants/{plant_id}/alarms/history read:alarms period (day, week, month), severity allarmi scattati nella finestra

Esempio: potenza istantanea

GET /v1/plants/7b0728a9-853c-4b31-8446-a4eb00607566/telemetry/latest

{
  "plant_id": "7b0728a9-853c-4b31-8446-a4eb00607566",
  "timestamp": "2026-10-13T12:21:00Z",
  "measurements": {
    "grid_power_w": 0,
    "battery_power_w": 18,
    "batteries": [ { "serial": "2527-35520819PH", "soc_pct": 100.0 } ],
    "pv_power_w": 2521,
    "load_power_w": 2503
  }
}

Mezzogiorno, batteria piena: il fotovoltaico copre i carichi, nessuno scambio con la rete. telemetry/series restituisce gli stessi campi come lista di samples, ciascuno con il proprio timestamp: un campione al minuto con period=hour, uno ogni 15 minuti con period=day (lo indica resolution_seconds). measures limita i campi, per esempio measures=pv_power_w,load_power_w.

Esempio: totali di energia

GET /v1/plants/7b0728a9-853c-4b31-8446-a4eb00607566/energy/totals?period=day

{
  "plant_id": "7b0728a9-853c-4b31-8446-a4eb00607566",
  "period": "day",
  "period_start": "2026-10-13T00:00:00+02:00",
  "period_end": "2026-10-13T14:23:15+02:00",
  "totals_wh": {
    "consumed": 4950, "produced": 10380,
    "imported": 100, "exported": 0,
    "charged": 8070, "discharged": 3350
  }
}
Campo Significato
produced energia prodotta dall'impianto fotovoltaico
consumed energia usata dai carichi del sito, da qualunque fonte
imported / exported energia prelevata dalla / immessa in rete
charged / discharged energia accumulata nelle / rilasciata dalle batterie

Un valore è null quando l'impianto non ha fornito dati per quella grandezza nella finestra. energy/series suddivide la stessa finestra in sotto-periodi di un'ora (resolution_seconds); include_previous=true aggiunge l'intero giorno o mese precedente. La somma di una serie è uguale ai totali sulla stessa finestra.

Connettività e allarmi

Un gateway è online se ha inviato dati negli ultimi 5 minuti, altrimenti offline; l'impianto è online se almeno un gateway lo è. unknown significa che lo stato non è determinabile, per esempio per un impianto senza gateway. last_seen_at copre gli ultimi 7 giorni ed è null oltre.

Ogni allarme riporta code e message del dispositivo, raised_at, cleared_at e source, il componente che l'ha generato (gateway, inverter, contatore). La gravità è in severity:

severity Significato
W warning (avviso)
A alarm (allarme)
F fault (guasto)

Considera significativo qualunque altro valore. Il parametro severity filtra senza distinguere maiuscole e minuscole (severity=F). alarms/active restituisce gli allarmi ancora aperti, senza cleared_at; nello storico cleared_at è null per un allarme ancora aperto.