REST API

עם ה-HTTP API אתם קוראים את המכשירים של החשבון שלכם מהתוכנה שלכם. ה-API רואה את אותם מכשירים ויש לו את אותן הרשאות כמו לחשבון שלכם באפליקציה.

יסודות

פריט	ערך
כתובת בסיס	`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 או ב-query string.
הכותרת Authorization: Bearer-API YOUR_API_KEY.

שלחו את אסימון הגישה באחת מהדרכים האלה:

הפרמטר access_token בגוף ה-POST או ב-query string.
הכותרת Authorization: Bearer YOUR_ACCESS_TOKEN.

אם אתם שולחים את שניהם, השרת משתמש במפתח ה-API.

יצירת מפתח API

פתחו את תפריט והקישו על חשבון.
באזור מפתח API, הקישו על יצירת מפתח API.
אשרו את ההודעה. מפתח חדש מבטל את המפתח הישן.
הקישו על המפתח כדי להעתיק אותו. האפליקציה מציגה הועתק.

האזור מפתח API בדף חשבון, עם המפתח מוסתר — מחשב

כדי לבטל מפתח, צרו מפתח חדש. המפתח הישן מפסיק לעבוד מיד.

נקודות קצה

בדיקת מפתח: `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 אומר שהמדידה חסרה.

זמן קצוב

קבעו זמן קצוב (timeout) של בערך 30 שניות לבקשות שלכם.

ראו גם

צ'אט עם התמיכה