API REST

Con la API HTTP usted lee los dispositivos de su cuenta desde su propio programa. La API ve los mismos dispositivos y tiene los mismos permisos que su cuenta en la app.

Conceptos básicos

Elemento	Valor
URL base	https://api.hamsystems.eu
Formato de la solicitud	POST con application/x-www-form-urlencoded, salvo que la sección indique otra cosa
Formato de la respuesta	JSON
Número de serie	<family>:<number>, por ejemplo e11:123. La primera parte es la familia del dispositivo.

La mayoría de las respuestas tienen un campo messages. Es una lista de objetos {"text": "...", "type": "error"}. El type es error, success o info.

Autenticación

Hay dos métodos:

Método	Cómo se obtiene	Duración
Clave API (api_key)	En la página Cuenta de la app	No caduca. Una clave por cuenta.
Token de acceso (access_token)	Desde login.php o login_api.php	60 días

Envíe la clave API de una de estas maneras:

• Parámetro api_key en el cuerpo POST o en la cadena de consulta.
• Encabezado Authorization: Bearer-API YOUR_API_KEY.

Envíe el token de acceso de una de estas maneras:

• Parámetro access_token en el cuerpo POST o en la cadena de consulta.
• Encabezado Authorization: Bearer YOUR_ACCESS_TOKEN.

Si envía ambos, el servidor usa la clave API.

Precaución

La clave API da acceso completo a su cuenta. No la ponga en código que se ejecuta en un navegador ni en un repositorio público.

Crear una clave API

1. Abra el Menú y toque Cuenta.
2. En la sección Clave API, toque Generar clave API.
3. Confirme el mensaje. Una clave nueva cancela la clave antigua.
4. Toque la clave para copiarla. La app muestra Copiado.

Ordenador

Teléfono

Para cancelar una clave, cree una clave nueva. La clave antigua deja de funcionar de inmediato.

Endpoints

Comprobar una clave: check_api_key.php

Comprueba una clave API.

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

Respuesta: user, messages. Si la clave no es correcta, messages tiene el error Api key not found.

Token de acceso desde una clave: login_api.php

Da un token de acceso para la clave API. Úselo cuando una herramienta acepta solo un token de acceso.

Parámetro	Valor
key	La clave 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": []
}

Este endpoint tiene un límite de intentos. Después de muchos fallos responde Too many attempts, try again later.

Iniciar sesión con correo electrónico: login.php

Parámetro	Valor
email	El correo electrónico de la cuenta
password	La contraseña
timezone	Opcional. La zona horaria, por ejemplo Europe/Athens.

Respuesta: access_token, user, messages. Si must_recaptcha es true, el servidor pide una comprobación reCAPTCHA. En ese caso, use una clave API.

Lista de dispositivos: get_user_devices.php

Devuelve los dispositivos, grupos, planos y escenas de la cuenta.

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

Campos de la respuesta: devices, groups, floorplans, scenes, messages. Con ?v=2&definitions=1 la respuesta tiene también un campo definitions para las familias de sus dispositivos.

Cada dispositivo tiene estos campos:

Campo	Contenido
serialno	El número de serie, por ejemplo e11:123
name, icon	El nombre y el icono de la app
mac	La dirección MAC
device_server	El servidor del dispositivo. Lo necesita para el historial y para el WebSocket.
latitude, longitude	La ubicación, si está definida
firmware_version	La versión de firmware
settings	Los ajustes del dispositivo
groups, floorplans	Los grupos y los planos del dispositivo
permissions	Su permiso en el dispositivo (véase abajo)

Valores de permissions:

Valor	Permiso
1	Lectura
2	Escritura (controlar salidas)
3	Administrador
4	Propietario

Un dispositivo: get_device_info.php

Parámetro	Valor
serialno	El número de 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

Respuesta: device (los mismos campos que en la lista), messages. También acepta &definitions=1. Sin serialno responde con HTTP 400. Sin acceso al dispositivo responde con HTTP 403.

Estado actual: get_device_state.php

Devuelve las lecturas actuales de uno o más dispositivos. El cuerpo es 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"
  }
}

Para más dispositivos, envíe una lista: {"serialno": ["e11:123", "e9:456"]}. La respuesta es {"devices": [...], "count": 2}. Si el estado no está disponible, state es {"connected": false, "message": "Device state not available"}. Sin autenticación la respuesta es HTTP 401 con {"error": "Authentication required"}.

Nota

Los valores de readings están sin procesar. En el ejemplo, T: 2082 significa 20.82 °C. La definición de la familia le indica cómo convertir cada valor. Consulte las definiciones de familia a continuación.

Definiciones de familia

Las definiciones indican qué lecturas, salidas y ajustes tiene cada familia. No necesitan autenticación.

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

La respuesta tiene families y readings. Con &include_readings=false la respuesta no tiene el diccionario readings. Sin family_id la respuesta tiene todas las familias.

Cada familia tiene:

Campo	Contenido
readings	Los códigos de lectura en su orden, por ejemplo ["T", "GI", "GIC", "GI2", "GI2C"]
output_names	Las salidas en su orden
settings	Los ajustes de la familia
ping_period	El intervalo de mantenimiento de conexión en segundos

El diccionario readings da la etiqueta, la unidad y la conversión de cada código de lectura. Por ejemplo, la lectura T tiene la unidad °C y la conversión divide_by_100. También puede ver la lista de lecturas en la página Lecturas.

El valor 2147483648 significa que la lectura falta.

Tiempo de espera

Defina un tiempo de espera de unos 30 segundos en sus solicitudes.

Véase también

• Descargar datos históricos
• Datos en directo (WebSocket)
• MCP para asistentes de IA
• Dispositivos virtuales