API Documentation: device

Περιγραφή

Αποστολή εντολής σε συσκευή (π.χ. ON/OFF, ρύθμιση setpoint θερμοστάτη, reset) μέσω της πλατφόρμας Globismart Smart City Platform. Το endpoint προωθεί την εντολή στο αντίστοιχο κανάλι επικοινωνίας (π.χ. MQTT) και επιστρέφει αποτέλεσμα αποδοχής/εκτέλεσης.

Η επιτυχής HTTP απόκριση (202 Accepted) δηλώνει ότι η εντολή έγινε δεκτή για εκτέλεση, όχι απαραίτητα ότι ολοκληρώθηκε στη συσκευή.

Base URL & Μέθοδος

POST [base_url]/api/device_command.php

Αναμένει Content-Type: application/json.

Body Παράμετροι (JSON)

Πεδίο	Τύπος	Υποχρεωτικό	Περιγραφή
key	String	Ναι	API key για εξουσιοδότηση.
device_id	Integer	Ναι*	ID συσκευής (*ή εναλλακτικά `external_id`).
external_id	String	Όχι	Εξωτερικό αναγνωριστικό συσκευής.
command	String	Ναι	Όνομα εντολής (π.χ. `power`, `set_temperature`, `mode`).
params	Object	Όχι	Παράμετροι εντολής (π.χ. `{"value": true}`, `{"temperature": 22}`).
qos	Integer	Όχι	Ποιότητα υπηρεσίας (0,1,2) για MQTT δημοσίευση.
retain	Boolean	Όχι	Αν θα γίνει retained publish (MQTT).
correlation_id	String	Όχι	Αναγνωριστικό συσχέτισης για audit/tracking.
timeout_ms	Integer	Όχι	Χρονικό όριο αναμονής απάντησης από τη συσκευή.

Παράδειγμα Αίτησης

POST /api/device_command.php
Host: [base_url]
Content-Type: application/json

{
  "key": "MY_SECRET_API_KEY",
  "device_id": 5021,
  "command": "set_temperature",
  "params": { "temperature": 22 },
  "qos": 1,
  "retain": false,
  "correlation_id": "9e7c1c48-8b5b-4f8a-839c-1a0fd6f6f0a2",
  "timeout_ms": 5000
}

Παράδειγμα Απόκρισης (202 Accepted)

{
  "status": "accepted",
  "device_id": 5021,
  "command": "set_temperature",
  "queued_at": "2025-08-08T12:50:00Z",
  "correlation_id": "9e7c1c48-8b5b-4f8a-839c-1a0fd6f6f0a2"
}

Εάν υπάρχει συγχρονική απάντηση από τη συσκευή εντός timeout_ms, μπορεί να επιστραφεί result ή ack με λεπτομέρειες.

Πιθανά Σφάλματα

HTTP Code	Περιγραφή	Παράδειγμα
400	Μη έγκυρες παράμετροι	{ "status": "error", "error": "invalid_payload" }
401	Μη εξουσιοδοτημένη πρόσβαση	{ "status": "error", "error": "unauthorized" }
404	Συσκευή δεν βρέθηκε	{ "status": "error", "error": "device_not_found" }
408	Λήξη χρονικού ορίου αναμονής	{ "status": "error", "error": "timeout" }
409	Σύγκρουση κατάστασης/εντολής	{ "status": "error", "error": "conflict" }
500	Εσωτερικό σφάλμα	{ "status": "error", "error": "server_error" }

Παράδειγμα curl

curl -X POST "[base_url]/api/device_command.php" \
  -H "Content-Type: application/json" \
  -d '{
        "key": "MY_SECRET_API_KEY",
        "device_id": 5021,
        "command": "power",
        "params": {"value": true},
        "qos": 1,
        "retain": false
      }'