Jak získat přístup k datům vašeho střídače Heiwit přes API (Data Act)

Jak získat přístup k datům vašeho střídače Heiwit přes API

Data své instalace Heiwit můžete číst i z externího programu, přes API. Přihlásíte se do AI-Care, otevřete Report › Scarica i dati del tuo impianto (Stáhněte si data své instalace) › Accesso via API (Přístup přes API) a vytvoříte token: je to klíč, kterým si program o data žádá. Přístup je zdarma, pouze pro čtení a každý token platí jen pro jednu instalaci. Jde o postup, který Heiwit poskytuje k uplatnění přístupu k datům podle evropského Data Act (nařízení EU 2023/2854).

Video se nezobrazuje? Podívejte se na YouTube.

Ve videu uvidíte celý postup: povolení přístupu, ověření tokenem a první požadavek. Níže jej najdete vysvětlený krok za krokem, se seznamem dostupných dat, limity a několika příklady připravenými ke zkopírování.

Především: opravdu potřebujete API?

Pokud chcete jen čísla v tabulce Excel, pak ne. Na stránce Report v AI-Care je pole Scarica i dati del tuo impianto: zvolíte období a podrobnost (po hodinách, po dnech nebo po měsících) a stáhnete soubor Excel nebo CSV. Není třeba nic nastavovat.

API se hodí, když chcete, aby data přicházela automaticky do jiného programu, bez ručního stahování souborů. Například:

• systém chytré domácnosti jako Home Assistant;
• tabulka Excel, která se aktualizuje jedním kliknutím;
• podnikový informační systém, software energetického konzultanta nebo energetického společenství;
• skript napsaný vámi nebo vaším technikem.

Co je API, jednoduše řečeno

API je webová adresa určená pro programy místo lidí. Vy otevřete stránku a čtete ji; program adresu „zavolá“ a obdrží data v uspořádaném formátu připraveném k použití: JSON nebo CSV.

Každé volání s sebou nese token, dlouhý tajný klíč. Funguje jako heslo, se dvěma rozdíly: slouží jen ke čtení dat a otevírá jen jednu instalaci.

Právo na vaše data: Data Act

Data Act je evropské nařízení o datech (nařízení EU 2023/2854) a použije se od 12. září 2025. Týká se i propojených produktů, jako je střídač se svou monitorovací službou, a jejich uživatelům dává dvě práva:

• získat přístup k datům generovaným používáním produktu a využívat je (článek 4);
• nechat je zpřístupnit třetí straně kterou pověří, například instalatérovi nebo konzultantovi (článek 5).

Proto je přístup k datům, na která máte nárok, zdarma. Heiwit nejprve ověří, že na ně máte právo: proto lze token vytvořit jen po přihlášení do AI-Care účtem, ke kterému je instalace přiřazena.

Co potřebujete

• Účet na portálu Heiwit. AI-Care používá stejné přihlašovací údaje jako portál: e-mail nebo uživatelské jméno a heslo. Pokud si heslo nepamatujete, použijte Obnovit heslo na přihlašovací stránce.
• Instalace přiřazená k vašemu účtu. Pokud se přihlásíte a svou instalaci nevidíte, požádejte podporu o její zpřístupnění.
• Program, který umí posílat webové požadavky: Home Assistant, Excel, Python, příkaz curl nebo software vašeho dodavatele.

Krok 1: vytvořte token

1. Přejděte na ai-care.heiwit.com a přihlaste se.
2. Pokud máte více instalací, vyberte tu, která vás zajímá.
3. Otevřete Report z nabídky.
4. V dolní části stránky otevřete pole Scarica i dati del tuo impianto a poté sekci Accesso via API.
5. Zadejte název, který vám připomene, k čemu token slouží, například „Home Assistant“, a stiskněte Crea token.
6. Token ihned zkopírujte a uložte jej na bezpečné místo: zobrazí se jen jednou. Poznáte jej podle toho, že začíná aic_.

Ve stejné sekci najdete seznam aktivních tokenů instalace s posledním použitím, počtem volání a datem, kdy se deaktivují. Tlačítkem Revoca kterýkoli okamžitě vypnete.

Krok 2: odešlete první požadavek

Všechny požadavky vycházejí z této adresy:

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

Token se posílá v hlavičce (header) požadavku s názvem Authorization, před ním slovo Bearer a mezera:

Authorization: Bearer aic_IL_TUO_TOKEN

Pro rychlý test stačí terminál s příkazem curl, který je již součástí Windows 10 a 11, macOS a Linuxu. Nahraďte aic_IL_TUO_TOKEN svým tokenem:

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

Ve Windows v PowerShellu napište curl.exe místo curl.

Nemusíte uvádět, kterou instalaci číst: určuje to token. Odpověď vypadá přibližně takto:

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

