Zum Hauptinhalt springen

LOQED Web-API-Integration

Erweiterter Leitfaden für Entwickler: Sperrereignisse mit Webhooks empfangen, Ihre LOQED-Sperre steuern und Sperreinstellungen ändern.

Gilt für: LOQED Touch und LOQED Pure.

Dies ist ein fortgeschrittener Entwicklerartikel für LOQED-Web-APIs, eingehende Webhooks und ausgehende Webhook-Ereignisse.

Touch Display-spezifische Einstellungen wie Open House Mode gelten nur für LOQED Pure, wenn das optionale LOQED Touch Display installiert ist.

Einige Smart-Home-Plattformen und -Geräte verfügen noch nicht über eine direkte LOQED-Integration. Wenn Sie ein fortgeschrittener Benutzer oder Entwickler sind, können Sie mithilfe der LOQED-APIs Ihre eigene Integration erstellen. Bevor Sie beginnen, empfehlen wir Ihnen, unseren Artikel zu lesen „Fortgeschrittene Benutzer: Verfügbare APIs“ zuerst.

LOQED bietet drei Möglichkeiten zur Integration in Ihr Schloss:

  • Ausgehende Webhooks – Lassen Sie Ihr Schloss eine externe URL benachrichtigen, wenn sich ihr Status ändert (z. B. um Automatisierungen auszulösen).

  • Eingehende Webhooks – Steuern Sie Ihr Schloss (Öffnen, Riegel, Nachtschloss) von einem anderen Dienst oder Gerät aus.

  • Integrations-API – eine tokenbasierte REST-API zum Auflisten Ihrer Sperren, zum Ändern des Sperrstatus und zum Ändern von Sperreinstellungen wie z Open House Mode und Twist Assist.

Ausgehende Webhooks: Rufen Sie eine externe URL auf, wenn sich die Sperre ändert

Wenn das Schloss eine neue Position erreicht (offen, entsperrt/Tagessperre, Sperre/Nachtsperre), kann das LOQED-Backend Daten an eine URL Ihrer Wahl senden (POST). Sie können die URL, die aufgerufen werden soll, im registrieren API Abschnitt über app.loqed.com (siehe unten).

Da nicht alle Systeme JSON unterstützen, können Sie auch eine separate URL pro Ereignis konfigurieren (z. B. eine URL zum Öffnen und eine zum Sperren). In diesem Fall die angeforderter_Status Der Wert ist für diese URL immer gleich.

Ereignisnutzlast: Status erreicht

Diese Nutzlast wird gesendet, wenn die Sperre aktiviert ist erreicht eine Stelle. Beispiel für den JSON, der an Ihre URL gepostet wird:

{
  „requested_state“: „DAY_LOCK“,
  „event_type“: „STATE_CHANGED_LATCH“,
  „lock_id“: „Yq1gK4oeE9KWe0ByxjX2“,
  „key_local_id“: 3,
  „key_name_user“: „Haustür“,
  „key_name_admin“: „Jane Doe“,
  „key_account_e-mail“: „jane@example.com“,
  „key_account_name“: „Jane Doe“
}

Felder

  • angeforderter_Status – die erreichte Position: OFFEN, DAY_LOCK, NIGHT_LOCK oder UNBEKANNT.

  • event_type – einer von:

    • STATE_CHANGED_OPEN (requested_state = OFFEN)

    • STATE_CHANGED_LATCH (requested_state = DAY_LOCK)

    • STATE_CHANGED_NIGHT_LOCK (requested_state = NIGHT_LOCK)

    • STATE_CHANGED_UNKNOWN (requested_state = UNBEKANNT)

    • MOTOR_STALL (requested_state = UNBEKANNT)

  • lock_id – die Kennung Ihres Schlosses.

  • key_local_id, Schlüsselname_Benutzer, Schlüsselname_Administrator – null wenn die Aktion nicht durch eine Taste ausgelöst wurde (z. B. eine manuelle Drehung des Knopfes oder ein Tastendruck).

  • key_account_e-mail, key_account_name – null für manuelle Aktionen oder wenn eine PIN verwendet wird, die nicht mit einem Konto verknüpft ist.

Ereignisnutzlast: Gehen in einen Zustand

Sie können beim Sperren auch einen Webhook empfangen beginnt sich zu bewegen auf dem Weg zu einer neuen Position. Möglicherweise erreicht das Schloss die Position nicht wirklich (z. B. wenn die Batterien fast leer sind). Diese Ereignisse setzen die go_to_state Attribut mit dem Zielschraubenzustand.

