API REST

Con l’API HTTP legge i dispositivi del Suo account dal Suo programma. L’API vede gli stessi dispositivi e ha gli stessi permessi del Suo account nell’app.

Nozioni di base

Elemento	Valore
URL di base	`https://api.hamsystems.eu`
Formato della richiesta	`POST` con `application/x-www-form-urlencoded`, salvo diversa indicazione nella sezione
Formato della risposta	JSON
Numero di serie	`<famiglia>:<numero>`, per esempio `e11:123`. La prima parte è la famiglia del dispositivo.

La maggior parte delle risposte ha un campo messages. È un elenco di oggetti {"text": "...", "type": "error"}. Il type è error, success o info.

Autenticazione

Ci sono due metodi:

Metodo	Come lo ottiene	Durata
Chiave API (`api_key`)	Dalla pagina Account dell’app	Non scade. Una chiave per account.
Token di accesso (`access_token`)	Da `login.php` o `login_api.php`	60 giorni

Invii la chiave API in uno di questi modi:

Parametro api_key nel corpo POST o nella query string.
Header Authorization: Bearer-API YOUR_API_KEY.

Invii il token di accesso in uno di questi modi:

Parametro access_token nel corpo POST o nella query string.
Header Authorization: Bearer YOUR_ACCESS_TOKEN.

Se invia entrambi, il server usa la chiave API.

Creare una chiave API

Apra il Menu e tocchi Account.
Nella sezione Chiave API, tocchi Genera chiave API.
Confermi il messaggio. Una nuova chiave annulla la vecchia chiave.
Tocchi la chiave per copiarla. L’app mostra Copiato.

La sezione Chiave API nella pagina Account, con la chiave nascosta — Computer

Per annullare una chiave, crei una nuova chiave. La vecchia chiave smette subito di funzionare.

Endpoint

Verificare una chiave: `check_api_key.php`

Verifica una chiave API.

curl -X POST https://api.hamsystems.eu/check_api_key.php \
  -d api_key=YOUR_API_KEY

Risposta: user, messages. Se la chiave non è corretta, messages contiene l’errore Api key not found.

Token di accesso da una chiave: `login_api.php`

Fornisce un token di accesso per la chiave API. Lo usi quando uno strumento accetta solo un token di accesso.

Parametro	Valore
`key`	La chiave API

curl -X POST https://api.hamsystems.eu/login_api.php \
  -d key=YOUR_API_KEY

{
  "access_token": "YOUR_ACCESS_TOKEN",
  "user": { "id": 1234 },
  "messages": []
}

Questo endpoint ha un limite di tentativi. Dopo molti errori risponde Too many attempts, try again later.

Accesso con e-mail: `login.php`

Parametro	Valore
`email`	L’e-mail dell’account
`password`	La password
`timezone`	Facoltativo. Il fuso orario, per esempio `Europe/Athens`.

Risposta: access_token, user, messages. Se must_recaptcha è true, il server richiede un controllo reCAPTCHA. In questo caso usi una chiave API.

Elenco dei dispositivi: `get_user_devices.php`

Restituisce i dispositivi, i gruppi, le planimetrie e gli scenari dell’account.

curl -X POST "https://api.hamsystems.eu/get_user_devices.php?v=2" \
  -H "Authorization: Bearer-API YOUR_API_KEY"

Campi della risposta: devices, groups, floorplans, scenes, messages. Con ?v=2&definitions=1 la risposta ha anche un campo definitions per le famiglie dei Suoi dispositivi.

Ogni dispositivo ha questi campi:

Campo	Contenuto
`serialno`	Il numero di serie, per esempio `e11:123`
`name`, `icon`	Il nome e l’icona dell’app
`mac`	L’indirizzo MAC
`device_server`	Il server del dispositivo. Ne ha bisogno per lo storico e per il WebSocket.
`latitude`, `longitude`	La posizione, se è impostata
`firmware_version`	La versione del firmware
`settings`	Le impostazioni del dispositivo
`groups`, `floorplans`	I gruppi e le planimetrie del dispositivo
`permissions`	Il Suo permesso sul dispositivo (veda sotto)

Valori di permissions:

Valore	Permesso
`1`	Lettura
`2`	Scrittura (controllo delle uscite)
`3`	Amministratore
`4`	Proprietario

Un dispositivo: `get_device_info.php`

Parametro	Valore
`serialno`	Il numero di serie

curl -X POST "https://api.hamsystems.eu/get_device_info.php?v=2" \
  -H "Authorization: Bearer-API YOUR_API_KEY" \
  -d serialno=e11:123

Risposta: device (gli stessi campi dell’elenco), messages. Accetta anche &definitions=1. Senza serialno risponde con HTTP 400. Senza accesso al dispositivo risponde con HTTP 403.

Stato attuale: `get_device_state.php`

Restituisce le misurazioni attuali di uno o più dispositivi. Il corpo è JSON.

curl -X POST https://api.hamsystems.eu/get_device_state.php \
  -H "Authorization: Bearer-API YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"serialno": "e11:123"}'

{
  "serialno": "e11:123",
  "name": "Fridge 1",
  "state": {
    "connected": true,
    "timestamp": 1791936198,
    "readings": { "T": 2082, "GI": 1, "GIC": 0, "GI2": 1, "GI2C": 0 },
    "rssi": -55,
    "device_name": "Fridge 1"
  }
}

Per più dispositivi, invii un elenco: {"serialno": ["e11:123", "e9:456"]}. La risposta è {"devices": [...], "count": 2}. Se lo stato non è disponibile, state è {"connected": false, "message": "Device state not available"}. Senza autenticazione la risposta è HTTP 401 con {"error": "Authentication required"}.

Definizioni delle famiglie

Le definizioni indicano quali misurazioni, uscite e impostazioni ha ogni famiglia. Non richiedono autenticazione.

curl "https://api.hamsystems.eu/get_device_definitions.php?family_id=e11"

La risposta ha families e readings. Con &include_readings=false la risposta non ha il dizionario readings. Senza family_id la risposta ha tutte le famiglie.

Ogni famiglia ha:

Campo	Contenuto
`readings`	I codici delle misurazioni nel loro ordine, per esempio `["T", "GI", "GIC", "GI2", "GI2C"]`
`output_names`	Le uscite nel loro ordine
`settings`	Le impostazioni della famiglia
`ping_period`	L’intervallo di keep-alive in secondi

Il dizionario readings fornisce l’etichetta, l’unità e la conversione per ogni codice di misurazione. Per esempio, la misurazione T ha l’unità °C e la conversione divide_by_100. Può anche vedere l’elenco delle misurazioni nella pagina Misurazioni.

Il valore 2147483648 indica che la misurazione manca.

Timeout

Imposti un timeout di circa 30 secondi sulle Sue richieste.

Vedere anche

Chat con l'assistenza