Avec certaines plateformes ou appareils de maison intelligente, LOQED n'a pas d'intégration directe. Si tu es un utilisateur avancé, tu peux développer ton intégration en utilisant l'API LOQED. Assure-toi de lire notre article "Utilisateurs avancés : Les API disponibles" d'abord.
Lorsque la porte est ouverte/verrouillée, appelle une URL (webhook sortant)
Lorsque l'état de la serrure change (ouvert, déverrouillé, verrouillé) et pour d'autres informations (pourcentage de la batterie, état en ligne), le LOQED Bridge peut appeler (POST des données vers) une URL. Tu trouveras ci-dessous les données qui sont POSTées en JSON à cette URL. Tu peux aussi ajouter les paramètres GET de l'URL en définissant la clé JSON entre "[" et "]". Par exemple : https://your.server.nl/script?yourstate= [requested_state ]. Tu peux aussi choisir pour quels changements un appel de webhook doit être déclenché (par exemple, tu peux choisir d'appeler une URL uniquement lorsque la porte est verrouillée).
Les clés JSON suivantes sont toujours envoyées :
mac_wifi : contient l'adresse MAC Wi-Fi du pont. Cela permet d'identifier le pont. Le nom DNS multicast du pont contient également cette adresse.
mac_ble : contient l'adresse MAC Bluetooth du pont.
État atteint
Après l'arrêt du moteur, les clés JSON ci-dessous sont envoyées pour les déclencheurs trigger_state_changed_open, trigger_state_changed_latch, trigger_state_changed_night_lock, trigger_state_changed_unknown: .
requested_state
OUVRIR
DAY_LOCK
NIGHT_LOCK
INCONNU
Type d'événement
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_TO_LOCK (requested_state = NIGHT_LOCK)
key_local_id (null si par ex. ouverture manuelle par le bouton ou en appuyant sur le bouton). Il contient l'ID de la clé qui a modifié l'état du verrou.
Aller dans un état
Lorsque le verrou passe à une nouvelle position (il pourrait ne pas atteindre la position si les piles sont presque vides, par exemple), les clés JSON ci-dessous sont envoyées pour les déclencheurs trigger_state_goto_open, trigger_state_goto_latch, trigger_state_goto_night_lock: .
Go_to_state
OUVRIR
DAY_LOCK
NIGHT_LOCK
Type d'événement
GO_TO_STATE_INSTANTOPEN_OPEN ( Toucher pour ouvrir ) (go_to_state = OPEN)
GO_TO_STATE_INSTANTOPEN_LATCH ( Déverrouillage automatique ) (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 signifie inconnu, par ex. ouverture manuelle par le bouton ou en appuyant sur le bouton)
Pourcentage de la batterie
Lorsque le verrou envoie le pourcentage actuel de la batterie (toutes les quelques heures), les clés JSON ci-dessous sont envoyées pour le déclencheur trigger_battery: .
battery_type (0 = Alcaline, 1 = NiMH, 2 = Lithium (non rechargeable), 3 = inconnu)
pourcentage de la batterie
Statut en ligne
Lorsque le verrou perd la connexion avec le pont, les clés JSON ci-dessous sont envoyées pour le déclencheur trigger_online_status: .
wifi_strength (actuellement en dB, bientôt cela deviendra un pourcentage)
ble_strength (actuellement en dB, bientôt cela changera en pourcentage. -1 signifie que la serrure n'est pas connectée)
Vérifie si la demande de webhook provient du pont LOQED
Tu pourrais prendre des mesures sensibles si la porte s'ouvre (par exemple, allumer les lumières, éteindre l'alarme, allumer le chauffage). Tu dois donc t'assurer que sur l'URL que tu as fournie, aucun autre appareil ne peut déclencher de telles actions. You can:
Assure-toi qu'aucun autre appareil ne peut appeler l'URL en limitant l'IP uniquement à l'adresse IP de LOQED Bridge. Assure-toi également que l'adresse IP du pont ne change pas en la fixant dans le service DHCP de ton routeur.
Vérifie la signature de hachage envoyée dans les en-têtes de l'appel webhook. Dans l'en-tête, tu trouves TIMESTAMP (8 octets) et HASH (hex). Tu peux calculer le hachage toi-même en faisant sha256(BODY + TIMESTAMP + base64_decode(bridge_authentication_key). La clé d'authentification du pont se trouve sur https://app.loqed.com/API-Config . Le BODY est le corps non modifié reçu avec la demande (avec tout le code JSON). N'oublie pas non plus de valider si l'horodatage est à quelques secondes près de l'heure réelle, pour éviter les attaques par rejeu.
Liste, ajoute et supprime un webhook sur le pont en utilisant notre outil
Le moyen le plus simple de répertorier, ajouter ou supprimer des webhooks est d'utiliser notre outil Javascript :
Connecte-toi sur https://app.loqed.com/API-Config
Fais défiler jusqu'au titre "Webhooks sortants via LOQED Bridge".
Clique sur le bouton "Ajouter/Supprimer les webhooks" à côté du pont correct. L'outil s'ouvre et l'adresse IP de ton pont et la clé d'authentification sont préremplies.
Liste, ajoute et supprime un webhook sur le pont en utilisant ton code
Si tu veux qu'il soit plus facile pour les utilisateurs de ton produit de le connecter à LOQED, tu peux aussi utiliser l'API passerelle pour configurer les webhooks. Les points de terminaison de l'API sont décrits ci-dessous. Tu peux regarder le code de l'outil Javascript mentionné ci-dessus si tu cherches un exemple. Tu peux trouver le pont LOQED en utilisant mDNS dans ton application (essaie "DNS-sd -B _http._tcp" sous Windows par exemple).
Pour toutes les méthodes de serveur Web /webhooks, deux en-têtes sont obligatoires :
TIMESTAMP : contient l'horodatage actuel
HASH - chaîne de hachage sha256
Le calcul du hachage est spécifique à chaque type de demande et décrit dans la section correspondante. Tu as besoin de la clé d'authentification du pont pour pouvoir calculer le hachage. Tu trouveras cette clé après t'être connecté à https://app.loqed.com/API-Config . Il n'y a pas d'autre moyen de récupérer cette clé.
GET :
Renvoie un tableau JSON avec les clés :
'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
Renvoie les codes HTTP :
Renvoie le code HTTP 400 BAD REQUEST et la chaîne de caractères avec la description au cas où les en-têtes ne sont pas valides ou ne sont pas trouvés.
Renvoie HTTP 401 UNAUTHORIZED si l'authentification a échoué
POST:
'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
Le HASH dans l'en-tête doit être formaté : SHA256(URL + trigger_bitmap + TIMESTAMP + LOCK_TOKEN), URL est une chaîne de caractères, trigger_bitmap 4 octets, TIMESTAMP est un nombre de 8 octets, et LOCK_TOKEN est la clé de sécurité du pont décodée en base64 ( !) (la clé sur la page webhooks.loqed.com est en base64). Le HASH doit être en hexagone. Le trigger_bitmap contient les déclencheurs. Par exemple, 0x000F (15 en décimal) correspond à 0000 0000 0000 1010 en binaire, ce qui signifie que les déclencheurs suivants sont activés :
"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
Nous avons également un petit extrait de PHP qui montre comment créer un webhook, tu peux le télécharger ici .
Retours :
Code HTTP 200 OK et chaîne avec description en cas de création réussie du webhook
Code HTTP 400 BAD REQUEST et chaîne de caractères avec description dans le cas où JSON n'est pas valide pour la création du webhook.
Code HTTP 400 BAD REQUEST et chaîne de caractères avec description au cas où les en-têtes ne sont pas valides ou ne sont pas trouvés.
HTTP 401 UNAUTHORIZED si l'authentification a échoué
Code HTTP 500 INTERNAL SERVER ERROR et chaîne de caractères avec description dans le cas où le webhook avec cette URL existe déjà.
Code HTTP 500 INTERNAL SERVER ERROR et chaîne de caractères avec description en cas d'atteinte du nombre MAX de webhooks
DELETE :
Retours :
Code HTTP 200 OK et chaîne avec description en cas de suppression réussie du webhook
Code HTTP 400 BAD REQUEST et chaîne de caractères avec description au cas où les en-têtes ne sont pas valides ou ne sont pas trouvés.
HTTP 401 UNAUTHORIZED si l'authentification a échoué
Code HTTP 404 NOT FOUND et chaîne de caractères avec description dans le cas où le webhook avec {webhookId} n'a pas été trouvé.
Code HTTP 500 INTERNAL SERVER ERROR et chaîne de caractères avec description en cas d'erreur pendant la suppression
Tester
Nous te recommandons d'utiliser Webhook.site si tu veux vérifier que ta serrure/pont intelligent appelle l'URL du Webhook. Tu pourras aussi y voir les données JSON.
Ouvre/verrouille la porte quand quelque chose se passe (webhook entrant)
Si tu veux contrôler ta serrure à partir d'un service ou d'un appareil tiers, tu peux le faire par le biais d'un appel GET HTTPS à ton URL LOQED Bridge.
Créer une clé d'API
Tout d'abord, tu dois créer une nouvelle clé sur ton LOQED Touch Smart Lock.
Ouvre la page https://app.loqed.com/API-Config .
Connecte-toi en utilisant ton adresse e-mail et le mot de passe que tu utilises pour te connecter à l'application LOQED.
Clique sur "Ajouter une nouvelle clé API".
Saisis un nom pour faciliter l'identification. Cela peut être tout ce que tu veux.
Si tu as plusieurs verrous, tu peux sélectionner le bon verrou dans le menu déroulant juste à côté de "Sélectionner le verrou".
Clique sur "Ajouter une clé API".
Tu as maintenant créé la clé API.
Appelle l'API
Actuellement, l'API prend en charge les commandes suivantes :
Ouvrir (la serrure s'ouvre, puis revient au loquet. Uniquement supporté sur les portes sans poignée à l'extérieur). Un objet JSON vide est renvoyé.
Le loquet (déverrouillé). Un objet JSON vide est renvoyé.
Verrouillage de nuit (verrouillé). Un objet JSON vide est renvoyé.
Statut. ATTENTION : nous te recommandons de ne demander le statut qu'une fois par jour, afin de limiter au maximum la charge sur le pont. Au lieu de demander l'état, tu devrais mettre en place un webhook qui appelle ton serveur, afin de recevoir une notification instantanée dès que l'état du verrou change. Il renvoie les clés JSON suivantes :
mac_wifi (identification de la serrure)
mac_bluetooth
lock_online (1 si le verrou est en ligne, sinon 0)
battery_percentage (-1 si le verrou est hors ligne, sinon 0 - 100)
battery_type (0 = Alcaline, 1 = NiMH, 2 = Lithium (non rechargeable), 3 = inconnu)
bolt_state_numeric (0 = inconnu, 1 = ouvert, 2 = day_lock, 3 = night_lock)
État_du_boulon (inconnu, ouvert, day_lock, night_lock)
Laisse le pont LOQED générer la signature numérique
Les commandes envoyées à la serrure intelligente doivent être signées numériquement. Le plus simple est de laisser le pont LOQED générer cette signature. Il suffit d'utiliser les quatre URL fournies (ouvert, verrouillé, verrouillé la nuit, état) affichées sur webhooks.loqed.com. Note que la connexion HTTP au pont n'est pas sécurisée, donc d'autres personnes sur ton réseau local pourraient potentiellement récupérer la clé de chiffrement. Si tu veux envoyer des commandes en toute sécurité, tu dois générer toi-même la signature numérique.
Génère toi-même la signature numérique
Sur https://app.loqed.com/Bridge-API-example/ nous fournissons un exemple de code (Javascript et PHP) qui montre comment la signature numérique est créée. Tu ne peux utiliser cette méthode que si tu peux créer ton plugin pour le système de maison intelligente auquel tu veux te connecter. Les données dont tu as besoin (IP, secret, KeyID) se trouvent sur https://app.loqed.com/API-Config après avoir cliqué sur le bouton "View / Edit" à côté de la clé API.