Cum să accesați datele invertorului Heiwit prin API (Data Act)

Cum să accesați datele invertorului Heiwit prin API

Puteți citi datele instalației Heiwit și dintr-un program extern, prin API. Intrați în AI-Care, deschideți Report › Scarica i dati del tuo impianto (Descărcați datele instalației) › Accesso via API (Acces prin API) și creați un token: este cheia pe care programul o folosește pentru a solicita datele. Accesul este gratuit, doar în citire, iar fiecare token este valabil pentru o singură instalație. Este procedura pe care Heiwit o pune la dispoziție pentru exercitarea dreptului de acces la date prevăzut de Data Act european (Regulamentul UE 2023/2854).

Nu se vede videoclipul? Urmăriți-l pe YouTube.

În videoclip vedeți procedura completă: activarea accesului, autentificarea cu tokenul și prima cerere. Mai jos o găsiți explicată pas cu pas, cu lista datelor disponibile, limitele și câteva exemple gata de copiat.

Mai întâi: chiar aveți nevoie de API?

Dacă doriți doar cifrele într-o foaie Excel, nu. În pagina Report din AI-Care există secțiunea Scarica i dati del tuo impianto: alegeți perioada și nivelul de detaliu (oră cu oră, zi cu zi sau lună cu lună) și descărcați un fișier Excel sau CSV. Nu trebuie să configurați nimic.

API-ul este util atunci când doriți ca datele să ajungă automat într-un alt program, fără a descărca manual fișiere. De exemplu:

• un sistem de automatizare a locuinței precum Home Assistant;
• o foaie Excel care se actualizează cu un clic;
• sistemul de gestiune al unei companii, software-ul unui consultant energetic sau al unei comunități energetice;
• un script scris de dumneavoastră sau de tehnicianul dumneavoastră.

Ce este un API, pe scurt

Un API este o adresă web concepută pentru programe, nu pentru oameni. Dumneavoastră deschideți o pagină și o citiți; un program „apelează” adresa și primește datele într-un format ordonat, gata de utilizat: JSON sau CSV.

Fiecare apel include un token, o cheie secretă lungă. Funcționează ca o parolă, cu două diferențe: servește doar la citirea datelor și deschide o singură instalație.

Dreptul la datele dumneavoastră: Data Act

Data Act este regulamentul european privind datele (Regulamentul UE 2023/2854) și se aplică din 12 septembrie 2025. Se referă și la produsele conectate, precum invertorul cu serviciul său de monitorizare, și conferă utilizatorilor două drepturi:

• să acceseze datele generate de utilizarea produsului și să le utilizeze (articolul 4);
• să solicite punerea lor la dispoziția unei terțe părți desemnate de aceștia, de exemplu instalatorul sau un consultant (articolul 5).

De aceea, accesul la datele care vă aparțin este gratuit. Mai întâi Heiwit verifică dacă aveți acest drept: de aceea tokenul se creează doar după autentificarea în AI-Care cu contul asociat instalației.

De ce aveți nevoie

• Contul portalului Heiwit. AI-Care folosește aceleași date de autentificare ca portalul: e-mail sau nume de utilizator și parolă. Dacă nu vă amintiți parola, folosiți Recuperare parolă în pagina de autentificare.
• Instalația asociată contului dumneavoastră. Dacă vă autentificați și nu vedeți instalația, solicitați activarea de la asistență.
• Un program capabil să trimită cereri web: Home Assistant, Excel, Python, comanda curl sau software-ul furnizorului dumneavoastră.

Pasul 1: creați tokenul

1. Accesați ai-care.heiwit.com și autentificați-vă.
2. Dacă aveți mai multe instalații, alegeți-o pe cea care vă interesează.
3. Deschideți Report din meniu.
4. În partea de jos a paginii deschideți secțiunea Scarica i dati del tuo impianto și apoi subsecțiunea Accesso via API.
5. Scrieți un nume care să vă amintească la ce servește tokenul, de exemplu „Home Assistant”, și apăsați Crea token.
6. Copiați imediat tokenul și păstrați-l într-un loc sigur: este afișat o singură dată. Îl recunoașteți pentru că începe cu aic_.

În aceeași secțiune găsiți lista tokenurilor active pentru instalație, cu ultima utilizare, numărul de apeluri și data la care se vor dezactiva. Cu Revoca dezactivați unul instantaneu.

Pasul 2: trimiteți prima cerere

Toate cererile pornesc de la această adresă:

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

Tokenul se trimite într-un antet (header) al cererii numit Authorization, precedat de cuvântul Bearer și de un spațiu:

Authorization: Bearer aic_IL_TUO_TOKEN

Pentru un test rapid este suficient terminalul cu comanda curl, deja prezentă pe Windows 10 și 11, macOS și Linux. Înlocuiți aic_IL_TUO_TOKEN cu tokenul dumneavoastră:

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

Pe Windows, în PowerShell, scrieți curl.exe în loc de curl.

Nu trebuie să indicați ce instalație să fie citită: o stabilește tokenul. Răspunsul este similar cu acesta:

{
  "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
  }
}

