Hogyan férhet hozzá Heiwit inverterének adataihoz API-n keresztül (Data Act)

Hogyan férhet hozzá Heiwit inverterének adataihoz API-n keresztül

Heiwit-rendszerének adatait egy külső programból is kiolvashatja, API-n keresztül. Belép az AI-Care-be, megnyitja a Report › Scarica i dati del tuo impianto (Töltse le rendszere adatait) › Accesso via API (Hozzáférés API-n keresztül) menüpontot, és létrehoz egy tokent: ez az a kulcs, amellyel a program lekéri az adatokat. A hozzáférés ingyenes, csak olvasható, és minden token egyetlen rendszerre érvényes. Ezt az eljárást biztosítja a Heiwit az európai Data Act ((EU) 2023/2854 rendelet) által előírt adathozzáférés gyakorlásához.

Nem jelenik meg a videó? Nézze meg a YouTube-on.

A videóban a teljes folyamatot láthatja: a hozzáférés engedélyezését, a tokenes hitelesítést és az első lekérést. Alább lépésről lépésre elmagyarázzuk, az elérhető adatok listájával, a korlátokkal és néhány másolásra kész példával.

Először is: valóban szüksége van az API-ra?

Ha csak egy Excel-táblázatban szeretné látni a számokat, akkor nem. Az AI-Care Report oldalán található a Scarica i dati del tuo impiantopanel: kiválasztja az időszakot és a részletességet (óránként, naponta vagy havonta), és letölt egy Excel- vagy CSV-fájlt. Semmit sem kell beállítani.

Az API akkor hasznos, ha azt szeretné, hogy az adatok maguktól érkezzenek meg egy másik programba, kézi fájlletöltés nélkül. Például:

• egy okosotthon-rendszer, például Home Assistant;
• egy egy kattintással frissülő Excel-táblázat;
• egy vállalat ügyviteli rendszere, egy energetikai tanácsadó vagy egy energiaközösség szoftvere;
• egy Ön vagy szakembere által írt szkript.

Mi az API, egyszerűen

Az API egy programoknak, nem pedig embereknek szánt webcím. Ön megnyit egy oldalt és elolvassa; egy program „meghívja” a címet, és rendezett, azonnal használható formátumban kapja meg az adatokat: JSON vagy CSV formátumban.

Minden hívás tartalmaz egy token-t, egy hosszú titkos kulcsot. Úgy működik, mint egy jelszó, két különbséggel: csak az adatok olvasására szolgál, és csak egyetlen rendszert nyit meg.

Az Ön adataihoz való joga: a Data Act

A Data Act az európai adatrendelet ((EU) 2023/2854 rendelet), és 2025. szeptember 12-től alkalmazandó. A csatlakoztatott termékekre is vonatkozik, például az inverterre és annak felügyeleti szolgáltatására, és két jogot biztosít a felhasználóknak:

• hozzáférni az adatokhoz, a termék használata során keletkező adatokhoz, és felhasználni azokat (4. cikk);
• azokat egy általa megbízott harmadik fél rendelkezésére bocsáttatni, például a telepítő vagy egy tanácsadó részére (5. cikk).

Ezért az Önt megillető adatokhoz való hozzáférés ingyenes. Előbb a Heiwit ellenőrzi, hogy Önnek joga van-e hozzá: ezért a token csak azután hozható létre, hogy belépett az AI-Care-be azzal a fiókkal, amelyhez a rendszer társítva van.

Mire van szüksége

• A Heiwit portál fiókjára. Az AI-Care ugyanazokat a belépési adatokat használja, mint a portál: e-mail-cím vagy felhasználónév és jelszó. Ha elfelejtette a jelszavát, használja a Jelszó visszaállítása funkciót a bejelentkezési oldalon.
• A fiókjához társított rendszerre. Ha belépés után nem látja a rendszerét, kérje az engedélyezést az ügyfélszolgálattól.
• Egy webes kérések küldésére képes programra: Home Assistant, Excel, Python, a curl parancs vagy a szolgáltatója szoftvere.

1. lépés: hozza létre a tokent

