REST API

مع HTTP API تقرأ أجهزة حسابك من برنامجك. يرى الـ API الأجهزة نفسها وله الأذونات نفسها التي لحسابك في التطبيق.

الأساسيات

العنصر	القيمة
عنوان URL الأساسي	`https://api.hamsystems.eu`
تنسيق الطلب	`POST` مع `application/x-www-form-urlencoded`، إلا إذا قال القسم شيئًا آخر
تنسيق الاستجابة	JSON
الرقم التسلسلي	`<family>:<number>`، مثلًا `e11:123`. الجزء الأول هو عائلة الجهاز.

في أغلب الاستجابات حقل messages. هو قائمة كائنات {"text": "...", "type": "error"}. قيمة type هي error أو success أو info.

المصادقة

توجد طريقتان:

الطريقة	كيف تحصل عليها	مدة الصلاحية
مفتاح API (`api_key`)	من صفحة الحساب في التطبيق	لا تنتهي صلاحيته. مفتاح واحد لكل حساب.
رمز الوصول (`access_token`)	من `login.php` أو `login_api.php`	60 يومًا

أرسل مفتاح API بإحدى هذه الطرق:

المعامل api_key في محتوى POST أو في سلسلة الاستعلام.
الترويسة Authorization: Bearer-API YOUR_API_KEY.

أرسل رمز الوصول بإحدى هذه الطرق:

المعامل access_token في محتوى POST أو في سلسلة الاستعلام.
الترويسة Authorization: Bearer YOUR_ACCESS_TOKEN.

إذا أرسلت الاثنين، يستخدم الخادم مفتاح API.

إنشاء مفتاح API

افتح القائمة وانقر على الحساب.
في قسم API Key، انقر على إنشاء API Key.
أكّد الرسالة. يلغي المفتاح الجديد المفتاح القديم.
انقر على المفتاح لنسخه. يعرض التطبيق تم النسخ.

قسم API Key في صفحة الحساب، مع المفتاح مخفيًا — الكمبيوتر

لإلغاء مفتاح، أنشئ مفتاحًا جديدًا. يتوقف المفتاح القديم عن العمل فورًا.

نقاط النهاية

التحقق من مفتاح: `check_api_key.php`

يتحقق من مفتاح API.

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

الاستجابة: user وmessages. إذا كان المفتاح غير صحيح، يحتوي messages على الخطأ Api key not found.

رمز وصول من مفتاح: `login_api.php`

يعطي رمز وصول لمفتاح API. استخدمه عندما تقبل أداة رمز وصول فقط.

المعامل	القيمة
`key`	مفتاح 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": []
}

لنقطة النهاية هذه حد للمحاولات. بعد إخفاقات كثيرة ترد بـ Too many attempts, try again later.

تسجيل الدخول بالبريد الإلكتروني: `login.php`

المعامل	القيمة
`email`	البريد الإلكتروني للحساب
`password`	كلمة المرور
`timezone`	اختياري. المنطقة الزمنية، مثلًا `Europe/Athens`.

الاستجابة: access_token وuser وmessages. إذا كانت قيمة must_recaptcha هي true، يطلب الخادم فحص reCAPTCHA. عندئذ استخدم مفتاح API.

قائمة الأجهزة: `get_user_devices.php`

يعيد أجهزة الحساب ومجموعاته ومخططاته الأرضية ومشاهده.

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

حقول الاستجابة: devices وgroups وfloorplans وscenes وmessages. مع ?v=2&definitions=1 تحتوي الاستجابة أيضًا على حقل definitions لعائلات أجهزتك.

لكل جهاز هذه الحقول:

الحقل	المحتوى
`serialno`	الرقم التسلسلي، مثلًا `e11:123`
`name`, `icon`	الاسم والأيقونة من التطبيق
`mac`	عنوان MAC
`device_server`	خادم الجهاز. تحتاج إليه لـ السجل ولـ WebSocket.
`latitude`, `longitude`	الموقع، إذا كان مضبوطًا
`firmware_version`	إصدار البرنامج الثابت
`settings`	إعدادات الجهاز
`groups`, `floorplans`	مجموعات الجهاز ومخططاته الأرضية
`permissions`	إذنك على الجهاز (انظر أدناه)

قيم permissions:

القيمة	الإذن
`1`	قراءة
`2`	كتابة (التحكم في المخرجات)
`3`	إدارة
`4`	المالك

جهاز واحد: `get_device_info.php`

المعامل	القيمة
`serialno`	الرقم التسلسلي

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

الاستجابة: device (الحقول نفسها الموجودة في القائمة) وmessages. يقبل أيضًا &definitions=1. بدون serialno يرد بـ HTTP 400. بدون وصول إلى الجهاز يرد بـ HTTP 403.

الحالة الحالية: `get_device_state.php`

يعيد القراءات الحالية لجهاز واحد أو أكثر. المحتوى 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"
  }
}

لأجهزة أكثر، أرسل قائمة: {"serialno": ["e11:123", "e9:456"]}. الاستجابة {"devices": [...], "count": 2}. إذا لم تكن الحالة متاحة، تكون قيمة state هي {"connected": false, "message": "Device state not available"}. بدون مصادقة تكون الاستجابة HTTP 401 مع {"error": "Authentication required"}.

تعريفات العائلات

تخبرك التعريفات ما القراءات والمخرجات والإعدادات الموجودة في كل عائلة. لا تحتاج إلى مصادقة.

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

تحتوي الاستجابة على families وreadings. مع &include_readings=false لا تحتوي الاستجابة على قاموس readings. بدون family_id تحتوي الاستجابة على كل العائلات.

لكل عائلة:

الحقل	المحتوى
`readings`	رموز القراءات بترتيبها، مثلًا `["T", "GI", "GIC", "GI2", "GI2C"]`
`output_names`	المخرجات بترتيبها
`settings`	إعدادات العائلة
`ping_period`	فترة keep-alive بالثواني

يعطي قاموس readings التسمية والوحدة والتحويل لكل رمز قراءة. مثلًا، للقراءة T الوحدة °C والتحويل divide_by_100. يمكنك أيضًا رؤية قائمة القراءات في صفحة قاموس القراءات.

تعني القيمة 2147483648 أن القراءة مفقودة.

المهلة

اضبط مهلة 30 ثانية تقريبًا لطلباتك.

انظر أيضًا

الدردشة مع الدعم