So greifen Sie per API auf die Daten Ihres Heiwit-Wechselrichters zu (Data Act)

So greifen Sie per API auf die Daten Ihres Heiwit-Wechselrichters zu

Sie können die Daten Ihrer Heiwit-Anlage auch aus einem externen Programm per API auslesen. Sie melden sich bei AI-Care an, öffnen Report › Scarica i dati del tuo impianto (Daten Ihrer Anlage herunterladen) › Accesso via API (Zugriff per API) und erstellen einen Token: Das ist der Schlüssel, mit dem das Programm die Daten abfragt. Der Zugriff ist kostenlos, nur lesend, und jeder Token gilt für genau eine Anlage. Dies ist das Verfahren, das Heiwit bereitstellt, damit Sie den im europäischen Data Act (Verordnung (EU) 2023/2854) vorgesehenen Datenzugang wahrnehmen können.

Das Video wird nicht angezeigt? Auf YouTube ansehen.

Im Video sehen Sie den gesamten Ablauf: Freischaltung des Zugriffs, Authentifizierung mit dem Token und erste Anfrage. Unten finden Sie alles Schritt für Schritt erklärt, mit der Liste der verfügbaren Daten, den Grenzen und einigen Beispielen zum Kopieren.

Vorab: Brauchen Sie die API wirklich?

Wenn Sie nur die Zahlen in einer Excel-Tabelle möchten, nein. Auf der Seite Report von AI-Care gibt es den Bereich Scarica i dati del tuo impianto: Wählen Sie den Zeitraum und die Auflösung (stündlich, täglich oder monatlich) und laden Sie eine Excel- oder CSV-Datei herunter. Eine Konfiguration ist nicht nötig.

Die API brauchen Sie, wenn die Daten automatisch in ein anderes Programm gelangen sollen, ohne Dateien manuell herunterzuladen. Zum Beispiel:

• ein Smart-Home-System wie Home Assistant;
• eine Excel-Tabelle, die sich per Klick aktualisiert;
• die Unternehmenssoftware eines Betriebs, die Software eines Energieberaters oder einer Energiegemeinschaft;
• ein Skript, das Sie oder Ihr Techniker geschrieben haben.

Was ist eine API – einfach erklärt

Eine API ist eine Webadresse, die für Programme statt für Menschen gedacht ist. Sie öffnen eine Seite und lesen sie; ein Programm „ruft“ die Adresse auf und erhält die Daten in einem geordneten, direkt nutzbaren Format: JSON oder CSV.

Jeder Aufruf enthält einen Token, einen langen geheimen Schlüssel. Er funktioniert wie ein Passwort, mit zwei Unterschieden: Er dient nur zum Lesen der Daten und öffnet nur eine einzige Anlage.

Das Recht auf Ihre Daten: der Data Act

Der Data Act ist die europäische Datenverordnung (Verordnung (EU) 2023/2854) und gilt seit dem 12. September 2025. Er betrifft auch vernetzte Produkte wie den Wechselrichter mit seinem Monitoring-Dienst und gibt den Nutzern zwei Rechte:

• auf die Daten zuzugreifen , die bei der Nutzung des Produkts entstehen, und sie zu verwenden (Artikel 4);
• sie einem Dritten bereitstellen zu lassen, den der Nutzer beauftragt, zum Beispiel dem Installateur oder einem Berater (Artikel 5).

Deshalb ist der Zugriff auf die Ihnen zustehenden Daten kostenlos. Zuvor prüft Heiwit, ob Sie dazu berechtigt sind: Deshalb lässt sich der Token erst erstellen, nachdem Sie sich mit dem Konto, dem die Anlage zugeordnet ist, bei AI-Care angemeldet haben.

Was Sie brauchen

• Das Konto für das Heiwit-Portal. AI-Care verwendet dieselben Zugangsdaten wie das Portal: E-Mail oder Benutzername und Passwort. Wenn Sie Ihr Passwort vergessen haben, nutzen Sie Passwort wiederherstellen auf der Anmeldeseite.
• Die Ihrem Konto zugeordnete Anlage. Wenn Sie sich anmelden und Ihre Anlage nicht sehen, bitten Sie den Kundendienst um Freischaltung.
• Ein Programm, das Webanfragen senden kann: Home Assistant, Excel, Python, der Befehl curl oder die Software Ihres Anbieters.

Schritt 1: Token erstellen