{
  „go_to_state“: „ÖFFNEN“,
  „event_type“: „GO_TO_STATE_INSTANTOPEN_OPEN“,
  „lock_id“: „Yq1gK4oeE9KWe0ByxjX2“,
  „key_local_id“: 3,
  „key_name_user“: „Haustür“,
  „key_name_admin“: „Jane Doe“,
  „key_account_e-mail“: „jane@example.com“,
  „key_account_name“: „Jane Doe“
}

Möglich go_to_state Werte: OFFEN, DAY_LOCK, NIGHT_LOCK.

Möglich event_type Werte:

  • GO_TO_STATE_INSTANTOPEN_OPEN – Touch to Open (go_to_state = OFFEN)

  • GO_TO_STATE_INSTANTOPEN_LATCH – Automatisches Entsperren (go_to_state = DAY_LOCK)

  • GO_TO_STATE_MANUAL_UNLOCK_BLE_OPEN (go_to_state = OFFEN)

  • 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 = OFFEN)

  • 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 = OFFEN)

  • GO_TO_STATE_MANUAL_UNLOCK_VIA_OUTSIDE_MODULE_BUTTON (go_to_state = OFFEN)

  • GO_TO_STATE_TOUCH_TO_LOCK (go_to_state = NIGHT_LOCK)

  • GO_TO_STATE_MANUAL_UNLOCK_REMOTE_OPEN

  • GO_TO_STATE_MANUAL_LOCK_REMOTE_LATCH

  • GO_TO_STATE_MANUAL_LOCK_REMOTE_NIGHT_LOCK

Die lock_id und key_* Felder verhalten sich genauso wie oben beschrieben.

Bluetooth- und Wi-Fi-Stärke-Webhook

Alle paar Stunden und immer dann, wenn die Schleuse oder Brücke eingeschaltet wird, kann eine Aktualisierung der Signalpegel gesendet werden. Aktivieren Sie das entsprechende Häkchen im API Abschnitt über app.loqed.com um diese Informationen zu erhalten.

{
  „ble_strength“: 42,
  „wifi_strength“: 73,
  „battery_percentage“: 88,
  „lock_id“: „Yq1gK4oeE9KWe0ByxjX2“
}

  • ble_strength – Bluetooth-Signal in Prozent. Dieser schwankt stark, also machen Sie sich keine Sorgen, wenn er niedrig ist.

  • wifi_strength – Wi-Fi-Signal in Prozent.

  • Batterieprozentsatz – Batteriestand in Prozent.

  • lock_id – die Kennung Ihres Schlosses.

Online-Webhook sperren

Alle paar Stunden und immer dann, wenn das Schloss oder die Brücke eingeschaltet ist, kann ein „Online“-Update gesendet werden. Aktivieren Sie das entsprechende Häkchen, um diese Informationen zu erhalten.

{
  „online“: 1,
  „lock_id“: „Yq1gK4oeE9KWe0ByxjX2“
}

  • online – 1 wird als Wert gesendet.

  • lock_id– die Kennung Ihres Schlosses.

Testen Sie Ihren Webhook

Wir empfehlen die Verwendung Webhook.site um zu überprüfen, ob Ihr Smart Lock die Webhook-URL aufruft. Außerdem können Sie damit die gesendeten JSON-Daten überprüfen.

Eingehende Webhooks: Steuern Sie die Sperre

Wenn Sie Ihre Sperre von einem Drittanbieterdienst oder -gerät aus steuern möchten, können Sie dies mit einem HTTPS tun ERHALTEN Anfrage an eine LOQED-URL.

Melden Sie sich an und öffnen Sie den API-Bereich

  1. Offen app.loqed.com in Ihrem Browser.

  2. Melden Sie sich mit der E-Mail-Adresse Ihres LOQED app-Kontos an. Ein Bestätigungscode (2FA) wird an Ihre E-Mail-Adresse gesendet. Geben Sie ihn ein, um fortzufahren.

  3. Wählen Sie im Menü API. Hier verwalten Sie Ihre ausgehenden und eingehenden Webhooks und API-Schlüssel.

Erstellen Sie einen API-Schlüssel

Auf dieser Seite können Sie ausgehende Webhooks hinzufügen und eingehende Webhooks erstellen.

  • Klicken Sie Neuen API-Schlüssel hinzufügen.

  • Geben Sie einen Namen ein, damit Sie den Schlüssel später wiedererkennen können. Es kann alles sein – es muss nicht mit Ihrem Schlüsselnamen übereinstimmen.

  • Wenn Sie mehrere Schlösser haben, wählen Sie das richtige aus Wählen Sie Sperren Dropdown.

  • Klicken Sie API-Schlüssel hinzufügen.