1. Nyissa meg az ai-care.heiwit.com oldalt, és jelentkezzen be.
2. Ha több rendszere van, válassza ki azt, amelyik érdekli.
3. Nyissa meg a Report menüpontot a menüből.
4. Az oldal alján nyissa meg a Scarica i dati del tuo impianto panelt, majd a Accesso via API.
5. részt. Adjon meg egy nevet, amely emlékezteti arra, mire szolgál a token, például „Home Assistant”, majd nyomja meg a Crea token.
6. Azonnal másolja ki a tokent és tárolja biztonságos helyen: csak egyszer jelenik meg. Onnan ismeri fel, hogy ezzel kezdődik: aic_.

Ugyanebben a részben megtalálja a rendszeren aktív tokenek listáját, az utolsó használattal, a hívások számával és a lejárat dátumával. A Revoca gombbal azonnal letilthat egyet.

2. lépés: küldje el az első lekérést

Minden lekérés erről a címről indul:

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

A tokent a lekérés egyik fejlécében (header) kell elküldeni, amelynek neve Authorization, előtte a Bearer szóval és egy szóközzel:

Authorization: Bearer aic_IL_TUO_TOKEN

Egy gyors próbához elég a terminál és a curlparancs, amely a Windows 10 és 11, a macOS és a Linux rendszereken már megtalálható. Cserélje ki az aic_IL_TUO_TOKEN részt a saját tokenjére:

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

Windowson, PowerShellben írja ezt: curl.exe ehelyett: curl.

Nem kell megadnia, melyik rendszert olvassa: ezt a token határozza meg. A válasz ehhez hasonló:

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

Ebben a példában a napelemek 3120 W-ot termelnek: 1670 W a házba jut, 1450 W pedig az akkumulátort tölti, amely 64%-on áll. A hálózattal nincs energiacsere.

Mit olvashat ki

Az API-nak három címe van, mindegyik csak olvasható (GET kérések):

/status: a rendszer most

/energy: az előzmények

Példa: 2026 szeptemberének napi adatai, csak energia és saját fogyasztás.

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"

A paramétereket a kérdőjel után kell a címhez fűzni, egymástól elválasztva ezzel: &:

A granularity=hour esetén egy kérés legfeljebb 400 napot fedhet le: hosszabb időszakokhoz több kérést kell küldenie. A day és month értékkel a teljes előzményt egyszerre lekérheti.

A CSV elválasztóként vesszőt, tizedesjelként pontot használ, ez a programok számára legelterjedtebb formátum. Ha magyar nyelvű Excellel szeretné megnyitni, adja hozzá ezt: &delimiter=semicolon&decimal=comma.

A lekérhető adatcsoportok, amelyeket ezzel kérhet: fields:

Minden sor a dátummal kezdődik (date), amelyhez órás bontásban az óra (hour) is társul; havi bontásban a hónap szerepel (month). A példa JSON-válasza így néz ki:

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

Itt csak az első sorok láthatók: a data mezőben mind a 30 nap megtalálható (count).

/token: a token állapota

Visszaadja a token nevét, a rendszert, a létrehozás dátumát, az utolsó használatot, azt a dátumot, amikor használat hiányában inaktiválódik (expires_at), a mai napon indított hívásokat és a korlátokat. Hasznos annak ellenőrzésére, hogy minden működik-e. Ez a hívás is beleszámít a napi korlátba.

Mennyire frissek az adatok

• Aktuális állapot (/status): az inverter nagyjából 5 percenként küld leolvasást, az API pedig a legutóbb beérkezettet adja vissza. Nem kérdezi le élőben az invertert: a monitorozás által már összegyűjtött adatokat olvassa, így hívásai nem terhelik a rendszert.
• Előzmények (/energy): a folyamatban lévő óra és nap részleges, és folyamatosan növekszik. A dátumok és időpontok olasz idő szerintiek.
• Ha az inverter elveszíti az internetkapcsolatot, az API akkor is válaszol a legutóbb beérkezett leolvasással: nézze meg az updated_at mezőt, hogy lássa, mennyire friss.
• Az euróban megadott értékek becslések, amelyek az adott időszak nagykereskedelmi energiaárával (PUN) és az AI-Care paneljeivel azonos képlettel készülnek. Ezek nem az Ön villanyszámlája.

A token szabályai és korlátai

