Come accedere ai dati del tuo inverter Heiwit tramite API (Data Act)

Come accedere ai dati del tuo inverter Heiwit tramite API

Puoi leggere i dati del tuo impianto Heiwit anche da un programma esterno, tramite API. Entri in AI Care, apri Report › Scarica i dati del tuo impianto › Accesso via API e crei un token: è la chiave che il programma usa per chiedere i dati. L’accesso è gratuito, è in sola lettura e ogni token vale per un solo impianto. È la procedura che Heiwit mette a disposizione per esercitare l’accesso ai dati previsto dal Data Act europeo (Regolamento UE 2023/2854).

Il video non si vede? Guardalo su YouTube.

Nel video vedi la procedura completa: abilitazione dell’accesso, autenticazione con il token e prima richiesta. Qui sotto la trovi spiegata passo per passo, con l’elenco dei dati disponibili, i limiti e qualche esempio pronto da copiare.

Prima di tutto: ti serve davvero l’API?

Se vuoi solo i numeri in un foglio Excel, no. Nella pagina Report di AI Care c’è il riquadro Scarica i dati del tuo impianto: scegli il periodo e il dettaglio (ora per ora, giorno per giorno o mese per mese) e scarichi un file Excel o CSV. Non serve configurare niente.

L’API serve quando vuoi che i dati arrivino da soli in un altro programma, senza scaricare file a mano. Per esempio:

• un sistema di domotica come Home Assistant;
• un foglio Excel che si aggiorna con un clic;
• il gestionale di un’azienda, il software di un consulente energetico o di una comunità energetica;
• uno script scritto da te o dal tuo tecnico.

Cos’è un’API, in parole semplici

Un’API è un indirizzo web pensato per i programmi invece che per le persone. Tu apri una pagina e la leggi; un programma “chiama” l’indirizzo e riceve i dati in un formato ordinato, pronto da usare: JSON oppure CSV.

Ogni chiamata porta con sé un token, una lunga chiave segreta. Funziona come una password, con due differenze: serve solo a leggere i dati e apre un solo impianto.

Il diritto ai tuoi dati: il Data Act

Il Data Act è il regolamento europeo sui dati (Regolamento UE 2023/2854) e si applica dal 12 settembre 2025. Riguarda anche i prodotti connessi, come l’inverter con il suo servizio di monitoraggio, e dà a chi li usa due diritti:

• accedere ai dati generati dall’uso del prodotto e utilizzarli (articolo 4);
• farli mettere a disposizione di un soggetto terzo incaricato da lui, per esempio l’installatore o un consulente (articolo 5).

Per questo l’accesso ai dati che ti spettano è gratuito. Prima Heiwit verifica che tu ne abbia diritto: per questo il token si crea solo dopo essere entrati in AI Care con l’account a cui è associato l’impianto.

Cosa ti serve

• L’account del portale Heiwit. AI Care usa le stesse credenziali del portale: email o nome utente e password. Se non ricordi la password, usa Recupera la password nella pagina di accesso.
• L’impianto associato al tuo account. Se entri e non vedi il tuo impianto, chiedi l’abilitazione all’assistenza.
• Un programma che sappia fare richieste web: Home Assistant, Excel, Python, il comando curl o il software del tuo fornitore.

Passo 1: crea il token

1. Vai su ai-care.heiwit.com e accedi.
2. Se hai più impianti, scegli quello che ti interessa.
3. Apri Report dal menu.
4. In fondo alla pagina apri il riquadro Scarica i dati del tuo impianto e poi la sezione Accesso via API.
5. Scrivi un nome che ti ricordi a cosa serve il token, per esempio “Home Assistant”, e premi Crea token.
6. Copia subito il token e conservalo in un posto sicuro: viene mostrato una volta sola. Lo riconosci perché inizia con aic_.

Nella stessa sezione trovi l’elenco dei token attivi sull’impianto, con l’ultimo utilizzo, il numero di chiamate e la data in cui si disattiveranno. Con Revoca ne spegni uno all’istante.

Passo 2: fai la prima richiesta

Tutte le richieste partono da questo indirizzo:

https://ai-care.heiwit.com/api/v1

Il token si invia in un’intestazione (header) della richiesta chiamata Authorization, preceduto dalla parola Bearer e da uno spazio:

Authorization: Bearer aic_IL_TUO_TOKEN

