Entwickler-API und Automatisierung

Einführung

Mit Netzero können Sie Konfigurationsänderungen an der Powerwall über die App planen (Notreserve, Betriebsmodus, Energieexporte und Netzaufladung).

Für fortgeschrittene Anwendungen bietet die App außerdem eine API, mit der Sie diese Konfigurationsänderungen verwalten können.

API-Token

Melden Sie sich zunächst mit der Netzero-App bei Ihrem Tesla-Konto an. Ihr API-Token und die Energy Site ID finden Sie im Menü „Konto“ (letztes Menü) unter Einstellungen > Entwickler-API. Bewahren Sie Ihr API-Token sicher auf: Es gewährt zwar nur Zugriff auf die hier angezeigten Daten, ermöglicht aber die Verwaltung der Powerwall-Konfiguration.

Das Token kann auf demselben Bildschirm widerrufen und neu erstellt werden. Für Konten, die ab Juli 2026 erstellt wurden, erfordert die Entwickler-API ein Netzero-Abonnement.

Automatisierung mit API-Anfragen

Wenn Sie mit Webanfragen über curl oder ähnliche Werkzeuge vertraut sind, können Sie die Konfiguration mit Skripten verwalten.

Um die aktuelle Konfiguration und den Live-Status des Systems abzurufen, setzen Sie die oben ermittelten Werte für $API_TOKEN und $SITE_ID ein und führen Sie Folgendes aus:

export API_TOKEN="..."
export SITE_ID="..."

curl -H "Authorization: Bearer $API_TOKEN" https://api.netzero.energy/api/v1/$SITE_ID/config

{
  "backup_reserve_percent": 80,
  "operational_mode": "autonomous",
  "energy_exports": "pv_only",
  "grid_charging": true,
  "storm_watch": true,
  "percentage_charged": 70,
  "grid_status": "Active (on_grid)",

  "live_status": {
    "solar_power": 4140,
    "battery_power": -2520,
    "load_power": 1620,
    "grid_power": 0,
    [...],
    "wall_connectors": [
      {
        "din": "1457768-02-G--B7S12345J12345",
        "wall_connector_state": 2,
        "wall_connector_fault_state": 2,
        "wall_connector_power": 0
      }
    ]
  }
}

Diese Antwort enthält sowohl die Konfigurationswerte als auch die aktuelle Leistung. Wenn ein Wall Connector mit Ihrem Konto verbunden ist, sehen Sie außerdem den Ladestatus des Fahrzeugs.

Um die Konfiguration zu ändern, senden Sie eine POST-Anfrage mit neuen Werten. Sie können einen oder mehrere der folgenden Parameter in derselben Anfrage anpassen:

backup_reserve_percent: Ganzzahlige Werte von 0 bis 100 oder die Zeichenkette preserve, um die Notreserve auf den aktuellen Ladezustand zu setzen (das verhindert, dass sich die Powerwall entlädt, z. B. während ein Elektroauto lädt).
operational_mode: Einer der folgenden Werte:
- autonomous (Sparmodus: nutzt gespeicherte Energie, um die Einsparungen gemäß Ihrem Stromtarif zu maximieren),
- self_consumption (Eigenversorger: nutzt gespeicherte Energie, um Ihr Haus nach Sonnenuntergang zu versorgen).
- backup (Backup-Modus, Einzelheiten siehe Dokumentation).
energy_exports: Einer der folgenden Werte:
- pv_only (nur Solarenergie exportieren),
- battery_ok (sowohl Solarenergie als auch gespeicherte Powerwall-Energie exportieren),
- never (kein Export).
grid_charging: Entweder true oder false.
storm_watch: Entweder true oder false, um die Teilnahme an der Unwetterwarnung zu aktivieren oder zu deaktivieren (Tesla-Dokumentation). Auf Systemen, auf denen die Unwetterwarnung nicht verfügbar ist, wird null gemeldet.
off_grid_status: Einer der folgenden Werte:
- go_off_grid (das System vom Stromnetz trennen),
- reconnect_grid (das System wieder mit dem Stromnetz verbinden).
API-Aufrufe mit off_grid_status erfordern ein Netzero-Abonnement und die Powerwall-Kopplung. Einzelheiten finden Sie unter Netztrennungsstatus weiter unten.

Sie können einen oder mehrere dieser Werte in derselben Anfrage ändern.

curl -H "Authorization: Bearer $API_TOKEN" \
    --json '{"backup_reserve_percent": 50, "operational_mode": "self_consumption"}' \
    https://api.netzero.energy/api/v1/$SITE_ID/config

{
  "backup_reserve_percent": 50,
  "operational_mode": "self_consumption",
  "energy_exports": "pv_only",
  "grid_charging": true,
  "storm_watch": true,
  "percentage_charged": 98,
  "grid_status": "Active (on_grid)",
  "live_status": {...}
}

Die Antwort entspricht der Antwort auf die GET-Anfrage und liefert die aktualisierte Konfiguration (einschließlich aller vorgenommenen Änderungen) zusammen mit dem Live-Status.

Die Antwort gibt die Konfiguration so wieder, wie Tesla sie meldet. Vergleichen Sie sie daher mit den gesendeten Werten, um zu bestätigen, dass die Änderung wirksam wurde. Beachten Sie, dass eine Notreserve zwischen 81 % und 99 % von Tesla nicht unterstützt wird und auf 80 % zurückgesetzt wird: siehe Aktualisierung der Powerwall-Notreserve.

Hier ein Beispiel mit Python-Code statt curl:

import os
import requests

site_id = os.environ['SITE_ID']
api_token = os.environ['API_TOKEN']
config = {'backup_reserve_percent': 30, 'operational_mode': 'autonomous'}

response = requests.post(
    url=f'https://api.netzero.energy/api/v1/{site_id}/config',
    headers={'Authorization': f'Bearer {api_token}'},
    json=config,
)
print(response.json())

Werte des Netzstatus

Das Antwortfeld grid_status gibt an, ob das System mit dem Stromnetz verbunden ist, und nennt, sofern verfügbar, den Inselbetriebszustand in Klammern. Mögliche Werte sind:

Active (on_grid): Das System ist mit dem Stromnetz verbunden.
Inactive (off_grid_intentional): Das System wurde absichtlich getrennt (siehe Netztrennungsstatus weiter unten).
Inactive (off_grid_unintentional): Das System ist aufgrund eines Stromausfalls vom Stromnetz getrennt.
Unknown (island_status_unknown): Tesla hat den Netzstatus nicht gemeldet. Manche Systeme melden diesen Zustand über längere Zeiträume, selbst wenn das Stromnetz verfügbar ist.

Meldet Tesla keinen Inselbetriebszustand, lautet der Wert nur Active oder Inactive.

Netztrennungsstatus

Mit dem Parameter off_grid_status können Sie das System programmgesteuert vom Stromnetz trennen und wieder verbinden. Das ist nützlich, um in bestimmten Zeiträumen negative Einspeisepreise oder Leistungspreise zu vermeiden.

Voraussetzungen:

Ein aktives Netzero-Abonnement.
Die Powerwall-Kopplung muss eingerichtet sein.

Beispiel: Trennen vom Stromnetz:

curl -H "Authorization: Bearer $API_TOKEN" \
    --json '{"off_grid_status": "go_off_grid"}' \
    https://api.netzero.energy/api/v1/$SITE_ID/config

Den aktuellen Netzstatus finden Sie in der Antwort unter grid_status.