Passa al contenuto principale

Homsai Backend v2

Questa documentazione descrive le API REST del backend Homsai v2, una piattaforma per il monitoraggio e l’ottimizzazione di impianti energetici residenziali e industriali.
Il backend è sviluppato in Spring Boot 3.1.1 (Java 17) con architettura Domain-Driven Design e fornisce gestione di impianti (plants), dispositivi (devices), sensori (sensors), tipi di dispositivo/sensore, firme di carico, vendor e metriche energetiche avanzate (consumi, produzioni, previsioni e salute impianto).

Introduzione​

Homsai espone un insieme di API REST pensate per essere integrate in applicazioni di terze parti (portali, app mobile, sistemi di supervisione) per leggere e gestire dati energetici in tempo reale e storici. L’accesso alle API è protetto tramite JSON Web Token (JWT) e i permessi sono granulari per risorsa (impianti, dispositivi, sensori, metriche, previsioni), in linea con le best practice di sicurezza per API web.

L’istanza tipica prevede almeno due ambienti:

  • ambiente di test/sandbox per sviluppo e validazione integrazioni;
  • ambiente di produzione per i dati reali degli impianti.

Getting Started​

Questa sezione guida passo‑passo nella prima integrazione con le API di Homsai: ottenimento del token JWT e prima chiamata verso il backend.

Requisiti​

Per iniziare servono:

  • Un account Homsai abilitato all’uso delle API (credenziali utente).
  • L’URL base delle API (esempio: https://v2.api.homsai.app per produzione, più un eventuale endpoint sandbox).
  • Uno strumento per effettuare richieste HTTP: cURL da terminale, Postman oppure un client HTTP nel linguaggio scelto (Python, JS, Java, ecc.).

Ottenere il token JWT​

L’autenticazione avviene tramite lo scambio credenziali → token JWT:

  1. Effettua una richiesta POST /auth/login inviando email e password nel body JSON.
  2. In risposta il backend restituisce almeno:
    • accessToken: token a breve durata, da usare nell’header Authorization;
    • refreshToken: token a durata maggiore, da usare per ottenere un nuovo access token quando scade.

Qualsiasi chiamata protetta deve includere l’header:

Authorization: Bearer <accessToken>

Quando l’accessToken scade, puoi usare GET /auth/token passando il refreshToken secondo la modalità prevista dall’implementazione (header o altro canale documentato) per ottenere un nuovo access token senza rifare il login.

Prima chiamata “Hello World”​

Una volta ottenuto un accessToken valido, puoi verificare rapidamente che l’integrazione funzioni eseguendo una chiamata molto semplice.

1. Login e ottenimento del token​

Esempio con cURL:

curl -X POST [https://api.homsai.app/auth/login](https://api.homsai.app/auth/login) -H "Content-Type: application/json" -d '{
"email": "utente@example.com",
"password": "PasswordSicura123"
}'

Dalla risposta JSON copia il valore del campo accessToken.

2. Chiamata protetta “Hello World”​

Usa un endpoint semplice, ad esempio:

  • GET /version per leggere la versione del backend, oppure
  • GET /protected come endpoint di test che richiede solo la presenza di un JWT valido.

Esempio cURL con GET /version:

curl -X GET [https://api.homsai.app/version](https://api.homsai.app/version) -H "Authorization: Bearer <accessToken>"

Se la configurazione è corretta, riceverai:

  • uno status HTTP 200 OK;
  • un payload JSON con le informazioni della versione (/version) o un payload minimale di test (/protected).

Questa prima richiesta dimostra che:

  • le credenziali sono corrette;
  • il flusso login → token → chiamata autenticata funziona;
  • non ci sono problemi di rete, CORS o certificati verso l’endpoint API.