Per una prova veloce basta il terminale con il comando curl, già presente su Windows 10 e 11, macOS e Linux. Sostituisci aic_IL_TUO_TOKEN con il tuo token:

curl -H "Authorization: Bearer aic_IL_TUO_TOKEN" "https://ai-care.heiwit.com/api/v1/status"

Su Windows, in PowerShell, scrivi curl.exe al posto di curl.

Non devi indicare quale impianto leggere: lo stabilisce il token. La risposta è simile a questa:

{
  "plant": {
    "sn": "90xxxxxxxxxxxxxxxx",
    "name": "Casa",
    "model": "Virgo6K-S-HW",
    "installed_power_kwp": 6,
    "battery_capacity_kwh": 10
  },
  "updated_at": "2026-10-05 07:10:12",
  "now": {
    "pv_w": 3120,
    "battery_w": -1450,
    "grid_w": 0,
    "load_w": 1670,
    "battery_soc": 64,
    "battery_soh": 100,
    "work_mode": 1,
    "work_mode_label": "Self-use (autoconsumo)"
  },
  "lifetime_kwh": {
    "pv": 8421.5,
    "export": 2310.2,
    "import": 1187.4,
    "bat_charge": 2950.8,
    "bat_discharge": 2702.3
  }
}

In questo esempio i pannelli producono 3.120 W: 1.670 W vanno alla casa e 1.450 W caricano la batteria, che è al 64%. Con la rete non si scambia niente.

Cosa puoi leggere

L’API ha tre indirizzi, tutti in sola lettura (richieste GET):

/status: l’impianto adesso

/energy: lo storico

Esempio: i dati giorno per giorno di settembre 2026, solo energia e autoconsumo.

curl -H "Authorization: Bearer aic_IL_TUO_TOKEN" "https://ai-care.heiwit.com/api/v1/energy?granularity=day&from=2026-09-01&to=2026-09-30&fields=energy,derived"

I parametri si aggiungono all’indirizzo dopo il punto di domanda, separati da &:

Με granularity=hour una richiesta copre al massimo 400 giorni: per periodi più lunghi fai più richieste. Con day e month puoi chiedere tutto lo storico in una volta sola.

Il CSV usa la virgola come separatore e il punto per i decimali, il formato più comune per i programmi. Per aprirlo con Excel in italiano aggiungi &delimiter=semicolon&decimal=comma.

I gruppi di dati che puoi chiedere con fields:

Ogni riga comincia con la data (date), a cui si aggiunge l’ora (hour) nel dettaglio orario; nel dettaglio mensile c’è il mese (month). La risposta JSON dell’esempio è fatta così:

{
  "plant": { "sn": "90xxxxxxxxxxxxxxxx" },
  "granularity": "day",
  "from": "2026-09-01",
  "to": "2026-09-30",
  "fields": ["energy", "derived"],
  "count": 30,
  "truncated": false,
  "generated_at": "2026-10-05T09:30:00+02:00",
  "data": [
    {
      "date": "2026-09-01",
      "pv_kwh": 31.4,
      "export_kwh": 9.8,
      "import_kwh": 1.2,
      "bat_charge_kwh": 8.7,
      "bat_discharge_kwh": 7.9,
      "self_consumption_kwh": 20.8,
      "home_load_kwh": 22.0,
      "autonomy_pct": 94.5,
      "pv_self_used_pct": 68.8
    }
  ]
}

Qui sono mostrate solo le prime righe: in data ci sono tutti i 30 giorni (count).

/token: lo stato del token

Restituisce il nome del token, l’impianto, la data di creazione, l’ultimo utilizzo, la data in cui si disattiverà se non lo usi (expires_at), le chiamate fatte oggi e i limiti. È utile per controllare che tutto funzioni. Anche questa chiamata conta nel limite giornaliero.

Quanto sono aggiornati i dati

• Stato attuale (/status): l’inverter invia una lettura circa ogni 5 minuti e l’API restituisce l’ultima arrivata. Non interroga l’inverter in diretta: legge i dati già raccolti dal monitoraggio, quindi le tue chiamate non pesano sull’impianto.
• Storico (/energy): l’ora e il giorno in corso sono parziali e crescono man mano. Date e ore sono quelle italiane.
• Se l’inverter perde la connessione a internet, l’API risponde comunque con l’ultima lettura arrivata: guarda updated_at per capire quanto è recente.
• I valori in euro sono stime, calcolate con il prezzo dell’energia all’ingrosso (PUN) del periodo e con la stessa formula dei riquadri di AI Care. Non sono la tua bolletta.