În acest exemplu panourile produc 3.120 W: 1.670 W merg către locuință, iar 1.450 W încarcă bateria, care este la 64%. Cu rețeaua nu se face niciun schimb.

Ce puteți citi

API-ul are trei adrese, toate doar în citire (cereri GET):

/status: instalația în acest moment

/energy: istoricul

Exemplu: datele zi de zi din septembrie 2026, doar energie și autoconsum.

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"

Parametrii se adaugă la adresă după semnul întrebării, separați prin &:

Cu granularity=hour o cerere acoperă cel mult 400 de zile: pentru perioade mai lungi faceți mai multe cereri. Cu day și month puteți solicita tot istoricul dintr-o singură dată.

CSV-ul folosește virgula ca separator și punctul pentru zecimale, formatul cel mai comun pentru programe. Pentru a-l deschide în Excel cu setări regionale italiene adăugați &delimiter=semicolon&decimal=comma.

Grupurile de date pe care le puteți solicita cu fields:

Fiecare rând începe cu data (date), la care se adaugă ora (hour) în detaliul orar; în detaliul lunar apare luna (month). Răspunsul JSON din exemplu arată astfel:

{
  "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
    }
  ]
}

Aici sunt afișate doar primele rânduri: în data se află toate cele 30 de zile (count).

/token: starea tokenului

Returnează numele tokenului, sistemul, data creării, ultima utilizare, data la care se va dezactiva dacă nu îl folosiți (expires_at), apelurile făcute astăzi și limitele. Este util pentru a verifica dacă totul funcționează. Și acest apel se contorizează în limita zilnică.

Cât de actualizate sunt datele

• Starea curentă (/status): invertorul trimite o citire aproximativ la fiecare 5 minute, iar API-ul returnează ultima sosită. Nu interoghează invertorul în timp real: citește datele deja colectate de monitorizare, deci apelurile dumneavoastră nu încarcă sistemul.
• Istoric (/energy): ora și ziua în curs sunt parțiale și cresc pe parcurs. Datele și orele sunt cele ale Italiei.
• Dacă invertorul pierde conexiunea la internet, API-ul răspunde oricum cu ultima citire sosită: verificați updated_at pentru a vedea cât de recentă este.
• Valorile în euro sunt estimări, calculate cu prețul angro al energiei (PUN) din perioada respectivă și cu aceeași formulă ca în panourile AI-Care. Nu reprezintă factura dumneavoastră.

Regulile și limitele tokenului

• Un token, un sistem. Dacă aveți mai multe sisteme, creați câte un token pentru fiecare.
• Doar citire. Cu tokenul nu se poate modifica nimic.
• Până la 5 tokenuri active pentru fiecare sistem. Este recomandat să folosiți câte unul pentru fiecare program: dacă trebuie să dezactivați unul, celelalte continuă să funcționeze.
• 10 apeluri pe minut și 300 pe zi pentru fiecare token. Contorul zilnic se resetează la miezul nopții, ora Italiei. Fiecare răspuns indică limita zilnică în antetul X-Quota-Limit și apelurile rămase astăzi în X-Quota-Remaining.
• Fără termen fix de expirare. Tokenul se dezactivează automat dacă rămâne neutilizat timp de 60 de zile; fiecare apel amână expirarea.
• Revocare imediată. Cu Revoca, în pagina Report, tokenul încetează imediat să funcționeze.

Cât de des să solicitați datele? Starea se schimbă aproximativ la fiecare 5 minute, așa că apelurile mai dese nu aduc date noi. Un apel la fiecare 5 minute înseamnă 288 de apeluri pe zi: se încadrează în limită, dar lasă libere doar 12. Dacă același token vă servește și pentru altceva, alegeți un apel la fiecare 10 minute. Pentru istoric este suficient un apel pe zi.

Dacă ceva nu funcționează

Când o cerere nu reușește, API-ul răspunde cu un cod, o siglă (error) și un mesaj în italiană care explică ce trebuie corectat. De exemplu:

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

Exemple gata de folosit

Home Assistant

Cu integrarea RESTful din Home Assistant puteți crea senzori care citesc /status. În fișierul secrets.yaml salvați tokenul, precedat de cuvântul Bearer:

heiwit_aicare: "Bearer aic_IL_TUO_TOKEN"

Apoi adăugați în 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

Cu scan_interval: 600 Home Assistant apelează API-ul la fiecare 10 minute: 144 de apeluri pe zi. Celelalte totaluri din lifetime_kwh (injecție în rețea, consum din rețea, baterie) se adaugă la fel ca senzorul „energie produsă” și pot fi folosite în dashboardul Energie.

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. În Excel deschideți Date › Din web și alegeți Complex.
2. Ca adresă lipiți:
   https://ai-care.heiwit.com/api/v1/energy?granularity=day&format=csv&delimiter=semicolon&decimal=comma
3. În anteturile cererii HTTP scrieți Authorization și, alături, Bearer aic_IL_TUO_TOKEN.
4. Dacă Excel întreabă cum să vă conectați, alegeți Anonim: autorizarea este deja în antet.
5. Încărcați tabelul. Din acel moment Reîmprospătare totală îl reîncarcă cu datele noi.

