Passa al contenuto principale

SDKs & Esempi di Codice

Questa sezione raccoglie esempi pratici di utilizzo delle API Homsai in vari contesti, utilizzando cURL e client HTTP comuni. Gli esempi riusano gli endpoint più importanti descritti nelle altre sezioni.

Overview​

Gli esempi mostrano come:

  • autenticarsi e ottenere un accessToken;
  • aggiungere l’header Authorization alle richieste;
  • chiamare alcuni endpoint chiave (plants, metrics, ecc.).

Puoi usarli come base per creare SDK o wrapper nelle tue applicazioni.

Nota: sostituisci sempre https://v2.api.homsai.app con l’URL dell’ambiente corretto (sandbox o produzione) e usa credenziali/token reali.

cURL examples​

Login (obtain accessToken)​

curl -X POST https://v2.api.homsai.app/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "SecurePassword123"
  }'

Dalla risposta JSON estrai il campo accessToken.

List plants​

curl -X GET "https://v2.api.homsai.app/plants?page=0&size=10"
-H "Authorization: Bearer <accessToken>"

Get daily power consumptions​

curl -X GET "https://v2.api.homsai.app/plants/<plantUuid>/daily-power-consumptions?date=2025-01-15"
-H "Authorization: Bearer <accessToken>"

JavaScript (fetch)​

Questi esempi mostrano come implementare lato JavaScript il flusso base:

  • fare login con POST /auth/login;
  • memorizzare l’accessToken;
  • usare il token per chiamare un endpoint protetto (es. lista plants).

Login and store token​

async function login() {
  const response = await fetch("https://v2.api.homsai.app/auth/login", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      email: "user@example.com",
      password: "SecurePassword123",
    }),
  });

  if (!response.ok) {
    throw new Error("Login failed");
  }

  const data = await response.json();
  return data.accessToken;
}

Questo blocco effettua il login, verifica che la risposta sia ok e restituisce l’accessToken ottenuto dal backend.

Call a protected endpoint​

async function listPlants(accessToken) {
const response = await fetch("https://v2.api.homsai.app/plants?page=0&size=10", {
headers: {
Authorization: Bearer ${accessToken},
},
});

if (!response.ok) {
throw new Error(Error listing plants: ${response.status});
}

return response.json();
}

Questo blocco mostra come usare l’accessToken nell’header Authorization: Bearer <token> per chiamare un endpoint protetto (GET /plants) e gestire gli errori base lato client.

Python (requests)​

Questi esempi mostrano come implementare lo stesso flusso in Python:

  • funzione di login che restituisce l’accessToken;
  • funzione che usa il token per chiamare un endpoint di metriche (PV health).

Login​

import requests

BASE_URL = "https://v2.api.homsai.app"

def login(email, password):
url = f"{BASE_URL}/auth/login"
payload = {"email": email, "password": password}
resp = requests.post(url, json=payload)
resp.raise_for_status()
data = resp.json()
return data["accessToken"]

Questa funzione chiama POST /auth/login, solleva eccezioni in caso di errore HTTP (raise_for_status) e restituisce l’accessToken estratto dalla risposta JSON.

Get PV health​

def get_pv_health(access_token, plant_uuid):
url = f"{BASE_URL}/plants/{plant_uuid}/pv-health"
headers = {"Authorization": f"Bearer {access_token}"}
resp = requests.get(url, headers=headers)
resp.raise_for_status()
return resp.json()

Questa funzione usa l’accessToken nell’header Authorization per chiamare l’endpoint GET /plants/{plantUuid}/pv-health e restituisce il payload JSON con gli indicatori di salute dell’impianto.

Questi snippet sono volutamente minimali: in un contesto reale è consigliato aggiungere gestione strutturata degli errori (401/403/5xx), logging e refresh automatico del token.