REST API

HTTP API ile hesabınızın cihazlarını kendi programınızdan okursunuz. API, uygulamadaki hesabınızla aynı cihazları görür ve aynı izinlere sahiptir.

Temel bilgiler

Öğe	Değer
Temel URL	https://api.hamsystems.eu
İstek biçimi	Bölüm farklı bir şey söylemiyorsa application/x-www-form-urlencoded ile POST
Yanıt biçimi	JSON
Seri numarası	<family>:<number>, örneğin e11:123. İlk kısım cihaz ailesidir.

Çoğu yanıtta bir messages alanı vardır. Bu alan {"text": "...", "type": "error"} nesnelerinden oluşan bir listedir. type değeri error, success veya info olur.

Kimlik doğrulama

İki yöntem vardır:

Yöntem	Nasıl alırsınız	Geçerlilik süresi
API anahtarı (api_key)	Uygulamanın Hesap sayfasından	Süresi dolmaz. Hesap başına bir anahtar.
Erişim token’ı (access_token)	login.php veya login_api.php ile	60 gün

API anahtarını şu yollardan biriyle gönderin:

• POST gövdesinde veya sorgu dizesinde api_key parametresi.
• Authorization: Bearer-API YOUR_API_KEY başlığı.

Erişim token’ını şu yollardan biriyle gönderin:

• POST gövdesinde veya sorgu dizesinde access_token parametresi.
• Authorization: Bearer YOUR_ACCESS_TOKEN başlığı.

İkisini de gönderirseniz sunucu API anahtarını kullanır.

Dikkat

API anahtarı hesabınıza tam erişim verir. Onu bir tarayıcıda çalışan koda veya herkese açık bir depoya koymayın.

Bir API anahtarı oluşturma

1. Menü seçeneğini açın ve Hesap seçeneğine dokunun.
2. API Anahtarı bölümünde API anahtarı oluştur seçeneğine dokunun.
3. Mesajı onaylayın. Yeni bir anahtar eski anahtarı iptal eder.
4. Kopyalamak için anahtara dokunun. Uygulama Kopyalandı gösterir.

Bilgisayar

Telefon

Bir anahtarı iptal etmek için yeni bir anahtar oluşturun. Eski anahtar hemen çalışmayı durdurur.

Uç noktalar

Bir anahtarı kontrol etme: check_api_key.php

Bir API anahtarını kontrol eder.

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

Yanıt: user, messages. Anahtar doğru değilse messages alanında Api key not found hatası bulunur.

Bir anahtardan erişim token’ı: login_api.php

API anahtarı için bir erişim token’ı verir. Bir araç yalnızca erişim token’ı kabul ettiğinde bunu kullanın.

Parametre	Değer
key	API anahtarı

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

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

Bu uç noktanın bir deneme sınırı vardır. Birçok başarısız denemeden sonra Too many attempts, try again later yanıtını verir.

E-postayla oturum açma: login.php

Parametre	Değer
email	Hesabın e-postası
password	Parola
timezone	İsteğe bağlı. Saat dilimi, örneğin Europe/Athens.

Yanıt: access_token, user, messages. must_recaptcha değeri true ise sunucu bir reCAPTCHA kontrolü ister. Bu durumda bir API anahtarı kullanın.

Cihaz listesi: get_user_devices.php

Hesabın cihazlarını, gruplarını, kat planlarını ve sahnelerini döndürür.

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

Yanıt alanları: devices, groups, floorplans, scenes, messages. ?v=2&definitions=1 ile yanıtta cihazlarınızın aileleri için bir definitions alanı da bulunur.

Her cihazın şu alanları vardır:

Alan	İçerik
serialno	Seri numarası, örneğin e11:123
name, icon	Uygulamadaki ad ve simge
mac	MAC adresi
device_server	Cihazın cihaz sunucusu. Geçmiş ve WebSocket için buna ihtiyacınız vardır.
latitude, longitude	Ayarlanmışsa konum
firmware_version	Firmware sürümü
settings	Cihaz ayarları
groups, floorplans	Cihazın grupları ve kat planları
permissions	Cihaz üzerindeki izniniz (aşağıya bakın)

permissions değerleri:

Değer	İzin
1	Okuma
2	Yazma (çıkışları kontrol etme)
3	Yönetici
4	Sahip

Tek bir cihaz: get_device_info.php

Parametre	Değer
serialno	Seri numarası

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

Yanıt: device (listedekiyle aynı alanlar), messages. &definitions=1 parametresini de kabul eder. serialno olmadan HTTP 400 ile yanıt verir. Cihaza erişim olmadan HTTP 403 ile yanıt verir.

Geçerli durum: get_device_state.php

Bir veya daha fazla cihazın geçerli ölçümlerini döndürür. Gövde JSON’dur.

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"
  }
}

Daha fazla cihaz için bir liste gönderin: {"serialno": ["e11:123", "e9:456"]}. Yanıt {"devices": [...], "count": 2} olur. Durum mevcut değilse state değeri {"connected": false, "message": "Device state not available"} olur. Kimlik doğrulama olmadan yanıt {"error": "Authentication required"} ile HTTP 401 olur.

Not

readings içindeki değerler ham değerlerdir. Örnekte T: 2082, 20.82 °C anlamına gelir. Aile tanımı her değeri nasıl dönüştüreceğinizi söyler. Aşağıdaki aile tanımlarına bakın.

Aile tanımları

Tanımlar, her ailenin hangi ölçümlere, çıkışlara ve ayarlara sahip olduğunu söyler. Kimlik doğrulama gerektirmezler.

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

Yanıtta families ve readings bulunur. &include_readings=false ile yanıtta readings sözlüğü bulunmaz. family_id olmadan yanıtta tüm aileler bulunur.

Her ailenin şunları vardır:

Alan	İçerik
readings	Sıralarına göre ölçüm kodları, örneğin ["T", "GI", "GIC", "GI2", "GI2C"]
output_names	Sıralarına göre çıkışlar
settings	Ailenin ayarları
ping_period	Saniye cinsinden canlı tutma aralığı

readings sözlüğü her ölçüm kodu için etiketi, birimi ve dönüşümü verir. Örneğin T ölçümünün birimi °C ve dönüşümü divide_by_100 şeklindedir. Ölçüm listesini Ölçümler sözlüğü sayfasında da görebilirsiniz.

2147483648 değeri ölçümün eksik olduğu anlamına gelir.

Zaman aşımı

İsteklerinizde yaklaşık 30 saniyelik bir zaman aşımı ayarlayın.

Ayrıca bkz.

• Geçmiş verileri indirme
• Canlı veriler (WebSocket)
• Yapay zeka asistanları için MCP
• Sanal cihazlar