Regole e limiti del token

• Un token, un impianto. Se hai più impianti, crei un token per ognuno.
• Solo lettura. Con il token non si può cambiare nulla.
• Fino a 5 token attivi per impianto. Conviene usarne uno per ogni programma: se ne devi spegnere uno, gli altri continuano a funzionare.
• 10 chiamate al minuto e 300 al giorno per ciascun token. Il conteggio del giorno riparte a mezzanotte, ora italiana. Ogni risposta riporta il limite giornaliero nell’intestazione X-Quota-Limit e le chiamate rimaste oggi in X-Quota-Remaining.
• Nessuna scadenza fissa. Il token si disattiva da solo se resta inutilizzato per 60 giorni; ogni chiamata sposta in avanti la scadenza.
• Revoca immediata. Με Revoca, nella pagina Report, il token smette di funzionare subito.

Ogni quanto chiedere i dati? Lo stato cambia circa ogni 5 minuti, quindi chiamare più spesso non dà dati nuovi. Una chiamata ogni 5 minuti fa 288 chiamate al giorno: rientra nel limite, ma ne lascia libere solo 12. Se lo stesso token ti serve anche per altro, scegli una chiamata ogni 10 minuti. Per lo storico basta una chiamata al giorno.

Se qualcosa non va

Quando una richiesta non va a buon fine, l’API risponde con un codice, una sigla (error) e un messaggio in italiano che spiega cosa correggere. Per esempio:

{ "error": "invalid_token", "message": "Token non valido o revocato." }

Esempi pronti

Home Assistant

Con l’integrazione RESTful di Home Assistant puoi creare dei sensori che leggono /status. Nel file secrets.yaml salva il token, con la parola Bearer davanti:

heiwit_aicare: "Bearer aic_IL_TUO_TOKEN"

Poi aggiungi in configuration.yaml:

rest:
  - resource: https://ai-care.heiwit.com/api/v1/status
    scan_interval: 600
    headers:
      Authorization: !secret heiwit_aicare
    sensor:
      - name: "Heiwit produzione FV"
        value_template: "{{ value_json.now.pv_w }}"
        unit_of_measurement: "W"
        device_class: power
        state_class: measurement
      - name: "Heiwit batteria"
        value_template: "{{ value_json.now.battery_soc }}"
        unit_of_measurement: "%"
        device_class: battery
      - name: "Heiwit scambio con la rete"
        value_template: "{{ value_json.now.grid_w }}"
        unit_of_measurement: "W"
        device_class: power
        state_class: measurement
      - name: "Heiwit energia prodotta"
        value_template: "{{ value_json.lifetime_kwh.pv }}"
        unit_of_measurement: "kWh"
        device_class: energy
        state_class: total_increasing

Με scan_interval: 600 Home Assistant chiama l’API ogni 10 minuti: 144 chiamate al giorno. Gli altri totali di lifetime_kwh (immissione, prelievo, batteria) si aggiungono come il sensore “energia prodotta” e si possono usare nella dashboard Energia.

Python

import requests

TOKEN = "aic_IL_TUO_TOKEN"

risposta = requests.get(
    "https://ai-care.heiwit.com/api/v1/energy",
    headers={"Authorization": f"Bearer {TOKEN}"},
    params={"granularity": "day", "from": "2026-09-01", "to": "2026-09-30"},
    timeout=30,
)
risposta.raise_for_status()

for giorno in risposta.json()["data"]:
    print(giorno["date"], giorno["pv_kwh"], "kWh prodotti")

Excel

1. In Excel apri Dati › Da Web e scegli Avanzate.
2. Come indirizzo incolla:
   https://ai-care.heiwit.com/api/v1/energy?granularity=day&format=csv&delimiter=semicolon&decimal=comma
3. Nelle intestazioni della richiesta HTTP scrivi Authorization e, accanto, Bearer aic_IL_TUO_TOKEN.
4. Se Excel chiede come accedere, scegli Anonimo: l’autorizzazione è già nell’intestazione.
5. Carica la tabella. Da quel momento Aggiorna tutto la riscarica con i dati nuovi.

Senza from e to ricevi sempre gli ultimi 30 giorni. Attenzione: il token resta salvato nel file, e chi riceve il file può leggere i dati dell’impianto.

Per installatori e aziende

