API REST

Com a API HTTP, lê os dispositivos da sua conta a partir do seu próprio programa. A API vê os mesmos dispositivos e tem as mesmas permissões que a sua conta na aplicação.

Princípios básicos

Item	Valor
URL de base	`https://api.hamsystems.eu`
Formato do pedido	`POST` com `application/x-www-form-urlencoded`, exceto quando a secção indica outro formato
Formato da resposta	JSON
Número de série	`<família>:<número>`, por exemplo `e11:123`. A primeira parte é a família do dispositivo.

A maioria das respostas tem um campo messages. É uma lista de objetos {"text": "...", "type": "error"}. O type é error, success ou info.

Autenticação

Existem dois métodos:

Método	Como o obtém	Duração
Chave API (`api_key`)	Na página Conta da aplicação	Não expira. Uma chave por conta.
Token de acesso (`access_token`)	Com `login.php` ou `login_api.php`	60 dias

Envie a chave API de uma destas formas:

O parâmetro api_key no corpo do POST ou na query string.
O cabeçalho Authorization: Bearer-API YOUR_API_KEY.

Envie o token de acesso de uma destas formas:

O parâmetro access_token no corpo do POST ou na query string.
O cabeçalho Authorization: Bearer YOUR_ACCESS_TOKEN.

Se enviar os dois, o servidor utiliza a chave API.

Criar uma chave API

Abra o Menu e toque em Conta.
Na secção Chave API, toque em Gerar chave API.
Confirme a mensagem. Uma chave nova cancela a chave antiga.
Toque na chave para a copiar. A aplicação mostra Copiado.

A secção Chave API na página Conta, com a chave oculta — Computador

Para cancelar uma chave, crie uma chave nova. A chave antiga deixa de funcionar de imediato.

Endpoints

Verificar uma chave: `check_api_key.php`

Verifica uma chave API.

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

Resposta: user, messages. Se a chave não está correta, messages tem o erro Api key not found.

Token de acesso a partir de uma chave: `login_api.php`

Dá um token de acesso para a chave API. Utilize-o quando uma ferramenta aceita apenas um token de acesso.

Parâmetro	Valor
`key`	A chave 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 tem um limite de tentativas. Após muitas falhas, responde Too many attempts, try again later.

Iniciar sessão com o e-mail: `login.php`

Parâmetro	Valor
`email`	O e-mail da conta
`password`	A palavra-passe
`timezone`	Opcional. O fuso horário, por exemplo `Europe/Athens`.

Resposta: access_token, user, messages. Se must_recaptcha é true, o servidor pede uma verificação reCAPTCHA. Nesse caso, utilize uma chave API.

Lista de dispositivos: `get_user_devices.php`

Devolve os dispositivos, os grupos, as plantas e as cenas da conta.

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

Campos da resposta: devices, groups, floorplans, scenes, messages. Com ?v=2&definitions=1, a resposta tem também um campo definitions para as famílias dos seus dispositivos.

Cada dispositivo tem estes campos:

Campo	Conteúdo
`serialno`	O número de série, por exemplo `e11:123`
`name`, `icon`	O nome e o ícone da aplicação
`mac`	O endereço MAC
`device_server`	O servidor do dispositivo. Precisa dele para o histórico e para o WebSocket.
`latitude`, `longitude`	A localização, se está definida
`firmware_version`	A versão do firmware
`settings`	As definições do dispositivo
`groups`, `floorplans`	Os grupos e as plantas do dispositivo
`permissions`	A sua permissão no dispositivo (veja abaixo)

Valores de permissions:

Valor	Permissão
`1`	Leitura
`2`	Escrita (controlar saídas)
`3`	Administrador
`4`	Proprietário

Um dispositivo: `get_device_info.php`

Parâmetro	Valor
`serialno`	O número 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

Resposta: device (os mesmos campos da lista), messages. Aceita também &definitions=1. Sem serialno, responde com HTTP 400. Sem acesso ao dispositivo, responde com HTTP 403.

Estado atual: `get_device_state.php`

Devolve as leituras atuais de um ou mais dispositivos. O 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"
  }
}

Para mais dispositivos, envie uma lista: {"serialno": ["e11:123", "e9:456"]}. A resposta é {"devices": [...], "count": 2}. Se o estado não está disponível, state é {"connected": false, "message": "Device state not available"}. Sem autenticação, a resposta é HTTP 401 com {"error": "Authentication required"}.

Definições das famílias

As definições indicam que leituras, saídas e definições cada família tem. Não precisam de autenticação.

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

A resposta tem families e readings. Com &include_readings=false, a resposta não tem o dicionário readings. Sem family_id, a resposta tem todas as famílias.

Cada família tem:

Campo	Conteúdo
`readings`	Os códigos das leituras pela sua ordem, por exemplo `["T", "GI", "GIC", "GI2", "GI2C"]`
`output_names`	As saídas pela sua ordem
`settings`	As definições da família
`ping_period`	O intervalo de keep-alive em segundos

O dicionário readings dá a etiqueta, a unidade e a conversão de cada código de leitura. Por exemplo, a leitura T tem a unidade °C e a conversão divide_by_100. Pode ver também a lista de leituras na página Leituras.

O valor 2147483648 significa que a leitura está em falta.

Tempo limite

Defina um tempo limite de cerca de 30 segundos nos seus pedidos.

Consulte também

Chat com o suporte