• Egy token, egy rendszer. Ha több rendszere van, mindegyikhez hozzon létre egy tokent.
• Csak olvasás. A tokennel semmit nem lehet módosítani.
• Rendszerenként legfeljebb 5 aktív token. Érdemes minden programhoz külön tokent használni: ha az egyiket le kell tiltania, a többi tovább működik.
• Tokenenként percenként 10 és naponta 300 hívás. A napi számláló olasz idő szerint éjfélkor nullázódik. Minden válasz tartalmazza a napi korlátot az X-Quota-Limit fejlécben, a mai napon még hátralévő hívások számát pedig az X-Quota-Remaining.
• Nincs fix lejárat. A token automatikusan inaktiválódik, ha 60 napig nem használják; minden hívás kitolja a lejáratot.
• Azonnali visszavonás. A Revocagombbal a Report oldalon a token azonnal leáll.

Milyen gyakran kérje le az adatokat? Az állapot körülbelül 5 percenként változik, így a gyakoribb hívás nem ad új adatot. Ötpercenkénti hívással naponta 288 hívás jön ki: ez belefér a korlátba, de csak 12 marad szabadon. Ha ugyanarra a tokenre másra is szüksége van, válasszon 10 percenkénti hívást. Az előzményadatokhoz napi egy hívás is elég.

Ha valami nem működik

Ha egy kérés sikertelen, az API egy kóddal, egy rövidítéssel (error) és egy olasz nyelvű üzenettel válaszol, amely elmagyarázza, mit kell javítani. Például:

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

Kész példák

Home Assistant

A Home Assistant RESTful integrációjával olyan szenzorokat hozhat létre, amelyek ezt olvassák: /status. A secrets.yaml fájlba mentse el a tokent, elé írva a Bearer szót:

heiwit_aicare: "Bearer aic_IL_TUO_TOKEN"

Ezután adja hozzá a 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

A scan_interval: 600 A Home Assistant 10 percenként hívja az API-t: naponta 144 hívás. A lifetime_kwh többi összesítője (betáplálás, vételezés, akkumulátor) a „termelt energia” szenzorhoz hasonlóan adható hozzá, és használható az Energia irányítópulton.

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. Az Excelben nyissa meg az Adatok › Weből menüt, és válassza a Speciális.
2. lehetőséget. Címként illessze be:
   https://ai-care.heiwit.com/api/v1/energy?granularity=day&format=csv&delimiter=semicolon&decimal=comma
3. A HTTP-kérés fejléceinél írja be: Authorization és mellé: Bearer aic_IL_TUO_TOKEN.
4. Ha az Excel rákérdez a hozzáférés módjára, válassza a Névtelenlehetőséget: az engedélyezés már a fejlécben szerepel.
5. Töltse be a táblázatot. Ettől kezdve az Összes frissítése az új adatokkal tölti be újra.

A from és to nélkül mindig az elmúlt 30 nap adatait kapja. Figyelem: a token a fájlban mentve marad, és aki megkapja a fájlt, olvashatja a rendszer adatait.

Telepítőknek és vállalatoknak

• Rendszerenként egy token. A telepítő fő fiókjával az AI-Care-ben látja az Ön által felügyelt rendszereket, és mindegyikhez létrehozhat egy tokent a Report oldalon. A korlátok és a lejárat tokenenként érvényesek: 40 rendszerhez 40 token tartozik, mindegyik napi 300 hívással.
• Az ügynöki fiókok nem látják az Accesso via API (Hozzáférés API-n keresztül) részt: ehhez a telepítő fő fiókja szükséges.
• Az adatok az ügyfélé. Csak az ügyféllel egyeztetett szolgáltatásokhoz használja őket. Az ügyfél a saját Report oldalán látja a rendszerén aktív összes tokent, az Ön által létrehozottakat is, névvel és utolsó használattal, és visszavonhatja őket. Adjon a tokeneknek egyértelmű neveket, például „Karbantartás – Rossi Impianti”.
• Ha egy ügyfél Önre szeretné bízni az adatait (a Data Act 5. cikke), a legegyszerűbb, ha ő maga hoz létre egy külön tokent, és átadja Önnek. Az együttműködés végén visszavonhatja.