V tomto příkladu panely vyrábějí 3 120 W: 1 670 W jde do domu a 1 450 W nabíjí baterii, která je na 64 %. Se sítí se nic nevyměňuje.

Co můžete číst

API má tři adresy, všechny pouze pro čtení (požadavky GET):

/status: instalace právě teď

/energy: historie

Příklad: data po dnech za září 2026, pouze energie a vlastní spotřeba.

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"

Parametry se přidávají k adrese za otazník a oddělují se znakem &:

S granularity=hour jeden požadavek pokrývá nejvýše 400 dní: pro delší období zadejte více požadavků. S day a month si můžete vyžádat celou historii najednou.

CSV používá čárku jako oddělovač a tečku pro desetinná místa, což je pro programy nejběžnější formát. Pro otevření v Excelu s italským nastavením přidejte &delimiter=semicolon&decimal=comma.

Skupiny dat, které si můžete vyžádat pomocí fields:

Každý řádek začíná datem (date), k němuž se v hodinovém rozlišení přidává hodina (hour); v měsíčním rozlišení je uveden měsíc (month). Odpověď JSON z příkladu vypadá takto:

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

Zde jsou zobrazeny jen první řádky: v data je všech 30 dní (count).

/token: stav tokenu

Vrací název tokenu, elektrárnu, datum vytvoření, poslední použití, datum, kdy se deaktivuje, pokud jej nebudete používat (expires_at), dnešní počet volání a limity. Hodí se pro kontrolu, že vše funguje. I toto volání se započítává do denního limitu.

Jak aktuální jsou data

• Aktuální stav (/status): střídač odesílá odečet přibližně každých 5 minut a API vrací ten poslední přijatý. Nedotazuje se střídače v reálném čase: čte data již shromážděná monitoringem, takže vaše volání elektrárnu nezatěžují.
• Historie (/energy): probíhající hodina a den jsou neúplné a postupně narůstají. Data a časy jsou v italském čase.
• Pokud střídač ztratí připojení k internetu, API přesto odpoví posledním přijatým odečtem: podívejte se na updated_at a zjistěte, jak je čerstvý.
• Hodnoty v eurech jsou odhady, vypočtené z velkoobchodní ceny energie (PUN) za dané období a stejným vzorcem jako přehledy v AI-Care. Nejde o váš účet za elektřinu.

Pravidla a limity tokenu

• Jeden token, jedna elektrárna. Pokud máte více elektráren, vytvořte token pro každou z nich.
• Pouze čtení. Pomocí tokenu nelze nic měnit.
• Až 5 aktivních tokenů na jednu instalaci. Vyplatí se používat jeden pro každý program: pokud některý musíte vypnout, ostatní fungují dál.
• 10 volání za minutu a 300 za den pro každý token. Denní počítadlo se nuluje o půlnoci italského času. Každá odpověď uvádí denní limit v hlavičce X-Quota-Limit a počet zbývajících dnešních volání v X-Quota-Remaining.
• Žádná pevná platnost. Token se sám deaktivuje, pokud zůstane nepoužitý 60 dní; každé volání posouvá konec platnosti dál.
• Okamžité zrušení. S Revocana stránce Report token okamžitě přestane fungovat.

Jak často se na data ptát? Stav se mění přibližně každých 5 minut, takže častější volání nepřinese nová data. Jedno volání každých 5 minut znamená 288 volání denně: vejde se do limitu, ale volných zůstane jen 12. Pokud stejný token potřebujete i na něco jiného, zvolte jedno volání každých 10 minut. Pro historii stačí jedno volání denně.

Když něco nefunguje

Když požadavek neuspěje, API odpoví kódem, zkratkou (error) a zprávou v italštině, která vysvětluje, co opravit. Například:

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

Hotové příklady

Home Assistant

Pomocí integrace RESTful v Home Assistant můžete vytvořit senzory, které čtou /status. Do souboru secrets.yaml uložte token se slovem Bearer na začátku:

heiwit_aicare: "Bearer aic_IL_TUO_TOKEN"

Poté přidejte do 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

S scan_interval: 600 Home Assistant volá API každých 10 minut: 144 volání denně. Ostatní součty z lifetime_kwh (dodávka do sítě, odběr ze sítě, baterie) se přidávají stejně jako senzor „vyrobená energie“ a lze je použít v řídicím panelu 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. V Excelu otevřete Data › Z webu a zvolte Upřesnit.
2. Jako adresu vložte:
   https://ai-care.heiwit.com/api/v1/energy?granularity=day&format=csv&delimiter=semicolon&decimal=comma
3. Do hlaviček požadavku HTTP napište Authorization a vedle Bearer aic_IL_TUO_TOKEN.
4. Pokud se Excel zeptá na způsob přístupu, zvolte Anonymní: autorizace je již v hlavičce.
5. Načtěte tabulku. Od té chvíle ji Aktualizovat vše znovu načte s novými daty.

