Jak uzyskać dostęp do danych falownika Heiwit przez API (Data Act)

Jak uzyskać dostęp do danych falownika Heiwit przez API

Dane swojej instalacji Heiwit możesz odczytywać także z zewnętrznego programu, przez API. Logujesz się do AI-Care, otwierasz Report › Scarica i dati del tuo impianto (Pobierz dane swojej instalacji) › Accesso via API (Dostęp przez API) i tworzysz token: to klucz, którego program używa, aby pobierać dane. Dostęp jest bezpłatny, tylko do odczytu, a każdy token obowiązuje dla jednej instalacji. To procedura, którą Heiwit udostępnia w celu realizacji dostępu do danych przewidzianego w europejskim Data Act (Rozporządzenie UE 2023/2854).

Film się nie wyświetla? Obejrzyj go na YouTube.

W filmie zobaczysz całą procedurę: włączenie dostępu, uwierzytelnienie tokenem i pierwsze zapytanie. Poniżej znajdziesz ją wyjaśnioną krok po kroku, wraz z listą dostępnych danych, limitami i kilkoma przykładami gotowymi do skopiowania.

Przede wszystkim: czy naprawdę potrzebujesz API?

Jeśli chcesz tylko mieć liczby w arkuszu Excel, to nie. Na stronie Report w AI-Care znajduje się sekcja Scarica i dati del tuo impianto: wybierasz okres i szczegółowość (godzina po godzinie, dzień po dniu lub miesiąc po miesiącu) i pobierasz plik Excel lub CSV. Nie trzeba niczego konfigurować.

API przydaje się, gdy chcesz, aby dane trafiały same do innego programu, bez ręcznego pobierania plików. Na przykład:

• system automatyki domowej, taki jak Home Assistant;
• arkusz Excel aktualizowany jednym kliknięciem;
• system zarządzania firmą, oprogramowanie doradcy energetycznego lub społeczności energetycznej;
• skrypt napisany przez Ciebie lub Twojego technika.

Czym jest API – w prostych słowach

API to adres internetowy przeznaczony dla programów, a nie dla ludzi. Ty otwierasz stronę i ją czytasz; program „wywołuje” adres i otrzymuje dane w uporządkowanym formacie, gotowe do użycia: JSON lub CSV.

Każde wywołanie zawiera token, czyli długi tajny klucz. Działa jak hasło, z dwiema różnicami: służy wyłącznie do odczytu danych i otwiera tylko jedną instalację.

Prawo do Twoich danych: Data Act

Data Act to europejskie rozporządzenie w sprawie danych (Rozporządzenie UE 2023/2854), stosowane od 12 września 2025 r. Dotyczy również produktów skomunikowanych, takich jak falownik z usługą monitoringu, i daje ich użytkownikom dwa prawa:

• uzyskać dostęp do danych generowanych podczas korzystania z produktu i je wykorzystywać (art. 4);
• do udostępnienia ich osobie trzeciej przez siebie upoważnionej, na przykład instalatorowi lub doradcy (art. 5).

Dlatego dostęp do danych, które Ci przysługują, jest bezpłatny. Najpierw Heiwit sprawdza, czy masz do tego prawo: dlatego token można utworzyć dopiero po zalogowaniu się do AI-Care na konto, z którym powiązana jest instalacja.

Czego potrzebujesz

• Konto w portalu Heiwit. AI-Care używa tych samych danych logowania co portal: e-mail lub nazwa użytkownika i hasło. Jeśli nie pamiętasz hasła, użyj opcji Odzyskaj hasło na stronie logowania.
• Instalacja powiązana z Twoim kontem. Jeśli po zalogowaniu nie widzisz swojej instalacji, poproś dział wsparcia o jej udostępnienie.
• Program, który potrafi wysyłać zapytania internetowe: Home Assistant, Excel, Python, polecenie curl lub oprogramowanie Twojego dostawcy.

Krok 1: utwórz token