Fără from și to primiți întotdeauna ultimele 30 de zile. Atenție: tokenul rămâne salvat în fișier, iar cine primește fișierul poate citi datele sistemului.

Pentru instalatori și companii

• Un token pentru fiecare sistem. Cu contul principal de instalator vedeți în AI-Care sistemele pe care le urmăriți și pentru fiecare puteți crea un token din pagina Report. Limitele și expirarea se aplică fiecărui token în parte: cu 40 de sisteme aveți 40 de tokenuri, fiecare cu propriile 300 de apeluri pe zi.
• Conturile de agent nu văd secțiunea Accesso via API (Acces prin API): este necesar contul principal de instalator.
• Datele aparțin clientului. Folosiți-le pentru serviciile convenite cu acesta. Clientul vede în pagina sa Report toate tokenurile active pe sistemul său, inclusiv cele create de dumneavoastră, cu nume și ultima utilizare, și le poate revoca. Dați tokenurilor nume clare, de exemplu „Mentenanță Rossi Impianti”.
• Dacă un client dorește să vă încredințeze datele sale (articolul 5 din Data Act), cea mai simplă cale este ca el să creeze un token dedicat și să vi-l predea. Îl va putea revoca la încheierea colaborării.

Același lucru este valabil pentru companiile de software, consultanții energetici și comunitățile energetice: se conectează cu câte un token pentru fiecare sistem, pe care titularul îl creează și li-l predă.

Securitate: ce nu face acest API

• Nu furnizează credențiale de administrare a invertorului.
• Nu modifică firmware-ul, parametrii electrici sau setările de protecție: doar citește.
• Tokenul nu deschide contul dumneavoastră AI-Care și nu oferă acces la alte sisteme.

Tratați totuși tokenul ca pe o parolă: nu îl publicați online, nu îl lăsați în fișiere partajate, nu îl trimiteți pe chat. Dacă vă temeți că cineva l-a văzut, revocați-l și creați unul nou. Heiwit păstrează doar o amprentă (hash) a tokenului, nu tokenul în sine: de aceea nimeni, nici măcar asistența, nu vi-l poate retrimite. Comunicațiile cu API-ul sunt criptate (HTTPS).

Întrebări frecvente

Cât costă?

Nimic. Accesul la datele care vă revin este gratuit.

Cu API-ul pot modifica setările invertorului?

Nu. API-ul este doar în citire: nu atinge firmware-ul, parametrii electrici sau protecțiile.

Pot da datele mele instalatorului sau altei companii?

Da. Data Act vă permite să solicitați punerea lor la dispoziția unui terț desemnat de dumneavoastră. În practică, creați un token cu un nume ușor de recunoscut și îl predați celui ales; îl puteți revoca oricând. Pentru alte solicitări scrieți asistenței.

Am pierdut tokenul. Mi-l puteți retrimite?

Nu, deoarece Heiwit nu îl păstrează. Creați unul nou și revocați-l pe cel vechi.

Tokenul expiră?

Doar dacă nu îl folosiți: după 60 de zile fără apeluri, se dezactivează automat. Cât timp îl folosiți, rămâne activ.

Pot citi mai multe instalații cu un singur token?

Nu, fiecare token este valabil pentru o singură instalație. Pentru mai multe instalații sunt necesare mai multe tokenuri.

Valorile în euro sunt cele de pe factură?

Nu. Sunt estimări calculate pe baza prețului angro al energiei (PUN) din perioada respectivă.

Cât de mult în urmă pot merge?

Până la începutul datelor înregistrate de monitorizare. Cu detaliere orară, fiecare cerere acoperă cel mult 400 de zile.

Funcționează cu Home Assistant?

Da, cu integrarea RESTful: găsiți configurația în exemplele de mai sus.

Linkuri utile

• Documentația API și lista datelor accesibile: ai-care.heiwit.com/report (după autentificare, secțiunea Scarica i dati del tuo impianto (Descărcați datele instalației dvs.) › Accesso via API (Acces prin API)).
• Activarea accesului și asistență: ai-care.heiwit.com/login.
• Ghid video: Invertor Heiwit: cum să accesați propriile date prin API.

Referințe legislative: Regulamentul (UE) 2023/2854 al Parlamentului European și al Consiliului din 13 decembrie 2023 (Data Act), în special articolul 4, privind accesul utilizatorului la date, și articolul 5, privind partajarea acestora cu terți. Accesul la datele care îi revin utilizatorului este gratuit, sub rezerva verificării legitimității solicitantului; punerea datelor la dispoziția unui terț desemnat de utilizator se face în condițiile prevăzute de regulament. Indicațiile tehnice se referă la versiunea 1 a API-ului (/api/v1) la 5 octombrie 2026.

API-ul citește datele colectate de AI-Care, platforma Heiwit de monitorizare a instalațiilor. Inima instalației esteinvertorul hibrid Virgo, asociat cu bateria Heiwit sodiu-ion de 10 kWh.