Bez from a to dostanete vždy posledních 30 dní. Pozor: token zůstává uložený v souboru a kdokoli soubor obdrží, může číst data instalace.

Pro instalatéry a firmy

• Jeden token na instalaci. S hlavním účtem instalatéra vidíte v AI-Care instalace, které spravujete, a pro každou můžete na stránce Report vytvořit token. Limity a platnost platí pro každý token zvlášť: se 40 instalacemi máte 40 tokenů, každý s vlastními 300 voláními denně.
• Účty agentů nevidí sekci Accesso via API (Přístup přes API): je potřeba hlavní účet instalatéra.
• Data patří zákazníkovi. Používejte je pro služby s ním dohodnuté. Zákazník na své stránce Report vidí všechny aktivní tokeny ke své instalaci, včetně těch, které jste vytvořili vy, s názvem a posledním použitím, a může je zrušit. Dávejte tokenům jasné názvy, například „Údržba Rossi Impianti“.
• Pokud vám zákazník chce svěřit svá data (článek 5 nařízení Data Act), nejjednodušší je, aby sám vytvořil vyhrazený token a předal vám ho. Po skončení spolupráce ho může zrušit.

Totéž platí pro softwarové firmy, energetické konzultanty a energetická společenství: připojují se jedním tokenem na instalaci, který jim vlastník vytvoří a předá.

Bezpečnost: co toto API nedělá

• Nevydává administrátorské přihlašovací údaje ke střídači.
• Nemění firmware, elektrické parametry ani nastavení ochran: pouze čte.
• Token neotevírá váš účet AI-Care a nedává přístup k jiným instalacím.

Přesto s tokenem zacházejte jako s heslem: nezveřejňujte ho online, nenechávejte ho ve sdílených souborech, neposílejte ho v chatu. Pokud se obáváte, že ho někdo viděl, zrušte ho a vytvořte nový. Heiwit uchovává pouze otisk (hash) tokenu, nikoli token samotný: proto vám ho nikdo, ani podpora, nemůže znovu zaslat. Komunikace s API je šifrovaná (HTTPS).

Často kladené otázky

Kolik to stojí?

Nic. Přístup k datům, na která máte nárok, je zdarma.

Mohu přes API měnit nastavení střídače?

Ne. API je pouze pro čtení: nezasahuje do firmwaru, elektrických parametrů ani ochran.

Mohu svá data poskytnout instalatérovi nebo jiné firmě?

Ano. Data Act vám umožňuje nechat je zpřístupnit třetí straně, kterou pověříte. V praxi vytvoříte token s rozpoznatelným názvem a předáte ho zvolenému subjektu; kdykoli ho můžete zrušit. S jinými požadavky se obraťte na podporu.

Ztratil(a) jsem token. Můžete mi ho poslat znovu?

Ne, protože ho Heiwit neuchovává. Vytvořte nový a starý zrušte.

Vyprší platnost tokenu?

Pouze pokud ho nepoužíváte: po 60 dnech bez volání se sám deaktivuje. Dokud ho používáte, zůstává aktivní.

Mohu jedním tokenem číst data z více instalací?

Ne, každý token platí pro jednu instalaci. Pro více instalací potřebujete více tokenů.

Odpovídají hodnoty v eurech vyúčtování?

Ne. Jde o odhady vypočtené z velkoobchodní ceny energie (PUN) v daném období.

Jak daleko do minulosti mohu jít?

Až k začátku dat zaznamenaných monitoringem. U hodinového rozlišení pokrývá každý požadavek nejvýše 400 dní.

Funguje to s Home Assistant?

Ano, s integrací RESTful: konfiguraci najdete v příkladech výše.

Užitečné odkazy

• Dokumentace API a seznam dostupných dat: ai-care.heiwit.com/report (po přihlášení v rámečku Scarica i dati del tuo impianto (Stáhněte si data své instalace) › Accesso via API (Přístup přes API)).
• Povolení přístupu a podpora: ai-care.heiwit.com/login.
• Videonávod: Střídač Heiwit: jak získat přístup ke svým datům přes API.

Právní předpisy: Nařízení Evropského parlamentu a Rady (EU) 2023/2854 ze dne 13. prosince 2023 (akt o datech), zejména článek 4 o přístupu uživatele k datům a článek 5 o jejich sdílení se třetími stranami. Přístup k datům, na která má uživatel nárok, je bezplatný, po ověření oprávnění žadatele; zpřístupnění dat třetí straně pověřené uživatelem probíhá za podmínek stanovených nařízením. Technické údaje se vztahují k verzi 1 API (/api/v1) ke dni 5. října 2026.

API čte data shromážděná platformou AI-Care, platformou Heiwit pro monitoring instalací. Srdcem instalace jehybridní střídač Virgo, v kombinaci s sodíkovo-iontová baterie Heiwit o kapacitě 10 kWh.