1. Gehen Sie auf ai-care.heiwit.com und melden Sie sich an.
2. Wenn Sie mehrere Anlagen haben, wählen Sie die gewünschte aus.
3. Öffnen Sie Report im Menü.
4. Öffnen Sie unten auf der Seite den Bereich Scarica i dati del tuo impianto und dann den Abschnitt Accesso via API.
5. Geben Sie einen Namen ein, der Sie an den Zweck des Tokens erinnert, zum Beispiel „Home Assistant“, und klicken Sie auf Crea token.
6. Kopieren Sie den Token sofort und bewahren Sie ihn sicher auf: Er wird nur einmal angezeigt. Sie erkennen ihn daran, dass er beginnt mit aic_.

Im selben Abschnitt finden Sie die Liste der aktiven Tokens der Anlage mit letzter Nutzung, Anzahl der Aufrufe und dem Datum, an dem sie deaktiviert werden. Mit Revoca deaktivieren Sie einen Token sofort.

Schritt 2: Erste Anfrage senden

Alle Anfragen gehen an diese Adresse:

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

Der Token wird in einem Header der Anfrage gesendet, der heißt Authorization, mit vorangestelltem Wort Bearer und einem Leerzeichen:

Authorization: Bearer aic_IL_TUO_TOKEN

Für einen schnellen Test genügt das Terminal mit dem Befehl curl, der unter Windows 10 und 11, macOS und Linux bereits vorhanden ist. Ersetzen Sie aic_IHR_TOKEN durch Ihren Token:

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

Unter Windows schreiben Sie in PowerShell curl.exe statt curl.

Sie müssen nicht angeben, welche Anlage gelesen werden soll: Das legt der Token fest. Die Antwort sieht etwa so aus:

