Gilt für: LOQED Touch und LOQED Pure.
Dies ist ein fortgeschrittener Entwicklerartikel für lokale Netzwerkintegrationen und ausgehende Webhooks.
Die lokale Bridge-API ist hauptsächlich Bridge-orientiert. Überprüfen Sie bei LOQED Pure- oder Gateway-basierten Setups die aktuelle API-Verfügbarkeit, bevor Sie eine neue Integration erstellen.
Bei einigen Smart-Home-Plattformen oder -Geräten verfügt LOQED über keine direkte Integration. Wenn Sie ein fortgeschrittener Benutzer sind, können Sie Ihre Integration mithilfe der LOQED-API entwickeln. Lesen Sie unbedingt zuerst unseren Artikel „Fortgeschrittene Benutzer: Verfügbare APIs“.
Beim Öffnen/Verriegeln der Tür eine URL aufrufen (ausgehender Webhook)
Wenn sich der Status des Schlosses ändert (offen, entsperrt, gesperrt) und für andere Informationen (Batterieprozentsatz, Online-Status), kann LOQED Bridge eine URL aufrufen (Daten an diese senden). Nachfolgend finden Sie, welche Daten als JSON an diese URL gesendet werden. Sie können auch GET-Parameter der URL hinzufügen, indem Sie den JSON-Schlüssel zwischen „[“ und „]“ festlegen. Zum Beispiel: https://your.server.nl/script?yourstate=[requested_state]. Sie können auch auswählen, bei welchen Änderungen ein Webhook-Aufruf ausgelöst werden soll (z. B. können Sie festlegen, dass eine URL nur dann aufgerufen wird, wenn die Tür verschlossen ist).
Die folgenden JSON-Schlüssel werden immer gesendet:
mac_wifi: enthält die Wi-Fi MAC-Adresse der Bridge. Dies hilft, die Brücke zu identifizieren. Der Multicast-DNS-Name der Bridge enthält diese Adresse ebenfalls.
mac_ble: enthält die Bluetooth MAC-Adresse der Bridge.
Zustand erreicht
Nachdem der Motor nicht mehr läuft, werden die folgenden JSON-Schlüssel für die Auslöser gesendet trigger_state_changed_open, trigger_state_changed_latch, trigger_state_changed_night_lock, trigger_state_changed_unknown:
angeforderter_Status
OFFEN
DAY_LOCK
NIGHT_LOCK
UNBEKANNT
event_type
STATE_CHANGED_OPEN (requested_state = OPEN)
STATE_CHANGED_LATCH (requested_state = DAY_LOCK)
STATE_CHANGED_NIGHT_LOCK (requested_state = NIGHT_LOCK)
STATE_CHANGED_UNKNOWN (requested_state = UNKNOWN)
MOTOR_STALL (requested_state = UNKNOWN)
STATE_CHANGED_OPEN_REMOTE (requested_state = OPEN)
STATE_CHANGED_LATCH_REMOTE (requested_state = DAY_LOCK)
STATE_CHANGED_NIGHT_LOCK_REMOTE (requested_state = NIGHT_LOCK)
GO_TO_STATE_TOUCH_TO_LOCK (requested_state = NIGHT_LOCK)
key_local_id (null, wenn z. B. manuelles Öffnen per Knopf oder Drücken der Taste). Enthält die KeyID, die den Zustand des Schlosses geändert hat.
In einen Staat gehen
Wenn sich das Schloss in eine neue Position bewegt (z. B. erreicht es die Position möglicherweise nicht, wenn die Batterien fast leer sind), werden die folgenden JSON-Schlüssel für die Auslöser gesendet trigger_state_goto_open, trigger_state_goto_latch, trigger_state_goto_night_lock:
go_to_state
OFFEN
DAY_LOCK
NIGHT_LOCK
event_type
GO_TO_STATE_INSTANTOPEN_OPEN (Touch to Open) (go_to_state = OPEN)
GO_TO_STATE_INSTANTOPEN_LATCH (Automatisches Entsperren) (go_to_state = DAY_LOCK)
GO_TO_STATE_MANUAL_UNLOCK_BLE_OPEN (go_to_state = OPEN)
GO_TO_STATE_MANUAL_LOCK_BLE_LATCH (go_to_state = DAY_LOCK)
GO_TO_STATE_MANUAL_LOCK_BLE_NIGHT_LOCK (go_to__state = NIGHT_LOCK)
GO_TO_STATE_TWIST_ASSIST_OPEN (go_to_state = OPEN)
GO_TO_STATE_TWIST_ASSIST_LATCH (go_to_state = DAY_LOCK)
GO_TO_STATE_TWIST_ASSIST_LOCK (go_to_state = NIGHT_LOCK)
GO_TO_STATE_MANUAL_UNLOCK_VIA_OUTSIDE_MODULE_PIN (go_to_state = OPEN)
GO_TO_STATE_MANUAL_UNLOCK_VIA_OUTSIDE_MODULE_BUTTON (go_to_state = OPEN)
GO_TO_STATE_TOUCH_TO_LOCK (go_to_state = NIGHT_LOCK)
key_local_id (255 bedeutet unbekannt, z. B. manuelles Öffnen per Knopf oder Drücken der Taste)
Batterieprozentsatz
Wenn das Schloss den aktuellen Batterieprozentsatz sendet (alle paar Stunden), werden die folgenden JSON-Schlüssel für den Auslöser gesendet trigger_battery:
Batterietyp (0 = Alkaline, 1 = NiMH, 2 = Lithium (nicht wiederaufladbar), 3 = unbekannt)
Batterieprozentsatz
Online-Status
Wenn das Schloss die Verbindung zur Bridge verliert, werden die folgenden JSON-Schlüssel für den Auslöser gesendet trigger_online_status:
wifi_strength (aktuell in dB, bald wird sich dies in einen Prozentsatz ändern)
ble_strength (derzeit in dB, bald wird sich dies in einen Prozentsatz ändern. -1 bedeutet, dass die Sperre nicht verbunden ist)
Überprüfen Sie, ob die Webhook-Anfrage vom LOQED Bridge stammt
Sie könnten sensible Maßnahmen ergreifen, wenn sich die Tür öffnet (z. B. das Licht einschalten, den Alarm ausschalten, die Heizung einschalten). Daher müssen Sie sicherstellen, dass unter der von Ihnen angegebenen URL keine anderen Geräte solche Aktionen auslösen können. Sie können:
Stellen Sie sicher, dass keine anderen Geräte die URL aufrufen können, indem Sie die IP nur auf die IP-Adresse des LOQED Bridge beschränken. Stellen Sie außerdem sicher, dass sich die Bridge-IP-Adresse nicht ändert, indem Sie dies im DHCP-Dienst Ihres Routers festlegen.
Überprüfen Sie die in den Headern des Webhook-Aufrufs gesendete Hash-Signatur. Im Header finden Sie TIMESTAMP (8 Bytes) und HASH (hex). Sie können den Hash selbst berechnen, indem Sie sha256(BODY + TIMESTAMP + base64_decode(bridge_authentication_key) ausführen. Den Bridge-Authentifizierungsschlüssel finden Sie unter https://app.loqed.com/API-Config. Der BODY ist der unveränderte Text, der mit der Anfrage empfangen wurde (mit dem gesamten JSON-Code). Vergessen Sie auch nicht zu überprüfen, ob der Zeitstempel nur wenige Sekunden von der tatsächlichen Zeit entfernt ist, um Replay-Angriffe zu verhindern.
Mit unserem Tool können Sie einen Webhook auf der Bridge auflisten, hinzufügen und löschen
Der einfachste Weg, Webhooks aufzulisten, hinzuzufügen oder zu löschen, ist die Verwendung unseres Javascript-Tools:
Melden Sie sich an https://app.loqed.com/API-Config
Scrollen Sie zur Überschrift „Ausgehende Webhooks über LOQED Bridge“
Klicken Sie neben der richtigen Bridge auf die Schaltfläche „Webhooks hinzufügen/löschen“. Das Tool wird geöffnet und Ihre Bridge-IP-Adresse und Ihr Authentifizierungsschlüssel sind vorab ausgefüllt.
Listen Sie mit Ihrem Code einen Webhook auf der Bridge auf, fügen Sie ihn hinzu und löschen Sie ihn
Wenn Sie Benutzern Ihres Produkts die Verbindung mit LOQED erleichtern möchten, können Sie die Webhooks auch über die Bridge-API einrichten. Nachfolgend werden die API-Endpunkte beschrieben. Wenn Sie ein Beispiel suchen, können Sie sich den Code des oben genannten Javascript-Tools ansehen. Der LOQED Bridge kann mithilfe von mDNS in Ihrer Anwendung gefunden werden (versuchen Sie es beispielsweise mit „DNS-sd -B _http._tcp“ unter Windows).
Für alle /webhooks-Webservermethoden sind zwei Header obligatorisch:
TIMESTAMP: enthält den aktuellen Zeitstempel
HASH – sha256-Hash-String
Die Hash-Berechnung ist für jede Art von Anfrage spezifisch und im entsprechenden Abschnitt beschrieben. Um den Hash berechnen zu können, benötigen Sie den Authentifizierungsschlüssel der Bridge. Diesen Schlüssel finden Sie nach der Anmeldung unter https://app.loqed.com/API-Config. Es gibt keine andere Möglichkeit, diesen Schlüssel abzurufen.
Webhooks auflisten
ERHALTEN: https://bridge-ip-address/webhooks
Der HASH im Header muss formatiert sein: SHA256(TIMESTAMP + LOCK_TOKEN), wobei TIMESTAMP eine 8-Byte-Zahl und LOCK_TOKEN der Sicherheitsschlüssel der Base64-dekodierten (!) Bridge ist (der Schlüssel auf der Seite webhooks.loqed.com ist in Base64). Der HASH sollte hexadezimal sein.
Gibt ein JSON-Array mit Schlüsseln zurück:
'id': 1 (int)
'trigger_state_changed_open': 0/1
'trigger_state_changed_latch': 0/1
'trigger_state_changed_night_lock': 0/1
'trigger_state_changed_unknown': 0/1
'trigger_state_goto_open': 0/1
'trigger_state_goto_latch': 0/1
'trigger_state_goto_night_lock': 0/1
'trigger_battery': 0/1
'trigger_online_status': 0/1
Gibt HTTP-Codes zurück:
Gibt den HTTP 400 BAD REQUEST-Code und die Zeichenfolge mit Beschreibung zurück, falls Header ungültig sind oder nicht gefunden werden
Geben Sie HTTP 401 UNAUTHORIZED zurück, wenn die Authentifizierung fehlgeschlagen ist
Webhook erstellen
POST: http://Bridge-IP-Adresse/webhooks
Textkörper: JSON mit Schlüsseln:
'trigger_state_changed_open': 0/1
'trigger_state_changed_latch': 0/1
'trigger_state_changed_night_lock': 0/1
'trigger_state_changed_unknown': 0/1
'trigger_state_goto_open': 0/1
'trigger_state_goto_latch': 0/1
'trigger_state_goto_night_lock': 0/1
'trigger_battery': 0/1
'trigger_online_status': 0/1
Der HASH im Header muss formatiert sein: SHA256(URL + Trigger_Bitmap + TIMESTAMP + LOCK_TOKEN), URL ist eine Zeichenfolge, Trigger_Bitmap 4 Bytes, TIMESTAMP ist eine 8 Bytes lange Zahl und LOCK_TOKEN ist der Sicherheitsschlüssel der Base64-dekodierten (!) Bridge (der Schlüssel auf der Seite webhooks.loqed.com ist in Base64). Der HASH sollte hexadezimal sein. Die trigger_bitmap enthält die Trigger. Beispielsweise ist 0x000F (15 Dezimalstellen) binär 0000 0000 0000 1010, was bedeutet, dass die folgenden Trigger aktiviert sind:
„trigger_state_changed_open“:0
„trigger_state_changed_latch“:1
„trigger_state_changed_night_lock“:0
„trigger_state_changed_unknown“:1
„trigger_state_goto_open“:0
„trigger_state_goto_latch“:0
„trigger_state_goto_night_lock“:0
„trigger_battery“:0
„trigger_online_status“:0
Wir haben auch ein kleines PHP-Snippet, das zeigt, wie ein Webhook erstellt wird, Sie können es hier herunterladen.
Rückgaben:
HTTP 200 OK-Code und String mit Beschreibung im Falle einer erfolgreichen Webhook-Erstellung
HTTP 400 BAD REQUEST-Code und String mit Beschreibung für den Fall, dass JSON für die Webhook-Erstellung nicht gültig ist
HTTP 400 BAD REQUEST-Code und String mit Beschreibung für den Fall, dass Header ungültig sind oder nicht gefunden werden
HTTP 401 UNAUTHORIZED, wenn die Authentifizierung fehlgeschlagen ist
HTTP 500 INTERNER SERVER-FEHLER-Code und Zeichenfolge mit Beschreibung für den Fall, dass ein Webhook mit dieser URL bereits vorhanden ist
HTTP 500 INTERNER SERVER-FEHLER-Code und String mit Beschreibung für den Fall, dass die maximale Anzahl an Webhooks erreicht wird
Webhook löschen
LÖSCHEN: http://Bridge-IP-Adresse/webhooks/{webhookId}
Der HASH im Header muss formatiert sein: SHA256(id + TIMESTAMP + LOCK_TOKEN), ID ist eine 8-Byte-Zahl, TIMESTAMP ist eine 8-Byte-Zahl und LOCK_TOKEN ist der Sicherheitsschlüssel der Base64-dekodierten (!) Bridge (der Schlüssel auf der Seite webhooks.loqed.com ist in Base64). Der HASH sollte hexadezimal sein.
Rückgaben:
HTTP 200 OK-Code und String mit Beschreibung im Falle einer erfolgreichen Webhook-Löschung
HTTP 400 BAD REQUEST-Code und String mit Beschreibung für den Fall, dass Header ungültig sind oder nicht gefunden werden
HTTP 401 UNAUTHORIZED, wenn die Authentifizierung fehlgeschlagen ist
HTTP 404 NOT FOUND-Code und String mit Beschreibung für den Fall, dass der Webhook mit {webhookId} nicht gefunden wurde
HTTP 500 INTERNAL SERVER ERROR Code und String mit Beschreibung für den Fall, dass beim Löschen ein Fehler aufgetreten ist
Testen
Wir empfehlen die Verwendung Webhook.site wenn Sie überprüfen möchten, ob Ihr Smart Lock/Ihre Smart Bridge die Webhook-URL aufruft. Dort können Sie auch die JSON-Daten sehen.
Tür öffnen/verriegeln, wenn etwas passiert (eingehender Webhook)
Wenn Sie Ihre Sperre von einem Drittanbieterdienst oder -gerät aus steuern möchten, können Sie dies über einen HTTPS-GET-Aufruf an Ihre LOQED Bridge-URL tun.
Erstellen eines API-Schlüssels
Zuerst müssen Sie einen neuen Schlüssel für Ihr LOQED Smart Lock erstellen.
Öffnen Sie die Seite https://app.loqed.com/API-Config.
Melden Sie sich mit Ihrer E-Mail-Adresse und Ihrem Passwort an, mit denen Sie sich beim LOQED app anmelden.
Klicken Sie auf „Neuen API-Schlüssel hinzufügen“.
Geben Sie zur leichteren Identifizierung einen Namen ein. Das kann alles sein, was Ihnen gefällt.
Wenn Sie über mehrere Schlösser verfügen, können Sie im Dropdown-Menü direkt neben „Schloss auswählen“ das richtige Schloss auswählen.
Klicken Sie auf „API-Schlüssel hinzufügen“.
Sie haben nun den API-Schlüssel erstellt.
Rufen Sie die API auf
Derzeit unterstützt die API die folgenden Befehle:
Öffnen (Schloss öffnet sich und kehrt dann in die Verriegelung zurück. Wird nur bei Türen ohne Griff an der Außenseite unterstützt). Es wird ein leeres JSON-Objekt zurückgegeben.
Riegel (entriegelt). Es wird ein leeres JSON-Objekt zurückgegeben.
Nachtsperre (gesperrt). Es wird ein leeres JSON-Objekt zurückgegeben.
Status. ACHTUNG: Wir empfehlen, den Status nur einmal täglich abzufragen, um die Belastung der Brücke möglichst gering zu halten. Anstatt nach dem Status zu fragen, sollten Sie einen Webhook implementieren, der Ihren Server aufruft, sodass Sie sofort eine Benachrichtigung erhalten, sobald sich der Sperrstatus ändert. Es gibt die folgenden JSON-Schlüssel zurück:
mac_wifi (Sperrerkennung)
mac_bluetooth
lock_online (1, wenn die Sperre online ist, sonst 0)
batterie_prozentsatz (-1, wenn die Sperre offline ist, andernfalls 0 - 100)
Batterietyp (0 = Alkaline, 1 = NiMH, 2 = Lithium (nicht wiederaufladbar), 3 = unbekannt)
Bolt_state_numeric (0 = unbekannt, 1 = offen, 2 = Day_lock, 3 = Night_lock)
Bolt_state (unbekannt, offen, day_lock, night_lock)
Lassen Sie die LOQED-Bridge die digitale Signatur generieren
Befehle an das Smart Lock müssen digital signiert werden. Am einfachsten ist es, diese Signatur von der LOQED-Bridge generieren zu lassen. Verwenden Sie einfach die vier bereitgestellten URLs (Offen, Riegel, Nachtsperre, Status), die auf webhooks.loqed.com angezeigt werden. Beachten Sie, dass die HTTP-Verbindung zur Bridge nicht gesichert ist, sodass andere Personen in Ihrem lokalen Netzwerk möglicherweise den Verschlüsselungsschlüssel abrufen könnten. Wenn Sie Befehle sicher versenden möchten, müssen Sie die digitale Signatur selbst erstellen.
Erzeugen Sie die digitale Signatur selbst
Bei https://app.loqed.com/Bridge-API-example/ Wir stellen Beispielcode (Javascript und PHP) zur Verfügung, der zeigt, wie die digitale Signatur erstellt wird. Sie können diese Methode nur verwenden, wenn Sie Ihr Plugin für das Smart-Home-System erstellen können, mit dem Sie eine Verbindung herstellen möchten. Die benötigten Daten (IP, Secret, KeyID) finden Sie unter https://app.loqed.com/API-Config nachdem Sie auf die Schaltfläche „Anzeigen/Bearbeiten“ neben dem API-Schlüssel geklickt haben.