• Un token per impianto. Con l’account principale dell’installatore vedi in AI Care gli impianti che segui, e per ciascuno puoi creare un token dalla pagina Report. Limiti e scadenza valgono token per token: con 40 impianti hai 40 token, ognuno con le sue 300 chiamate al giorno.
• Gli account agente non vedono la sezione Accesso via API: serve l’account principale dell’installatore.
• I dati sono del cliente. Usali per i servizi concordati con lui. Il cliente vede nella sua pagina Report tutti i token attivi sul suo impianto, anche quelli creati da te, con nome e ultimo utilizzo, e può revocarli. Dai ai token nomi chiari, per esempio “Manutenzione Rossi Impianti”.
• Se un cliente vuole affidarti i suoi dati (articolo 5 del Data Act), la strada più semplice è che crei lui un token dedicato e te lo consegni. Potrà revocarlo quando il rapporto finisce.

Lo stesso vale per software house, consulenti energetici e comunità energetiche: si collegano con un token per impianto, che il titolare crea e consegna loro.

Sicurezza: cosa questa API non fa

• Non rilascia credenziali di amministrazione dell’inverter.
• Non modifica firmware, parametri elettrici o impostazioni di protezione: legge soltanto.
• Il token non apre il tuo account AI Care e non dà accesso ad altri impianti.

Tratta comunque il token come una password: non pubblicarlo online, non lasciarlo in file condivisi, non mandarlo in chat. Se temi che qualcuno l’abbia visto, revocalo e creane uno nuovo. Heiwit conserva solo un’impronta (hash) del token, non il token stesso: per questo nessuno, nemmeno l’assistenza, può rimandartelo. Le comunicazioni con l’API sono cifrate (HTTPS).

Συχνές ερωτήσεις

Quanto costa?

Niente. L’accesso ai dati che ti spettano è gratuito.

Con l’API posso cambiare le impostazioni dell’inverter?

No. L’API è in sola lettura: non tocca firmware, parametri elettrici o protezioni.

Posso dare i miei dati all’installatore o a un’altra azienda?

Sì. Il Data Act ti permette di farli mettere a disposizione di un soggetto terzo incaricato da te. In pratica crei un token con un nome riconoscibile e lo consegni a chi hai scelto; puoi revocarlo quando vuoi. Per richieste diverse scrivi all’assistenza.

Ho perso il token. Me lo potete rimandare?

No, perché Heiwit non lo conserva. Creane uno nuovo e revoca quello vecchio.

Il token scade?

Solo se non lo usi: dopo 60 giorni senza chiamate si disattiva da solo. Finché lo usi resta attivo.

Posso leggere più impianti con un solo token?

No, ogni token vale per un impianto. Per più impianti servono più token.

I valori in euro sono quelli della bolletta?

No. Sono stime calcolate con il prezzo dell’energia all’ingrosso (PUN) del periodo.

Quanto indietro nel tempo posso andare?

Fino all’inizio dei dati registrati dal monitoraggio. Con il dettaglio orario ogni richiesta copre al massimo 400 giorni.

Funziona con Home Assistant?

Sì, con l’integrazione RESTful: trovi la configurazione negli esempi qui sopra.

Link utili

• Documentazione API ed elenco dei dati accessibili: ai-care.heiwit.com/report (dopo l’accesso, riquadro Scarica i dati del tuo impianto › Accesso via API).
• Abilitazione dell’accesso e assistenza: ai-care.heiwit.com/login.
• Video guida: Inverter Heiwit: come accedere ai propri dati tramite API.

Riferimenti normativi: Regolamento (UE) 2023/2854 del Parlamento europeo e del Consiglio, del 13 dicembre 2023 (Data Act), in particolare l’articolo 4, sull’accesso dell’utente ai dati, e l’articolo 5, sulla loro condivisione con terzi. L’accesso ai dati spettanti all’utente è gratuito, previa verifica della legittimazione del richiedente; la messa a disposizione dei dati a un terzo incaricato dall’utente avviene alle condizioni previste dal regolamento. Le indicazioni tecniche si riferiscono alla versione 1 dell’API (/api/v1) al 5 ottobre 2026.

L’API legge i dati raccolti da AI Care, la piattaforma Heiwit di monitoraggio degli impianti. Il cuore dell’impianto è l’inverter ibrido Virgo, abbinato alla μπαταρία Heiwit ιόντων νατρίου 10 kWh.