1. Wejdź na ai-care.heiwit.com i zaloguj się.
2. Jeśli masz kilka instalacji, wybierz tę, która Cię interesuje.
3. Otwórz Report z menu.
4. Na dole strony otwórz sekcję Scarica i dati del tuo impianto , a następnie część Accesso via API.
5. Wpisz nazwę, która przypomni Ci, do czego służy token, na przykład „Home Assistant”, i kliknij Crea token.
6. Od razu skopiuj token i przechowuj go w bezpiecznym miejscu: jest wyświetlany tylko raz. Rozpoznasz go po tym, że zaczyna się od aic_.

W tej samej części znajdziesz listę aktywnych tokenów instalacji wraz z ostatnim użyciem, liczbą wywołań i datą, w której zostaną dezaktywowane. Przyciskiem Revoca natychmiast wyłączasz wybrany token.

Krok 2: wyślij pierwsze zapytanie

Wszystkie zapytania wysyła się na ten adres:

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

Token przesyła się w nagłówku (header) zapytania o nazwie Authorization, poprzedzony słowem Bearer i spacją:

Authorization: Bearer aic_IL_TUO_TOKEN

Do szybkiego testu wystarczy terminal z poleceniem curl, dostępnym już w systemach Windows 10 i 11, macOS i Linux. Zastąp aic_IL_TUO_TOKEN swoim tokenem:

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

W systemie Windows, w PowerShell, wpisz curl.exe zamiast curl.

Nie musisz wskazywać, którą instalację odczytać: określa to token. Odpowiedź wygląda podobnie do tej:

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

W tym przykładzie panele wytwarzają 3120 W: 1670 W trafia do domu, a 1450 W ładuje baterię, naładowaną w 64%. Z siecią nie ma żadnej wymiany.

Co możesz odczytać

API ma trzy adresy, wszystkie tylko do odczytu (zapytania GET):

/status: instalacja w tej chwili

/energy: dane historyczne

Przykład: dane dzień po dniu za wrzesień 2026, tylko energia i autokonsumpcja.

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 dodaje się do adresu po znaku zapytania, oddzielając je znakiem &:

Z granularity=hour jedno zapytanie obejmuje maksymalnie 400 dni: w przypadku dłuższych okresów wykonaj kilka zapytań. Przy day oraz month możesz pobrać całą historię za jednym razem.

Plik CSV używa przecinka jako separatora i kropki jako separatora dziesiętnego – to najpopularniejszy format dla programów. Aby otworzyć go w polskiej wersji Excela, dodaj &delimiter=semicolon&decimal=comma.

Grupy danych, które możesz pobrać za pomocą fields:

Każdy wiersz zaczyna się od daty (date), do której w widoku godzinowym dochodzi godzina (hour); w widoku miesięcznym jest miesiąc (month). Odpowiedź JSON z przykładu wygląda tak:

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

Pokazano tu tylko pierwsze wiersze: w data znajduje się wszystkie 30 dni (count).

/token: stan tokenu

Zwraca nazwę tokenu, instalację, datę utworzenia, ostatnie użycie, datę, w której token zostanie dezaktywowany, jeśli nie będziesz go używać (expires_at), liczbę dzisiejszych wywołań i limity. Przydaje się do sprawdzenia, czy wszystko działa. To wywołanie również wlicza się do limitu dziennego.

Jak aktualne są dane

• Stan bieżący (/status): falownik przesyła odczyt mniej więcej co 5 minut, a API zwraca ostatni otrzymany. API nie odpytuje falownika na żywo: odczytuje dane już zebrane przez system monitoringu, dzięki czemu Twoje wywołania nie obciążają instalacji.
• Dane historyczne (/energy): bieżąca godzina i bieżący dzień są niepełne i stopniowo rosną. Daty i godziny podawane są według czasu włoskiego.
• Jeśli falownik utraci połączenie z internetem, API i tak odpowiada ostatnim otrzymanym odczytem: sprawdź updated_at , aby ocenić, jak jest aktualny.
• Wartości w euro są szacunkowe, obliczone na podstawie hurtowej ceny energii (PUN) z danego okresu i według tej samej formuły co w kafelkach AI-Care. Nie są to kwoty z Twojego rachunku.

Zasady i limity tokenu