Ihr API-Schlüssel wurde nun erstellt.

Rufen Sie die API auf

Die API unterstützt derzeit die folgenden Befehle:

  • Offen – die Tür öffnet sich. Es wird ein leeres JSON-Objekt zurückgegeben.

  • Riegel – Die Tür ist entriegelt (Tagesverriegelung). Es wird ein leeres JSON-Objekt zurückgegeben.

  • Nachtsperre – Die Tür ist verriegelt. Es wird ein leeres JSON-Objekt zurückgegeben.

  • Status – gibt den aktuellen Zustand der Sperre zurück (siehe unten).

⚠️ Wichtig: Fordern Sie die Status höchstens einmal pro Tag. Wenn Sie es mehr als 12 Mal anfordern, werden Sie für 12 Stunden gesperrt. Anstatt den Status abzufragen, richten Sie eine ein ausgehender Webhook So wird Ihr Server sofort benachrichtigt, wenn sich der Sperrstatus ändert.

Die Status Der Befehl gibt den folgenden JSON zurück:

{
  „id“: „Yq1gK4oeE9KWe0ByxjX2“,
  „bridge_online“: 1,
  „lock_online“: 1,
  „battery_percentage“: 88,
  "battery_type": 0,
  „bolt_state_numeric“: 2,
  „bolt_state“: „day_lock“,
  „guest_access_mode“: 0,
  „twist_assist“: 0,
  „touch_to_connect“: 0
}

  • ID – Schlosskennung.

  • bridge_online – 1 wenn die Brücke online ist, andernfalls 0.

  • lock_online – 1 wenn das Schloss online ist, andernfalls 0.

  • Batterieprozentsatz – -1 wenn die Sperre offline ist, andernfalls 0–100.

  • Batterietyp – 0 = alkalisch, 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 oder night_lock.

  • Guest_Access_Mode – 1 wenn aktiviert, 0 wenn deaktiviert.

  • twist_assist – 1 wenn aktiviert, 0 wenn deaktiviert.

  • touch_to_connect – 1 wenn die Touch to Open 500-m-Beschränkung aufgehoben wird, andernfalls 0.

Lassen Sie LOQED die digitale Signatur generieren

Befehle an das Smart Lock müssen digital signiert sein. Am einfachsten ist es, diese Signatur vom LOQED-Server für Sie generieren zu lassen: Verwenden Sie dazu einfach die vier vorgefertigten URLs (Open, Latch, Night Lock, Status), die im angezeigt werden API Abschnitt über app.loqed.com.

Erzeugen Sie die digitale Signatur selbst

Wenn Sie Ihren Verschlüsselungsschlüssel lieber für sich behalten und ihn nicht an den LOQED-Server senden möchten, können Sie die digitale Signatur selbst erstellen. Bei app.loqed.com/Backend-API-Beispiel Wir stellen Beispielcode (JavaScript und PHP) zur Verfügung, der zeigt, wie die Signatur erstellt wird.

Integrations-API: Sperren lesen und Einstellungen ändern

Die Integrations-API ist eine tokenbasierte REST-API. Mit einem einzigen persönlichen Zugriffstoken können Sie Ihre Schlösser auflisten, den Schlossstatus ändern und Schlosseinstellungen ändern, z Open House Mode und Twist Assist.

Die Basis-URL für alle Endpunkte lautet:

https://integrations.production.loqed.com

In jeder Anfrage muss Ihr persönliches Zugriffstoken enthalten sein Autorisierung Kopfzeile:

Autorisierung: Inhaber YOUR_PERSONAL_ACCESS_TOKEN

Generieren Sie ein persönliches Zugriffstoken

Öffnen Sie die LOQED persönliche Zugriffstoken-Seite und folgen Sie diesen Schritten:

  1. Melden Sie sich mit der E-Mail-Adresse Ihres LOQED app-Kontos an (Sie müssen ein sein Administrator).

  2. Tippen Sie auf Erstellen.

  3. Geben Sie dem Token einen erkennbaren Namen (z. B. den Namen der Integration, die Sie erstellen).

  4. Tippen Sie auf Speichern.

  5. Kopieren Sie den Token und bewahren Sie ihn an einem sicheren Ort auf – Sie werden ihn als verwenden Träger Token in jeder Anfrage. Behandeln Sie es wie ein Passwort.

Listen Sie Ihre Schlösser auf

Verwenden Sie diesen Endpunkt, um alle für Ihr Konto verfügbaren Sperren abzurufen, einschließlich ihres aktuellen Status und ihrer Einstellungen. Sie benötigen das Schloss ID für die anderen Endpunkte.

