S'applique à : LOQED Touch et LOQED Pure.
Il s'agit d'un article de développeur avancé pour les intégrations de réseaux locaux et les webhooks sortants.
L'API du pont local est principalement orientée Bridge. Pour les configurations LOQED Pure ou basées sur une passerelle, vérifiez la disponibilité actuelle de l'API avant de créer une nouvelle intégration.
Avec certaines plates-formes ou appareils de maison intelligente, LOQED n'a pas d'intégration directe. Si vous êtes un utilisateur avancé, vous pouvez développer votre intégration en utilisant l'API LOQED. Assurez-vous de lire d'abord notre article « Utilisateurs avancés : API disponibles ».
Lorsque la porte est ouverte/verrouillée, appelez une URL (webhook sortant)
Lorsque l'état du verrou change (ouvert, déverrouillé, verrouillé) et pour d'autres informations (pourcentage de batterie, état en ligne), le LOQED Bridge peut appeler (données POST vers) une URL. Vous trouverez ci-dessous les données publiées au format JSON sur cette URL. Vous pouvez également 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]. Vous pouvez également choisir pour quelles modifications un appel webhook doit être déclenché (par exemple, vous pouvez choisir de n'appeler une URL que 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 aide à identifier le pont. Le nom DNS multicast du pont contient également cette adresse.
mac_ble : contient l'adresse MAC Bluetooth du pont.
État atteint
Une fois le moteur arrêté de fonctionner, 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 :
état_demandé
OUVERT
DAY_LOCK
NUIT_LOCK
INCONNU
type_événement
STATE_CHANGED_OPEN (requested_state = OUVERT)
STATE_CHANGED_LATCH (requested_state = DAY_LOCK)
STATE_CHANGED_NIGHT_LOCK (requested_state = NIGHT_LOCK)
STATE_CHANGED_UNKNOWN (requested_state = INCONNU)
MOTOR_STALL (requested_state = INCONNU)
STATE_CHANGED_OPEN_REMOTE (requested_state = OUVERT)
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 si par exemple ouverture manuelle par bouton ou en appuyant sur un bouton). Celui-ci contient le KeyID qui a modifié l'état du verrou.
Aller dans un état
Lorsque le verrou se dirige vers une nouvelle position (il se peut qu'il n'atteigne pas 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 :
aller_à_état
OUVERT
DAY_LOCK
NUIT_LOCK
type_événement
GO_TO_STATE_INSTANTOPEN_OPEN (Touch to Open) (go_to_state = OUVERT)
GO_TO_STATE_INSTANTOPEN_LATCH (Déverrouillage automatique) (go_to_state = DAY_LOCK)
GO_TO_STATE_MANUAL_UNLOCK_BLE_OPEN (go_to_state = OUVERT)
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 = OUVERT)
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 = OUVERT)
GO_TO_STATE_MANUAL_UNLOCK_VIA_OUTSIDE_MODULE_BUTTON (go_to_state = OUVERT)
GO_TO_STATE_TOUCH_TO_LOCK (go_to_state = NIGHT_LOCK)
key_local_id (255 signifie inconnu, par exemple ouverture manuelle par bouton ou en appuyant sur un bouton)
Pourcentage de 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 déclencheur_batterie :
type_batterie (0 = alcaline, 1 = NiMH, 2 = lithium (non rechargeable), 3 = inconnu)
pourcentage_batterie
Statut en ligne
Lorsque le verrou perd la connexion au pont, les clés JSON ci-dessous sont envoyées pour le déclencheur trigger_online_status :
wifi_strength (actuellement en dB, cela passera bientôt en pourcentage)
ble_strength (actuellement en dB, cela changera bientôt en pourcentage. -1 signifie que le verrou n'est pas connecté)
Vérifiez si la demande de webhook provient du LOQED Bridge
Vous pourriez prendre des mesures sensibles si la porte s'ouvre (par exemple, allumer les lumières, éteindre l'alarme, allumer le chauffage). Par conséquent, vous devez vous assurer que sur l'URL que vous avez fournie, aucun autre appareil ne peut déclencher de telles actions. Vous pouvez :
Assurez-vous qu'aucun autre appareil ne peut appeler l'URL en limitant l'adresse IP uniquement à l'adresse IP du LOQED Bridge. Assurez-vous également que l'adresse IP du pont ne change pas en la fixant dans le service DHCP de votre routeur.
Vérifiez la signature de hachage envoyée dans les en-têtes de l'appel webhook. Dans l'en-tête, vous trouvez TIMESTAMP (8 octets) et HASH (hex). Vous pouvez calculer le hachage vous-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 inchangé reçu avec la requête (avec tout le code JSON). N'oubliez pas non plus de valider si l'horodatage est à quelques secondes de l'heure réelle, pour éviter les attaques par rejeu.
Répertoriez, ajoutez et supprimez un webhook sur le pont à l'aide de notre outil
Le moyen le plus simple de répertorier, ajouter ou supprimer des webhooks consiste à utiliser notre outil Javascript :
Connectez-vous sur https://app.loqed.com/API-Config
Faites défiler jusqu'à la rubrique « Webhooks sortants via LOQED Bridge »
Cliquez sur le bouton « Ajouter/Supprimer des webhooks » à côté du bon pont. L'outil s'ouvrira et l'adresse IP de votre pont et la clé d'authentification seront pré-remplies.
Répertoriez, ajoutez et supprimez un webhook sur le pont à l'aide de votre code
Si vous souhaitez permettre aux utilisateurs de votre produit de le connecter plus facilement à LOQED, vous pouvez également utiliser l'API du pont pour configurer les webhooks. Ci-dessous, les points de terminaison de l'API sont décrits. Vous pouvez consulter le code de l'outil Javascript mentionné ci-dessus si vous cherchez un exemple. Le LOQED Bridge peut être trouvé en utilisant mDNS dans votre application (essayez "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 requête et décrit dans la section correspondante. Vous avez besoin de la clé d'authentification du pont pour pouvoir calculer le hachage. Cette clé peut être trouvée après vous être connecté à https://app.loqed.com/API-Config. Il n'existe aucun autre moyen de récupérer cette clé.
Répertorier les webhooks
OBTENIR : https://bridge-ip-address/webhooks
Le HASH dans l'en-tête doit être formaté : SHA256 (TIMESTAMP + LOCK_TOKEN), où TIMESTAMP est un nombre de 8 octets et LOCK_TOKEN est la clé de sécurité du pont décodé en base64 (!) (la clé sur la page webhooks.loqed.com est en base64). Le HASH doit être en hexadécimal.
Renvoie un tableau JSON avec des clés :
'id' : 1 (entier)
'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 avec la description au cas où les en-têtes seraient invalides ou introuvables
Renvoie HTTP 401 UNAUTHORIZED si l'authentification échoue
Créer un webhook
POSTE : http://adresse IP du pont/webhooks
Corps : JSON avec clés :
'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), l'URL est une chaîne, trigger_bitmap 4 octets, TIMESTAMP est un nombre de 8 octets et LOCK_TOKEN est la clé de sécurité du pont décodé en base64 (!) (la clé sur la page webhooks.loqed.com est en base64). Le HASH doit être en hexadécimal. Le trigger_bitmap contient les déclencheurs. Par exemple, 0x000F (15 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
"batterie_déclencheur":0
"trigger_online_status":0
Nous avons également un petit extrait PHP qui montre comment un webhook est créé, vous pouvez le télécharger ici.
Retours :
Code HTTP 200 OK et chaîne avec description en cas de création réussie d'un webhook
Code HTTP 400 BAD REQUEST et chaîne avec description au cas où JSON ne serait pas valide pour la création de webhook
Code HTTP 400 BAD REQUEST et chaîne avec description au cas où les en-têtes seraient invalides ou introuvables
HTTP 401 NON AUTORISÉ si l'authentification a échoué
Code d'ERREUR DU SERVEUR INTERNE HTTP 500 et chaîne avec description au cas où un webhook avec cette URL existe déjà
Code d'ERREUR DU SERVEUR INTERNE HTTP 500 et chaîne avec description au cas où le nombre MAX de webhooks serait atteint
Supprimer le webhook
SUPPRIMER : http://adresse IP du pont/webhooks/{webhookId}
Le HASH dans l'en-tête doit être formaté : SHA256 (id + TIMESTAMP + LOCK_TOKEN), ID est un nombre de 8 octets, TIMESTAMP est un nombre de 8 octets et LOCK_TOKEN est la clé de sécurité du pont décodé en base64 (!) (la clé sur la page webhooks.loqed.com est en base64). Le HASH doit être en hexadécimal.
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 avec description au cas où les en-têtes seraient invalides ou introuvables
HTTP 401 NON AUTORISÉ si l'authentification a échoué
Code HTTP 404 NON TROUVÉ et chaîne avec description au cas où le webhook avec {webhookId} n'aurait pas été trouvé
Code d'ERREUR DU SERVEUR INTERNE HTTP 500 et chaîne avec description au cas où une erreur se produirait lors de la suppression
Tests
Nous vous recommandons d'utiliser Webhook.site si vous souhaitez vérifier que votre serrure/pont intelligent appelle l'URL du Webhook. Vous pourrez également y voir les données JSON.
Ouvrir/verrouiller la porte lorsque quelque chose se produit (webhook entrant)
Si vous souhaitez contrôler votre serrure à partir d'un service ou d'un appareil tiers, vous pouvez le faire via un appel HTTPS GET vers votre URL LOQED Bridge.
Création d'une clé API
Tout d'abord, vous devez créer une nouvelle clé sur votre serrure intelligente LOQED.
Ouvrir la page https://app.loqed.com/API-Config.
Connectez-vous en utilisant votre adresse e-mail et le mot de passe que vous utilisez pour vous connecter au LOQED app.
Cliquez sur "Ajouter une nouvelle clé API".
Entrez un nom pour une identification facile. Cela peut être tout ce que vous voulez.
Si vous disposez de plusieurs verrous, vous pouvez sélectionner le bon verrou dans le menu déroulant juste à côté de « Sélectionner le verrou ».
Cliquez sur "Ajouter une clé API".
Vous avez maintenant créé la clé API.
Appeler l'API
Actuellement, l'API prend en charge les commandes suivantes :
Ouvert (la serrure s'ouvre, puis revient au loquet. Uniquement pris en charge sur les portes sans poignée à l'extérieur). Un objet JSON vide est renvoyé.
Loquet (déverrouillé). Un objet JSON vide est renvoyé.
Serrure de nuit (verrouillée). Un objet JSON vide est renvoyé.
Statut. ATTENTION : nous vous recommandons de ne demander le statut qu'une fois par jour, afin de minimiser la charge sur le pont. Au lieu de demander l'état, vous devez implémenter un webhook qui appelle votre serveur, afin de recevoir une notification instantanée dès que l'état du verrouillage change. Il renvoie les clés JSON suivantes :
mac_wifi (identification du verrou)
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)
type_batterie (0 = alcaline, 1 = NiMH, 2 = lithium (non rechargeable), 3 = inconnu)
bolt_state_numeric (0 = inconnu, 1 = ouvert, 2 = day_lock, 3 = night_lock)
bolt_state (inconnu, ouvert, day_lock, night_lock)
Laissez le pont LOQED générer la signature numérique
Les commandes vers la serrure intelligente doivent être signées numériquement. Le plus simple est de laisser le pont LOQED générer cette signature. Utilisez simplement les quatre URL fournies (ouvert, verrou, verrouillage de nuit, statut) affichées sur webhooks.loqed.com. Notez que la connexion HTTP au pont n'est pas sécurisée, donc d'autres personnes sur votre réseau local pourraient potentiellement récupérer la clé de cryptage. Si vous souhaitez envoyer des commandes en toute sécurité, vous devez générer vous-même la signature numérique.
Générez vous-même la signature numérique
À 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. Vous ne pouvez utiliser cette méthode que si vous pouvez créer votre plugin pour le système de maison intelligente auquel vous souhaitez vous connecter. Les données dont vous avez besoin (IP, secret, KeyID) se trouvent sur https://app.loqed.com/API-Config après avoir cliqué sur le bouton "Afficher / Modifier" à côté de la clé API.