• Jeden token, jedna instalacja. Jeśli masz kilka instalacji, utwórz token dla każdej z nich.
• Tylko odczyt. Za pomocą tokenu nie można niczego zmienić.
• Do 5 aktywnych tokenów na instalację. Warto używać osobnego tokenu dla każdego programu: jeśli trzeba wyłączyć jeden, pozostałe nadal działają.
• 10 wywołań na minutę i 300 dziennie dla każdego tokenu. Licznik dzienny zeruje się o północy czasu włoskiego. Każda odpowiedź podaje limit dzienny w nagłówku X-Quota-Limit oraz liczbę wywołań pozostałych na dziś w X-Quota-Remaining.
• Brak stałej daty wygaśnięcia. Token dezaktywuje się automatycznie, jeśli nie jest używany przez 60 dni; każde wywołanie przesuwa termin wygaśnięcia.
• Natychmiastowe unieważnienie. Z Revocana stronie Report token natychmiast przestaje działać.

Jak często pobierać dane? Stan zmienia się mniej więcej co 5 minut, więc częstsze wywołania nie dają nowych danych. Jedno wywołanie co 5 minut to 288 wywołań dziennie: mieści się w limicie, ale zostawia wolnych tylko 12. Jeśli ten sam token jest Ci potrzebny także do innych celów, wybierz jedno wywołanie co 10 minut. Do danych historycznych wystarczy jedno wywołanie dziennie.

Jeśli coś nie działa

Gdy żądanie się nie powiedzie, API odpowiada kodem, skrótem (error) i komunikatem po włosku, który wyjaśnia, co poprawić. Na przykład:

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

Gotowe przykłady

Home Assistant

Dzięki integracji RESTful w Home Assistant możesz utworzyć czujniki odczytujące /status. W pliku secrets.yaml zapisz token, poprzedzony słowem Bearer:

heiwit_aicare: "Bearer aic_IL_TUO_TOKEN"

Następnie dodaj w 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

Z scan_interval: 600 Home Assistant wywołuje API co 10 minut: 144 wywołania dziennie. Pozostałe sumy z lifetime_kwh (oddawanie do sieci, pobór, akumulator) dodaje się tak jak czujnik „energia wyprodukowana” i można ich używać w panelu 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. W Excelu otwórz Dane › Z sieci Web i wybierz Zaawansowane.
2. Jako adres wklej:
   https://ai-care.heiwit.com/api/v1/energy?granularity=day&format=csv&delimiter=semicolon&decimal=comma
3. W nagłówkach żądania HTTP wpisz Authorization a obok Bearer aic_IL_TUO_TOKEN.
4. Jeśli Excel zapyta o sposób dostępu, wybierz Anonimowy: autoryzacja jest już w nagłówku.
5. Załaduj tabelę. Od tej chwili Odśwież wszystko pobiera ją ponownie z nowymi danymi.

Bez from oraz to otrzymujesz zawsze ostatnie 30 dni. Uwaga: token pozostaje zapisany w pliku, a każdy, kto otrzyma plik, może odczytać dane instalacji.

Dla instalatorów i firm

• Jeden token na instalację. Na głównym koncie instalatora widzisz w AI-Care obsługiwane instalacje i dla każdej z nich możesz utworzyć token na stronie Report. Limity i wygaśnięcie dotyczą każdego tokenu osobno: przy 40 instalacjach masz 40 tokenów, każdy z własnymi 300 wywołaniami dziennie.
• Konta agentów nie widzą sekcji Accesso via API (Dostęp przez API): potrzebne jest główne konto instalatora.
• Dane należą do klienta. Używaj ich do usług uzgodnionych z klientem. Klient widzi na swojej stronie Report wszystkie aktywne tokeny swojej instalacji, także utworzone przez Ciebie, wraz z nazwą i ostatnim użyciem, i może je unieważnić. Nadawaj tokenom jasne nazwy, na przykład „Serwis Rossi Impianti”.
• Jeśli klient chce powierzyć Ci swoje dane (art. 5 Data Act), najprostszym rozwiązaniem jest, aby sam utworzył dedykowany token i Ci go przekazał. Może go unieważnić po zakończeniu współpracy.