{
  "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 diesem Beispiel erzeugen die Module 3.120 W: 1.670 W gehen ins Haus und 1.450 W laden den Akku, der bei 64 % steht. Mit dem Netz wird nichts ausgetauscht.

Was Sie auslesen können

Die API hat drei Adressen, alle nur lesend (GET-Anfragen):

/status: die Anlage jetzt

/energy: der Verlauf

Beispiel: die Tageswerte für September 2026, nur Energie und Eigenverbrauch.

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"

Die Parameter werden nach dem Fragezeichen an die Adresse angehängt, getrennt durch &:

Mit granularity=hour deckt eine Anfrage höchstens 400 Tage ab: Für längere Zeiträume stellen Sie mehrere Anfragen. Mit day und month können Sie den gesamten Verlauf auf einmal abrufen.

Die CSV-Datei verwendet das Komma als Trennzeichen und den Punkt als Dezimalzeichen, das für Programme gängigste Format. Um sie mit einem deutschsprachigen Excel zu öffnen, fügen Sie Folgendes hinzu: &delimiter=semicolon&decimal=comma.

Die Datengruppen, die Sie abrufen können mit fields:

Jede Zeile beginnt mit dem Datum (date), bei stündlicher Auflösung ergänzt um die Uhrzeit (hour); bei monatlicher Auflösung steht dort der Monat (month). Die JSON-Antwort des Beispiels sieht so aus:

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

Hier sind nur die ersten Zeilen dargestellt: In data sind alle 30 Tage enthalten (count).

/token: der Status des Tokens

Liefert den Namen des Tokens, die Anlage, das Erstellungsdatum, die letzte Nutzung, das Datum, an dem er bei Nichtnutzung deaktiviert wird (expires_at), die heutigen Abrufe und die Limits. Nützlich, um zu prüfen, ob alles funktioniert. Auch dieser Abruf zählt zum Tageslimit.

Wie aktuell die Daten sind

• Aktueller Status (/status): Der Wechselrichter sendet etwa alle 5 Minuten einen Messwert, und die API liefert den zuletzt eingegangenen. Sie fragt den Wechselrichter nicht live ab, sondern liest die bereits vom Monitoring erfassten Daten – Ihre Abrufe belasten die Anlage also nicht.
• Verlauf (/energy): Die laufende Stunde und der laufende Tag sind unvollständig und wachsen fortlaufend an. Datum und Uhrzeit entsprechen italienischer Zeit.
• Wenn der Wechselrichter die Internetverbindung verliert, antwortet die API trotzdem mit dem zuletzt eingegangenen Messwert: Prüfen Sie updated_at , um zu sehen, wie aktuell er ist.
• Die Euro-Werte sind Schätzungen, berechnet mit dem Großhandelsstrompreis (PUN) des Zeitraums und mit derselben Formel wie die Kacheln in AI-Care. Sie entsprechen nicht Ihrer Stromrechnung.

Regeln und Limits des Tokens

• Ein Token, eine Anlage. Wenn Sie mehrere Anlagen haben, erstellen Sie für jede einen Token.
• Nur Lesezugriff. Mit dem Token lässt sich nichts ändern.
• Bis zu 5 aktive Tokens pro Anlage. Am besten verwenden Sie für jedes Programm einen eigenen: Wenn Sie einen deaktivieren müssen, funktionieren die anderen weiter.
• 10 Abrufe pro Minute und 300 pro Tag für jeden Token. Der Tageszähler wird um Mitternacht italienischer Zeit zurückgesetzt. Jede Antwort enthält das Tageslimit im Header X-Quota-Limit und die heute noch verbleibenden Abrufe in X-Quota-Remaining.
• Kein festes Ablaufdatum. Der Token deaktiviert sich automatisch, wenn er 60 Tage lang nicht verwendet wird; jeder Abruf verschiebt das Ablaufdatum nach hinten.
• Sofortiger Widerruf. Mit Revocaauf der Seite Report funktioniert der Token sofort nicht mehr.

Wie oft sollten Daten abgerufen werden? Der Status ändert sich etwa alle 5 Minuten, häufigere Abrufe liefern also keine neuen Daten. Ein Abruf alle 5 Minuten ergibt 288 Abrufe pro Tag: Das liegt innerhalb des Limits, lässt aber nur 12 frei. Wenn Sie denselben Token auch für anderes benötigen, wählen Sie einen Abruf alle 10 Minuten. Für die Verlaufsdaten genügt ein Abruf pro Tag.

Wenn etwas nicht funktioniert

Wenn eine Anfrage fehlschlägt, antwortet die API mit einem Code, einem Kürzel (error) und einer Meldung auf Italienisch, die erklärt, was zu korrigieren ist. Zum Beispiel:

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

Fertige Beispiele

Home Assistant

Mit der RESTful-Integration von Home Assistant können Sie Sensoren erstellen, die Folgendes auslesen: /status. In der Datei secrets.yaml speichern Sie den Token, mit dem Wort Bearer davor:

heiwit_aicare: "Bearer aic_IL_TUO_TOKEN"

Fügen Sie dann hinzu 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

Mit scan_interval: 600 Home Assistant ruft die API alle 10 Minuten ab: 144 Abrufe pro Tag. Die weiteren Summen von lifetime_kwh (Einspeisung, Netzbezug, Akku) werden wie der Sensor „erzeugte Energie“ hinzugefügt und können im Energie-Dashboard verwendet werden.

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. Öffnen Sie in Excel Daten › Aus dem Web und wählen Sie Erweitert.
2. Fügen Sie als Adresse ein:
   https://ai-care.heiwit.com/api/v1/energy?granularity=day&format=csv&delimiter=semicolon&decimal=comma
3. Tragen Sie in den HTTP-Anforderungsheadern Authorization ein und daneben Bearer aic_IHR_TOKEN.
4. Wenn Excel nach der Zugriffsart fragt, wählen Sie Anonym: Die Autorisierung steht bereits im Header.
5. Laden Sie die Tabelle. Ab dann lädt Alle aktualisieren sie mit den neuen Daten erneut.

Ohne from und to erhalten Sie immer die letzten 30 Tage. Achtung: Der Token bleibt in der Datei gespeichert, und wer die Datei erhält, kann die Daten der Anlage lesen.

Für Installateure und Unternehmen

• Ein Token pro Anlage. Mit dem Hauptkonto des Installateurs sehen Sie in AI-Care die von Ihnen betreuten Anlagen und können für jede auf der Seite Report einen Token erstellen. Limits und Ablauf gelten pro Token: Bei 40 Anlagen haben Sie 40 Tokens, jeder mit seinen eigenen 300 Abrufen pro Tag.
• Agentenkonten sehen den Bereich Accesso via API (API-Zugriff) nicht: Dafür ist das Hauptkonto des Installateurs erforderlich.
• Die Daten gehören dem Kunden. Verwenden Sie sie für die mit ihm vereinbarten Leistungen. Der Kunde sieht auf seiner Seite Report alle aktiven Tokens seiner Anlage, auch die von Ihnen erstellten, mit Namen und letzter Nutzung, und kann sie widerrufen. Geben Sie den Tokens eindeutige Namen, zum Beispiel „Wartung Rossi Impianti“.
• Wenn ein Kunde Ihnen seine Daten anvertrauen möchte (Artikel 5 des Data Act), ist der einfachste Weg, dass er selbst einen eigenen Token erstellt und Ihnen übergibt. Er kann ihn widerrufen, wenn die Geschäftsbeziehung endet.

Dasselbe gilt für Softwarehäuser, Energieberater und Energiegemeinschaften: Sie verbinden sich mit einem Token pro Anlage, den der Inhaber erstellt und ihnen übergibt.

Sicherheit: Was diese API nicht tut

• Sie gibt keine Administrator-Zugangsdaten des Wechselrichters heraus.
• Sie ändert weder Firmware noch elektrische Parameter oder Schutzeinstellungen: Sie liest nur.
• Der Token öffnet nicht Ihr AI-Care-Konto und gewährt keinen Zugriff auf andere Anlagen.

Behandeln Sie den Token dennoch wie ein Passwort: Veröffentlichen Sie ihn nicht online, lassen Sie ihn nicht in geteilten Dateien und senden Sie ihn nicht per Chat. Wenn Sie befürchten, dass jemand ihn gesehen hat, widerrufen Sie ihn und erstellen Sie einen neuen. Heiwit speichert nur einen Fingerabdruck (Hash) des Tokens, nicht den Token selbst: Deshalb kann ihn Ihnen niemand, auch nicht der Support, erneut zusenden. Die Kommunikation mit der API ist verschlüsselt (HTTPS).

Häufig gestellte Fragen

Was kostet das?

Nichts. Der Zugriff auf die Ihnen zustehenden Daten ist kostenlos.

Kann ich mit der API die Einstellungen des Wechselrichters ändern?

Nein. Die API ist schreibgeschützt: Sie greift nicht in Firmware, elektrische Parameter oder Schutzfunktionen ein.

Kann ich meine Daten an meinen Installateur oder ein anderes Unternehmen weitergeben?

Ja. Der Data Act erlaubt es Ihnen, sie einem von Ihnen beauftragten Dritten zur Verfügung stellen zu lassen. In der Praxis erstellen Sie einen Token mit einem erkennbaren Namen und übergeben ihn an die Person Ihrer Wahl; Sie können ihn jederzeit widerrufen. Für andere Anfragen wenden Sie sich an den Support.

Ich habe den Token verloren. Können Sie ihn mir erneut zusenden?

Nein, denn Heiwit speichert ihn nicht. Erstellen Sie einen neuen und widerrufen Sie den alten.

Läuft der Token ab?

Nur wenn Sie ihn nicht nutzen: Nach 60 Tagen ohne Aufrufe wird er automatisch deaktiviert. Solange Sie ihn nutzen, bleibt er aktiv.

Kann ich mit einem einzigen Token mehrere Anlagen auslesen?

Nein, jeder Token gilt für eine Anlage. Für mehrere Anlagen benötigen Sie mehrere Token.

Entsprechen die Euro-Werte denen der Stromrechnung?

Nein. Es handelt sich um Schätzungen, die mit dem Großhandelsstrompreis (PUN) des jeweiligen Zeitraums berechnet werden.

Wie weit kann ich in der Zeit zurückgehen?

Bis zum Beginn der vom Monitoring aufgezeichneten Daten. Bei stündlicher Auflösung umfasst jede Anfrage maximal 400 Tage.

Funktioniert es mit Home Assistant?

Ja, mit der RESTful-Integration: Die Konfiguration finden Sie in den Beispielen oben.

Nützliche Links

• API-Dokumentation und Liste der zugänglichen Daten: ai-care.heiwit.com/report (nach der Anmeldung, Bereich „Scarica i dati del tuo impianto“ (Daten Ihrer Anlage herunterladen) › „Accesso via API“ (Zugriff über API)).
• Freischaltung des Zugriffs und Support: ai-care.heiwit.com/login.
• Video-Anleitung: Heiwit-Wechselrichter: So greifen Sie per API auf Ihre Daten zu.

Rechtsgrundlagen: Verordnung (EU) 2023/2854 des Europäischen Parlaments und des Rates vom 13. Dezember 2023 (Data Act), insbesondere Artikel 4 über den Zugang des Nutzers zu den Daten und Artikel 5 über deren Weitergabe an Dritte. Der Zugang zu den dem Nutzer zustehenden Daten ist kostenlos, nach Prüfung der Berechtigung des Antragstellers; die Bereitstellung der Daten an einen vom Nutzer beauftragten Dritten erfolgt zu den in der Verordnung vorgesehenen Bedingungen. Die technischen Angaben beziehen sich auf Version 1 der API (/api/v1) mit Stand 5. Oktober 2026.

Die API liest die Daten aus, die erfasst werden von AI-Care, der Heiwit-Plattform zur Überwachung der Anlagen. Das Herzstück der Anlage ist derHybrid-Wechselrichter Virgo, kombiniert mit dem Heiwit Natrium-Ionen-Akku mit 10 kWh.