REST API

Με το HTTP API διαβάζετε τις συσκευές του λογαριασμού σας από δικό σας πρόγραμμα. Το API βλέπει τις ίδιες συσκευές και έχει τα ίδια δικαιώματα με τον λογαριασμό σας στην εφαρμογή.

Βασικά στοιχεία

Στοιχείο	Τιμή
Βασική διεύθυνση	https://api.hamsystems.eu
Μορφή αιτήματος	POST με application/x-www-form-urlencoded, εκτός αν η σελίδα λέει κάτι άλλο
Μορφή απάντησης	JSON
Σειριακός αριθμός	<οικογένεια>:<αριθμός>, π.χ. e11:123. Το πρώτο μέρος είναι η οικογένεια της συσκευής.

Οι περισσότερες απαντήσεις έχουν το πεδίο messages. Είναι λίστα με αντικείμενα {"text": "...", "type": "error"}. Το type είναι error, success ή info.

Έλεγχος ταυτότητας

Υπάρχουν δύο τρόποι:

Τρόπος	Πώς το παίρνετε	Διάρκεια
Κλειδί API (api_key)	Από τη σελίδα Λογαριασμός της εφαρμογής	Δεν λήγει. Ένα κλειδί ανά λογαριασμό.
Access token (access_token)	Από το login.php ή το login_api.php	60 ημέρες

Στείλτε το κλειδί με έναν από αυτούς τους τρόπους:

• Παράμετρος api_key στο σώμα POST ή στο query string.
• Κεφαλίδα Authorization: Bearer-API YOUR_API_KEY.

Στείλτε το access token με έναν από αυτούς τους τρόπους:

• Παράμετρος access_token στο σώμα POST ή στο query string.
• Κεφαλίδα Authorization: Bearer YOUR_ACCESS_TOKEN.

Αν στείλετε και τα δύο, ο διακομιστής χρησιμοποιεί το κλειδί API.

Προσοχή

Το κλειδί API δίνει πλήρη πρόσβαση στον λογαριασμό σας. Μην το βάλετε σε κώδικα που τρέχει σε browser ή σε δημόσιο αποθετήριο.

Δημιουργία κλειδιού API

1. Ανοίξτε το Μενού και πατήστε Λογαριασμός.
2. Στην ενότητα Κλειδί API, πατήστε Δημιουργία κλειδιού API.
3. Επιβεβαιώστε το μήνυμα. Ένα νέο κλειδί ακυρώνει το παλιό.
4. Πατήστε το κλειδί για να το αντιγράψετε. Η εφαρμογή δείχνει Αντιγράφηκε.

Υπολογιστής

Κινητό

Για να ακυρώσετε ένα κλειδί, δημιουργήστε νέο κλειδί. Το παλιό κλειδί σταματά να λειτουργεί αμέσως.

Endpoints

Έλεγχος κλειδιού: 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.

Access token από κλειδί: login_api.php

Δίνει ένα access token για το κλειδί API. Χρησιμοποιήστε το όταν ένα εργαλείο δέχεται μόνο access token.

Παράμετρος	Τιμή
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": []
}

Το endpoint έχει όριο προσπαθειών. Μετά από πολλές αποτυχίες απαντά Too many attempts, try again later.

Σύνδεση με e-mail: login.php

Παράμετρος	Τιμή
email	Το e-mail του λογαριασμού
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": "Ψυγείο 1",
  "state": {
    "connected": true,
    "timestamp": 1791936198,
    "readings": { "T": 2082, "GI": 1, "GIC": 0, "GI2": 1, "GI2C": 0 },
    "rssi": -55,
    "device_name": "Ψυγείο 1"
  }
}

Για πολλές συσκευές στείλτε λίστα: {"serialno": ["e11:123", "e9:456"]}. Η απάντηση είναι {"devices": [...], "count": 2}. Αν η κατάσταση δεν είναι διαθέσιμη, το state είναι {"connected": false, "message": "Device state not available"}. Χωρίς έλεγχο ταυτότητας η απάντηση είναι HTTP 401 με {"error": "Authentication required"}.

Σημείωση

Οι τιμές στο readings είναι ακατέργαστες. Στο παράδειγμα, T: 2082 σημαίνει 20.82 °C. Ο ορισμός της οικογένειας λέει πώς μετατρέπετε κάθε τιμή. Δείτε τους ορισμούς οικογενειών παρακάτω.

Ορισμοί οικογενειών

Οι ορισμοί λένε ποιες μετρήσεις, εξόδους και ρυθμίσεις έχει κάθε οικογένεια. Δεν χρειάζονται έλεγχο ταυτότητας.

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	Το διάστημα σήματος ζωής σε δευτερόλεπτα

Το λεξικό readings δίνει για κάθε κωδικό μέτρησης την ονομασία, τη μονάδα και τη μετατροπή. Π.χ. η μέτρηση T έχει μονάδα °C και μετατροπή divide_by_100. Τον κατάλογο των μετρήσεων τον βλέπετε και στη σελίδα Μετρήσεις.

Η τιμή 2147483648 σημαίνει ότι η μέτρηση λείπει.

Χρονικό όριο

Ορίστε χρονικό όριο περίπου 30 δευτερόλεπτα στα αιτήματά σας.

Δείτε επίσης

• Λήψη ιστορικών δεδομένων
• Ζωντανά δεδομένα (WebSocket)
• MCP για AI assistants
• Εικονικές συσκευές