ERHALTEN SIE https://integrations.production.loqed.com/api/locks/

Beispiel mit cURL:

curl -X GET "https://integrations.production.loqed.com/api/locks/" \
  -H „Autorisierung: Inhaber YOUR_PERSONAL_ACCESS_TOKEN“

Beispielantwort:

{
  „Daten“: [
    {
      „id“: „Yq1gK4oeE9KWe0ByxjX2“,
      „name“: „Haustür“,
      „model_name“: „LOQED“,
      „battery_percentage“: 95,
      „battery_type“: „alkaline“,
      „bolt_state“: „day_lock“,
      „party_mode“: false,
      „guest_access_mode“: false,
      „twist_assist“: false,
      „touch_to_connect“: false,
„lock_direction“: „gegen den Uhrzeigersinn“,
      „mortise_lock_type“: „zylinder_operated_no_handle_on_the_outside“,
      „supported_lock_states“: [
        „offen“,
        „day_lock“,
        „night_lock“
      ]
    }
  ]
}

Ändern Sie den Sperrstatus

Betätigen Sie eine Sperre, indem Sie die aufrufen Bolt_state Endpunkt. Die verfügbaren Schraubenzustände sind offen, day_lock und night_lock.

ERHALTEN SIE https://integrations.production.loqed.com/api/locks/{lockId}/bolt_state/{boltState}

Beispiel mit cURL (Entsperren zur Tagessperre):

curl -X GET "https://integrations.production.loqed.com/api/locks/Yq1gK4oeE9KWe0ByxjX2/bolt_state/day_lock" \
  -H „Autorisierung: Inhaber YOUR_PERSONAL_ACCESS_TOKEN“

Ändern Sie eine Sperreinstellung

Verwenden Sie diesen Endpunkt, um eine Sperreinstellung zu ändern, z Open House Mode, Twist Assist, die Schließrichtung oder die Zeitzone.

POST https://integrations.production.loqed.com/api/locks/{lockId}/setting

Senden Sie einen JSON-Text mit dem Einstellungsnamen und seinem neuen Wert. Zum Beispiel, um Aktivieren Sie Open House Mode:

{
  „setting_name“: „open_house_mode“,
  „setting_value“: 1
}

Zu Aktivieren Sie Twist Assist:

{
  „setting_name“: „twist_assist“,
  „setting_value“: 1
}

Vollständiges Beispiel mit cURL:

curl -X POST "https://integrations.production.loqed.com/api/locks/Yq1gK4oeE9KWe0ByxjX2/setting" \
  -H „Autorisierung: Inhaber YOUR_PERSONAL_ACCESS_TOKEN“ \
  -H „Inhaltstyp: application/json“ \
  -d '{"setting_name": "open_house_mode", "setting_value": 1}'

Einstellungswert ist eine vorzeichenbehaftete 32-Bit-Ganzzahl. Bei den meisten Einstellungen handelt es sich um einfache Ein-/Aus-Schalter, die akzeptiert werden 0 (aus) und 1 (ein), aber einige erwarten bestimmte Werte. Ändern Sie jeweils eine Einstellung und überprüfen Sie das Ergebnis auf Ihrem Schloss oder im LOQED app.

Verfügbare Einstellungen

Die folgenden Einstellungen sind die am häufigsten verwendeten Umschalter (0 = aus, 1 = ein):

Einstellungsname

Was es bewirkt

open_house_mode

Hält die Tür in der Tagesverriegelung, sodass sie jedes Mal mit dem Griff geöffnet werden kann, ohne dass sie entriegelt werden muss.

twist_assist

Verleiht dem Riegel eine zusätzliche Drehung, um die Betätigung steifer Türen zu erleichtern.

touch_to_connect

Entfernt die 500-m-Geofence-Anforderung für Touch to Open.

touch_to_lock

Verriegeln Sie die Tür, indem Sie die Außenseite des Schlosses berühren.

hold_to_lock

Verriegeln Sie die Tür, indem Sie die Außenseite des Schlosses berühren und festhalten.

Tipp: Um zu bestätigen, dass Ihr Token funktioniert, senden Sie eine ERHALTEN Anfrage an https://integrations.production.loqed.com/api/locks/ mit deinem Autorisierung: Inhaber Kopfzeile. Eine Liste Ihrer Schlösser bestätigt, dass alles korrekt eingerichtet ist.

Verwandte Artikel
LOQED verfügbare APIs
LOQED lokale Bridge-API-Integration
Loxone- und LOQED-Integration
Home Assistant- und LOQED-Integration
Domoticz- und LOQED-Integration
Hat dies deine Frage beantwortet?