To samo dotyczy firm programistycznych, doradców energetycznych i społeczności energetycznych: łączą się za pomocą jednego tokenu na instalację, który właściciel tworzy i im przekazuje.

Bezpieczeństwo: czego to API nie robi

• Nie udostępnia danych logowania administratora falownika.
• Nie zmienia oprogramowania układowego, parametrów elektrycznych ani ustawień zabezpieczeń: tylko odczytuje.
• Token nie otwiera Twojego konta AI-Care i nie daje dostępu do innych instalacji.

Mimo to traktuj token jak hasło: nie publikuj go w internecie, nie zostawiaj w udostępnianych plikach, nie wysyłaj na czacie. Jeśli obawiasz się, że ktoś go zobaczył, unieważnij go i utwórz nowy. Heiwit przechowuje tylko odcisk (hash) tokenu, a nie sam token: dlatego nikt, nawet dział wsparcia, nie może go ponownie przesłać. Komunikacja z API jest szyfrowana (HTTPS).

Często zadawane pytania

Ile to kosztuje?

Nic. Dostęp do przysługujących Ci danych jest bezpłatny.

Czy przez API mogę zmieniać ustawienia falownika?

Nie. API działa tylko w trybie odczytu: nie ingeruje w oprogramowanie układowe, parametry elektryczne ani zabezpieczenia.

Czy mogę przekazać swoje dane instalatorowi lub innej firmie?

Tak. Data Act pozwala udostępnić je wskazanemu przez Ciebie podmiotowi trzeciemu. W praktyce tworzysz token o rozpoznawalnej nazwie i przekazujesz go wybranej osobie lub firmie; możesz go unieważnić w dowolnym momencie. W przypadku innych próśb napisz do działu wsparcia.

Zgubiłem token. Czy możecie go ponownie przesłać?

Nie, ponieważ Heiwit go nie przechowuje. Utwórz nowy i unieważnij stary.

Czy token wygasa?

Tylko wtedy, gdy go nie używasz: po 60 dniach bez wywołań dezaktywuje się automatycznie. Dopóki go używasz, pozostaje aktywny.

Czy jednym tokenem mogę odczytywać dane z kilku instalacji?

Nie, każdy token dotyczy jednej instalacji. Dla kilku instalacji potrzeba kilku tokenów.

Czy wartości w euro to kwoty z rachunku za energię?

Nie. Są to szacunki obliczone na podstawie hurtowej ceny energii (PUN) z danego okresu.

Jak daleko wstecz mogę sięgnąć?

Do początku danych zarejestrowanych przez system monitoringu. Przy szczegółowości godzinowej każde zapytanie obejmuje maksymalnie 400 dni.

Czy to działa z Home Assistant?

Tak, przez integrację RESTful: konfigurację znajdziesz w przykładach powyżej.

Przydatne linki

• Dokumentacja API i lista dostępnych danych: ai-care.heiwit.com/report (po zalogowaniu: sekcja Scarica i dati del tuo impianto (Pobierz dane swojej instalacji) › Accesso via API (Dostęp przez API)).
• Włączenie dostępu i pomoc techniczna: ai-care.heiwit.com/login.
• Poradnik wideo: Falownik Heiwit: jak uzyskać dostęp do swoich danych przez API.

Podstawa prawna: Rozporządzenie Parlamentu Europejskiego i Rady (UE) 2023/2854 z dnia 13 grudnia 2023 r. (Data Act), w szczególności art. 4 dotyczący dostępu użytkownika do danych oraz art. 5 dotyczący ich udostępniania osobom trzecim. Dostęp do danych przysługujących użytkownikowi jest bezpłatny, po weryfikacji uprawnień wnioskodawcy; udostępnienie danych osobie trzeciej wskazanej przez użytkownika odbywa się na warunkach określonych w rozporządzeniu. Informacje techniczne dotyczą wersji 1 API (/api/v1) według stanu na 5 października 2026 r.

API odczytuje dane zbierane przez AI-Care, platformę Heiwit do monitorowania instalacji. Sercem instalacji jestfalownik hybrydowy Virgo, współpracujący z bateria sodowo-jonowa Heiwit o pojemności 10 kWh.