L'API remota dà alla tua piattaforma accesso diretto, in sola lettura, ai dati di monitoraggio degli impianti fotovoltaici e di accumulo collegati alla tua organizzazione. È pensata per chi vuole portare questi dati nei propri sistemi.
Cosa offre
- anagrafica degli impianti: nome, paese, fuso orario, indirizzo
- connettività: impianto e gateway online o offline
- potenza istantanea e serie di potenza: fotovoltaico, carichi, rete, batteria e stato di carica
- totali e serie di energia: prodotta, consumata, prelevata, immessa, caricata e scaricata
- allarmi attivi e storici
È un'API REST su HTTPS: richieste e risposte sono in JSON e l'accesso è machine-to-machine con OAuth 2.0 client credentials. I dati si ottengono interrogando l'API (polling): l'API non invia dati di sua iniziativa.
| Indirizzo | |
|---|---|
| URL base dell'API | https://api.cloud.energyincloud.com |
| Endpoint del token | https://k8s.prod.cloud.energyincloud.com/webapp/oauth/token |
Tutti gli endpoint dei dati si trovano sotto /v1.
Cosa non fa
- Non modifica gli impianti. Questa versione è di sola lettura. Le funzioni di controllo (setpoint, modalità di funzionamento) non sono attive: saranno attivate con un accordo dedicato.
- Non vede impianti di altre organizzazioni. Un impianto non collegato alla tua organizzazione risulta "non trovato".
- Non ti avvisa quando qualcosa cambia. Per avere dati aggiornati interroghi l'API a intervalli regolari: la pagina "Unità, segni e aggiornamento dei dati" indica ogni quanto.
Come ottenere un client
L'accesso all'API viene abilitato solo su richiesta esplicita: le credenziali non si possono creare in autonomia dal portale.
- Chiedi l'accesso a zeroCO2 scrivendo a info@energysynt.com e indicando la tua organizzazione.
- Un operatore zeroCO2 crea un client API per la tua organizzazione e ti consegna un
client_ide unclient_secret. - Conserva subito il secret in un secrets manager: viene mostrato una sola volta, alla creazione. Non inserirlo mai in codice eseguito lato client, come una pagina web o un'app.
Se il secret viene perso o esposto, chiedi a zeroCO2 un nuovo client.
Per impostazione predefinita un client riceve questi permessi (scope):
| Scope | Dà accesso a |
|---|---|
read:plants |
elenco e dettaglio impianti, connettività |
read:telemetry |
potenza istantanea e serie di potenza |
read:energy |
totali e serie di energia |
read:alarms |
allarmi attivi e storici |
I token contengono anche read:controls, riservato alle funzioni di controllo non attive in questa versione.
Quali impianti vede il client
Il client vede esattamente gli impianti collegati alla tua organizzazione. L'elenco lo ottieni con GET /v1/plants. Ogni impianto ha un identificativo stabile, plant_id, da usare in tutte le altre chiamate.
Da dove iniziare
- Ottieni il client come descritto sopra.
- Segui "Autenticazione e prima chiamata" per ottenere un token ed elencare i tuoi impianti.
- Prima di mettere in esercizio l'integrazione, leggi "Limiti, errori e supporto".