API REST

Avec l’API HTTP, vous lisez les appareils de votre compte depuis votre propre programme. L’API voit les mêmes appareils et a les mêmes permissions que votre compte dans l’application.

Notions de base

Élément	Valeur
URL de base	https://api.hamsystems.eu
Format de la requête	POST avec application/x-www-form-urlencoded, sauf si la section dit autre chose
Format de la réponse	JSON
Numéro de série	<family>:<number>, par exemple e11:123. La première partie est la famille de l’appareil.

La plupart des réponses ont un champ messages. C’est une liste d’objets {"text": "...", "type": "error"}. Le type est error, success ou info.

Authentification

Il existe deux méthodes :

Méthode	Comment l’obtenir	Durée de vie
Clé API (api_key)	Depuis la page Compte de l’application	Elle n’expire pas. Une clé par compte.
Jeton d’accès (access_token)	Depuis login.php ou login_api.php	60 jours

Envoyez la clé API d’une de ces façons :

• Paramètre api_key dans le corps POST ou dans la chaîne de requête.
• En-tête Authorization: Bearer-API YOUR_API_KEY.

Envoyez le jeton d’accès d’une de ces façons :

• Paramètre access_token dans le corps POST ou dans la chaîne de requête.
• En-tête Authorization: Bearer YOUR_ACCESS_TOKEN.

Si vous envoyez les deux, le serveur utilise la clé API.

Attention

La clé API donne un accès complet à votre compte. Ne la mettez pas dans du code qui s’exécute dans un navigateur ou dans un dépôt public.

Créer une clé API

1. Ouvrez le Menu et touchez Compte.
2. Dans la section Clé API, touchez Générer une clé API.
3. Confirmez le message. Une nouvelle clé annule l’ancienne clé.
4. Touchez la clé pour la copier. L’application affiche Copié.

Ordinateur

Téléphone

Pour annuler une clé, créez une nouvelle clé. L’ancienne clé cesse de fonctionner immédiatement.

Points d’accès

Vérifier une clé : check_api_key.php

Vérifie une clé API.

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

Réponse : user, messages. Si la clé n’est pas correcte, messages contient l’erreur Api key not found.

Jeton d’accès à partir d’une clé : login_api.php

Donne un jeton d’accès pour la clé API. Utilisez-le quand un outil accepte seulement un jeton d’accès.

Paramètre	Valeur
key	La clé 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": []
}

Ce point d’accès a une limite de tentatives. Après beaucoup d’échecs, il répond Too many attempts, try again later.

Connexion avec l’e-mail : login.php

Paramètre	Valeur
email	L’e-mail du compte
password	Le mot de passe
timezone	Facultatif. Le fuseau horaire, par exemple Europe/Athens.

Réponse : access_token, user, messages. Si must_recaptcha est true, le serveur demande une vérification reCAPTCHA. Dans ce cas, utilisez une clé API.

Liste des appareils : get_user_devices.php

Renvoie les appareils, les groupes, les plans d’étage et les scènes du compte.

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

Champs de la réponse : devices, groups, floorplans, scenes, messages. Avec ?v=2&definitions=1, la réponse a aussi un champ definitions pour les familles de vos appareils.

Chaque appareil a ces champs :

Champ	Contenu
serialno	Le numéro de série, par exemple e11:123
name, icon	Le nom et l’icône de l’application
mac	L’adresse MAC
device_server	Le serveur d’appareils de l’appareil. Vous en avez besoin pour l’historique et pour le WebSocket.
latitude, longitude	L’emplacement, s’il est défini
firmware_version	La version du micrologiciel
settings	Les paramètres de l’appareil
groups, floorplans	Les groupes et les plans d’étage de l’appareil
permissions	Votre permission sur l’appareil (voir ci-dessous)

Valeurs de permissions :

Valeur	Permission
1	Lecture
2	Écriture (commande des sorties)
3	Administrateur
4	Propriétaire

Un appareil : get_device_info.php

Paramètre	Valeur
serialno	Le numéro de série

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

Réponse : device (les mêmes champs que dans la liste), messages. Il accepte aussi &definitions=1. Sans serialno, il répond avec HTTP 400. Sans accès à l’appareil, il répond avec HTTP 403.

État actuel : get_device_state.php

Renvoie les mesures actuelles d’un ou de plusieurs appareils. Le corps est du 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"
  }
}

Pour plusieurs appareils, envoyez une liste : {"serialno": ["e11:123", "e9:456"]}. La réponse est {"devices": [...], "count": 2}. Si l’état n’est pas disponible, state est {"connected": false, "message": "Device state not available"}. Sans authentification, la réponse est HTTP 401 avec {"error": "Authentication required"}.

Note

Les valeurs dans readings sont brutes. Dans l’exemple, T: 2082 signifie 20,82 °C. La définition de la famille indique comment convertir chaque valeur. Voir les définitions de famille ci-dessous.

Définitions de famille

Les définitions indiquent quelles mesures, sorties et paramètres chaque famille a. Elles ne demandent pas d’authentification.

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

La réponse a families et readings. Avec &include_readings=false, la réponse n’a pas le dictionnaire readings. Sans family_id, la réponse a toutes les familles.

Chaque famille a :

Champ	Contenu
readings	Les codes de mesure dans leur ordre, par exemple ["T", "GI", "GIC", "GI2", "GI2C"]
output_names	Les sorties dans leur ordre
settings	Les paramètres de la famille
ping_period	L’intervalle de maintien de connexion en secondes

Le dictionnaire readings donne le libellé, l’unité et la conversion pour chaque code de mesure. Par exemple, la mesure T a l’unité °C et la conversion divide_by_100. Vous pouvez aussi voir la liste des mesures sur la page Mesures.

La valeur 2147483648 signifie que la mesure est absente.

Délai d’attente

Réglez un délai d’attente d’environ 30 secondes sur vos requêtes.

Voir aussi

• Télécharger les données historiques
• Données en direct (WebSocket)
• MCP pour les assistants IA
• Appareils virtuels