API per sviluppatori e automazione

Introduzione

Netzero ti permette di programmare le modifiche alla configurazione del Powerwall tramite l’app (riserva di backup, modalità operativa, esportazioni di energia e ricarica da rete elettrica).

Per un uso più avanzato, l’app offre anche un’API che consente di gestire queste modifiche alla configurazione.

Token API

Per iniziare, accedi al tuo account Tesla con l’app Netzero. Per trovare il tuo token API e l’ID del sistema energetico, apri il menu Account (l’ultimo menu) e seleziona Impostazioni > API sviluppatore. È importante conservare il token API in modo sicuro: pur dando accesso solo ai dati mostrati qui, consente di gestire la configurazione del Powerwall.

Il token può essere revocato e rigenerato nella stessa schermata. Per gli account creati a partire da luglio 2026, l’API per sviluppatori richiede un abbonamento Netzero.

Automazione con richieste API

Se hai dimestichezza con l’esecuzione di richieste web tramite curl o strumenti simili, puoi gestire la configurazione con degli script.

Per recuperare la configurazione attuale e lo stato in tempo reale del sistema, inserisci i valori $API_TOKEN e $SITE_ID ottenuti sopra ed esegui:

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

Questa risposta include sia i valori di configurazione sia la potenza attuale. Se al tuo account è collegato un Wall Connector, vedrai anche lo stato di ricarica dell’auto.

Per modificare la configurazione, invia una richiesta POST con i nuovi valori. Nella stessa richiesta puoi modificare uno o più dei seguenti parametri:

backup_reserve_percent: valori interi da 0 a 100, oppure la stringa preserve per impostare la riserva di backup sullo stato di carica attuale (in questo modo il Powerwall non si scarica, ad es. durante la ricarica di un EV).
operational_mode: scegli uno tra:
- autonomous (Risparmio, usa l’energia immagazzinata per massimizzare il risparmio in base al tuo piano tariffario),
- self_consumption (Alimentazione autonoma, usa l’energia immagazzinata per alimentare la casa dopo il tramonto).
- backup (modalità Backup, consulta la documentazione per i dettagli).
energy_exports: scegli uno tra:
- pv_only (esporta solo l’energia fotovoltaica),
- battery_ok (esporta sia l’energia fotovoltaica sia l’energia immagazzinata nel Powerwall),
- never (nessuna esportazione).
grid_charging: scegli true oppure false.
storm_watch: scegli true oppure false per abilitare o disabilitare la partecipazione a Scudo Tempesta (documentazione Tesla). Riportato come null sui sistemi in cui Scudo Tempesta non è disponibile.
off_grid_status: scegli uno tra:
- go_off_grid (scollega il sistema dalla rete),
- reconnect_grid (ricollega il sistema alla rete).
Le chiamate API con off_grid_status richiedono un abbonamento Netzero e l’Abbinamento Powerwall. Consulta Stato fuori rete più avanti per i dettagli.

Puoi modificare uno o più di questi valori nella stessa richiesta.

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

La risposta ha la stessa struttura di quella della richiesta GET e fornisce la configurazione aggiornata (comprese le eventuali modifiche apportate) insieme allo stato in tempo reale.

La risposta riflette la configurazione così come viene riportata da Tesla, quindi confrontala con i valori che hai inviato per verificare che la modifica sia stata applicata. Tieni presente che una riserva di backup tra l’81% e il 99% non è supportata da Tesla e viene reimpostata all’80%: consulta Aggiornamento della riserva di backup del Powerwall.

Ecco un esempio con codice Python invece di 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())

Valori dello stato della rete

Il campo grid_status della risposta indica se il sistema è collegato alla rete, con lo stato di funzionamento in isola tra parentesi quando disponibile. I valori possibili comprendono:

Active (on_grid): il sistema è collegato alla rete.
Inactive (off_grid_intentional): il sistema è stato scollegato intenzionalmente (vedi Stato fuori rete più avanti).
Inactive (off_grid_unintentional): il sistema è fuori rete a causa di un blackout.
Unknown (island_status_unknown): Tesla non ha riportato lo stato della rete. Alcuni sistemi riportano questo stato per lunghi periodi anche quando la rete è attiva.

Se Tesla non riporta uno stato di funzionamento in isola, il valore è semplicemente Active o Inactive.

Stato fuori rete

Il parametro off_grid_status ti consente di scollegarti dalla rete e di ricollegarti in modo programmatico. È utile per evitare prezzi di esportazione negativi o corrispettivi di domanda in determinati periodi.

Requisiti:

Un abbonamento Netzero attivo.
L’Abbinamento Powerwall deve essere configurato.

Esempio: scollegarsi dalla rete:

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

Puoi controllare lo stato attuale della rete nella risposta, in grid_status.