Ugyanez érvényes a szoftverfejlesztő cégekre, energetikai tanácsadókra és energiaközösségekre: rendszerenként egy tokennel csatlakoznak, amelyet a tulajdonos hoz létre és ad át nekik.

Biztonság: mit nem tesz ez az API

• Nem ad ki adminisztrátori hozzáférési adatokat az inverterhez.
• Nem módosítja a firmware-t, az elektromos paramétereket vagy a védelmi beállításokat: csak olvas.
• A token nem nyitja meg az AI-Care-fiókját, és nem ad hozzáférést más rendszerekhez.

A tokent ennek ellenére kezelje jelszóként: ne tegye közzé online, ne hagyja megosztott fájlokban, ne küldje el chaten. Ha attól tart, hogy valaki látta, vonja vissza, és hozzon létre újat. A Heiwit csak a token lenyomatát (hash) tárolja, magát a tokent nem: ezért senki, még az ügyfélszolgálat sem tudja újra elküldeni. Az API-val folytatott kommunikáció titkosított (HTTPS).

Gyakran ismételt kérdések

Mennyibe kerül?

Semmibe. Az Önt megillető adatokhoz való hozzáférés ingyenes.

Módosíthatom az API-val az inverter beállításait?

Nem. Az API csak olvasható: nem nyúl a firmware-hez, az elektromos paraméterekhez vagy a védelmekhez.

Átadhatom az adataimat a telepítőnek vagy egy másik cégnek?

Igen. A Data Act lehetővé teszi, hogy az adatokat egy Ön által megbízott harmadik fél rendelkezésére bocsássák. A gyakorlatban létrehoz egy felismerhető nevű tokent, és átadja annak, akit választott; bármikor visszavonhatja. Egyéb kérésekkel írjon az ügyfélszolgálatnak.

Elveszítettem a tokent. Újra elküldenék?

Nem, mert a Heiwit nem tárolja. Hozzon létre újat, és vonja vissza a régit.

Lejár a token?

Csak ha nem használja: 60 nap hívás nélkül automatikusan inaktiválódik. Amíg használja, aktív marad.

Több rendszert is lekérdezhetek egyetlen tokennel?

Nem, minden token egy rendszerre érvényes. Több rendszerhez több token szükséges.

Az euróban megadott értékek megegyeznek a számlán szereplőkkel?

Nem. Ezek becslések, amelyeket az adott időszak nagykereskedelmi energiaárával (PUN) számolunk.

Mennyire mehetek vissza az időben?

A felügyelet által rögzített adatok kezdetéig. Óránkénti bontás esetén egy lekérdezés legfeljebb 400 napot fed le.

Működik a Home Assistanttal?

Igen, a RESTful integrációval: a konfigurációt a fenti példákban találja.

Hasznos linkek

• API-dokumentáció és a hozzáférhető adatok listája: ai-care.heiwit.com/report (bejelentkezés után: Scarica i dati del tuo impianto (Töltse le rendszere adatait) panel › Accesso via API (Hozzáférés API-n keresztül)).
• A hozzáférés engedélyezése és ügyfélszolgálat: ai-care.heiwit.com/login.
• Videós útmutató: Heiwit inverter: hogyan férhet hozzá adataihoz API-n keresztül.

Jogszabályi hivatkozások: Az Európai Parlament és a Tanács 2023. december 13-i (EU) 2023/2854 rendelete (Data Act), különösen a felhasználó adatokhoz való hozzáféréséről szóló 4. cikk és az adatok harmadik felekkel való megosztásáról szóló 5. cikk. A felhasználót megillető adatokhoz való hozzáférés ingyenes, a kérelmező jogosultságának ellenőrzését követően; az adatok felhasználó által megbízott harmadik fél rendelkezésére bocsátása a rendeletben előírt feltételek szerint történik. A műszaki információk az API 1. verziójára (/api/v1) vonatkoznak, 2026. október 5-i állapot szerint.

Az API az alábbi által gyűjtött adatokat olvassa: AI-Care, a Heiwit rendszerfelügyeleti platformja. A rendszer szíve aVirgo hibrid inverter, amelyhez társul a 10 kWh-s Heiwit nátrium-ion akkumulátor.