S'applique à : LOQED Touch et LOQED Pure.

Il s'agit d'un article de développeur avancé pour les API Web LOQED, les webhooks entrants et les événements de webhook sortants.

Les paramètres spécifiques à Touch Display tels que Open House Mode s'appliquent à LOQED Pure uniquement lorsque le LOQED Touch Display en option est installé.

Certaines plates-formes et appareils de maison intelligente n'ont pas encore d'intégration directe LOQED. Si vous êtes un utilisateur avancé ou un développeur, vous pouvez créer votre propre intégration à l'aide des API LOQED. Avant de commencer, nous vous recommandons de lire notre article "Utilisateurs avancés : API disponibles" d'abord.

LOQED propose trois façons d'intégrer votre serrure :

Webhooks sortants – laissez votre verrou notifier une URL externe chaque fois que son état change (par exemple, pour déclencher des automatisations).
Webhooks entrants – contrôlez votre serrure (ouverture, verrouillage, serrure de nuit) depuis un autre service ou appareil.
API d'intégrations – une API REST basée sur des jetons pour répertorier vos verrous, modifier l'état du verrou et modifier les paramètres de verrouillage tels que Open House Mode et Twist Assist.

Webhooks sortants : appeler une URL externe lorsque le verrouillage change

Lorsque le verrou atteint une nouvelle position (ouvert, déverrouillé/verrouillage de jour, verrouillage/verrouillage de nuit), le backend LOQED peut envoyer des données (POST) à une URL de votre choix. Vous pouvez enregistrer l'URL que vous souhaitez appeler dans le API section sur app.loqed.com (voir ci-dessous).

Étant donné que tous les systèmes ne prennent pas en charge JSON, vous pouvez également configurer une URL distincte par événement (par exemple une URL pour l'ouverture et une pour le verrouillage). Dans ce cas le état_demandé la valeur est toujours la même pour cette URL.

Charge utile de l'événement : état atteint

Cette charge utile est envoyée lorsque le verrou a atteint un poste. Exemple de JSON posté sur votre URL :

{
  "requested_state": "DAY_LOCK",
  "event_type": "STATE_CHANGED_LATCH",
  "lock_id": "Yq1gK4oeE9KWe0ByxjX2",
  "key_local_id": 3,
  "key_name_user": "Porte d'entrée",
  "key_name_admin": "Jane Doe",
  "key_account_e-mail": "jane@example.com",
  "key_account_name": "Jane Doe"
}

Champs

état_demandé – la position atteinte : OUVERT, DAY_LOCK, NUIT_LOCK ou INCONNU.
type_événement – l'un des :
- STATE_CHANGED_OPEN (requested_state = OUVERT)
- STATE_CHANGED_LATCH (état_demandé = DAY_LOCK)
- STATE_CHANGED_NIGHT_LOCK (requested_state = NIGHT_LOCK)
- STATE_CHANGED_UNKNOWN (état_demandé = INCONNU)
- MOTEUR_STALL (état_demandé = INCONNU)
lock_id – l’identifiant de votre serrure.
clé_local_id, nom_clé_utilisateur, nom_clé_admin – nul lorsque l'action n'a pas été déclenchée par une touche (par exemple une rotation manuelle du bouton ou un appui sur un bouton).
key_account_e-mail, nom_compte_clé – nul pour des actions manuelles ou lorsqu'un code PIN est utilisé qui n'est pas lié à un compte.

Charge utile de l'événement : accéder à un état

Vous pouvez également recevoir un webhook lorsque le verrou commence à bouger vers un nouveau poste. Le verrou peut ne pas atteindre la position (par exemple lorsque les piles sont presque vides). Ces événements fixent le aller_à_état attribut avec l’état du boulon cible.

{
  "go_to_state": "OUVERT",
  "event_type": "GO_TO_STATE_INSTANTOPEN_OPEN",
  "lock_id": "Yq1gK4oeE9KWe0ByxjX2",
  "key_local_id": 3,
  "key_name_user": "Porte d'entrée",
  "key_name_admin": "Jane Doe",
  "key_account_e-mail": "jane@example.com",
  "key_account_name": "Jane Doe"
}

Possible aller_à_état valeurs : OUVERT, DAY_LOCK, NUIT_LOCK.

Possible type_événement valeurs :

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)
GO_TO_STATE_MANUAL_UNLOCK_REMOTE_OPEN
GO_TO_STATE_MANUAL_LOCK_REMOTE_LATCH
GO_TO_STATE_MANUAL_LOCK_REMOTE_NIGHT_LOCK

Le lock_id et clé_* les champs se comportent de la même manière que décrit ci-dessus.

Webhook de force Bluetooth et Wi-Fi

Toutes les quelques heures, et chaque fois que la serrure ou le pont est sous tension, une mise à jour des niveaux de signal peut être envoyée. Cochez la case correspondante dans le API section sur app.loqed.com pour recevoir ces informations.

{
  "ble_strength": 42,
  "wifi_strength": 73,
  "batterie_pourcentage": 88,
  "lock_id": "Yq1gK4oeE9KWe0ByxjX2"
}

ble_strength – Signal Bluetooth en pourcentage. Cela fluctue beaucoup, alors ne vous inquiétez pas s'il est faible.
wifi_force – Signal Wi-Fi en pourcentage.
pourcentage_batterie – niveau de batterie en pourcentage.
lock_id – l’identifiant de votre serrure.

Verrouiller le webhook en ligne

Toutes les quelques heures, et chaque fois que la serrure ou le pont est sous tension, une mise à jour « en ligne » peut être envoyée. Cochez la case correspondante pour recevoir ces informations.

{
  "en ligne": 1,
  "lock_id": "Yq1gK4oeE9KWe0ByxjX2"
}

en ligne – 1 est envoyé comme valeur.
lock_id– l’identifiant de votre serrure.

Tester votre webhook

Nous vous recommandons d'utiliser Webhook.site pour vérifier que votre serrure intelligente appelle l'URL du webhook. Il vous permet également d'inspecter les données JSON envoyées.

Webhooks entrants : contrôler le verrouillage

Si vous souhaitez contrôler votre serrure depuis un service ou un appareil tiers, vous pouvez le faire avec un HTTPS OBTENIR demande à une URL LOQED.

Connectez-vous et ouvrez la section API

Ouvert app.loqed.com dans votre navigateur.
Connectez-vous avec l'adresse e-mail de votre compte LOQED app. Un code de vérification (2FA) sera envoyé à votre adresse e-mail – saisissez-le pour continuer.
Dans le menu, choisissez API. C’est ici que vous gérez vos webhooks et clés API sortants et entrants.

Créer une clé API

Sur cette page, vous pouvez ajouter des webhooks sortants et créer des webhooks entrants.

Cliquez Ajouter une nouvelle clé API.

Saisissez un nom afin de pouvoir reconnaître la clé plus tard. Cela peut être n'importe quoi – il n'est pas nécessaire qu'il corresponde au nom de votre clé.
Si vous disposez de plusieurs verrous, sélectionnez le bon dans la liste Sélectionnez Verrouiller liste déroulante.
Cliquez Ajouter une clé API.

Votre clé API est maintenant créée.

Appeler l'API

L'API prend actuellement en charge les commandes suivantes :

Ouvert – la porte s'ouvre. Un objet JSON vide est renvoyé.
Loquet – la porte est déverrouillée (verrouillage jour). Un objet JSON vide est renvoyé.
Verrouillage de nuit – la porte est verrouillée. Un objet JSON vide est renvoyé.
Statut – renvoie l'état actuel du verrou (voir ci-dessous).

⚠️Important : demander le Statut au maximum une fois par jour. Si vous le demandez plus de 12 fois, vous serez bloqué pendant 12 heures. Au lieu d'interroger l'état, configurez un webhook sortant Ainsi, votre serveur est informé instantanément chaque fois que l'état du verrouillage change.

Le Statut La commande renvoie le JSON suivant :

{
  "identifiant": "Yq1gK4oeE9KWe0ByxjX2",
  "bridge_online": 1,
  "lock_online": 1,
  "batterie_pourcentage": 88,
  "type_batterie": 0,
  "bolt_state_numeric": 2,
  "bolt_state": "day_lock",
  "guest_access_mode": 0,
  "twist_assist": 0,
  "touch_to_connect": 0
}

identifiant – identifiant de verrouillage.
pont_en ligne – 1 si le pont est en ligne, sinon 0.
lock_online – 1 si le verrou est en ligne, sinon 0.
pourcentage_batterie – -1 si le verrou est hors ligne, sinon 0–100.
type_de_batterie – 0 = alcalin, 1 = NiMH, 2 = Lithium (non rechargeable), 3 = inconnu.
bolt_state_numeric – 0 = inconnu, 1 = ouvert, 2= jour_lock, 3 = night_lock.
état_boulon – inconnu, ouvert, jour_lock ou nuit_lock.
mode_accès_invité – 1 si activé, 0 si désactivé.
twist_assist – 1 si activé, 0 si désactivé.
touch_to_connect – 1 si la restriction Touch to Open de 500 m est supprimée, sinon 0.

Laissez LOQED générer la signature numérique

Les commandes vers la serrure intelligente doivent être signées numériquement. L'option la plus simple est de laisser le serveur LOQED générer cette signature pour vous : utilisez simplement les quatre URL prêtes à l'emploi (open, latch, night lock, status) affichées dans le champ API section sur app.loqed.com.

Générez vous-même la signature numérique

Si vous préférez garder votre clé de cryptage pour vous et ne pas l'envoyer au serveur LOQED, vous pouvez générer vous-même la signature numérique. À Exemple app.loqed.com/Backend-API nous fournissons un exemple de code (JavaScript et PHP) qui montre comment la signature est créée.

API d'intégration : lire les verrous et modifier les paramètres

Le API d'intégrations est une API REST basée sur des jetons. Avec un seul jeton d'accès personnel, vous pouvez répertorier vos verrous, modifier l'état du verrou et modifier les paramètres de verrouillage tels que Open House Mode et Twist Assist.

L'URL de base de tous les points de terminaison est :

https://integrations.production.loqed.com

Chaque demande doit inclure votre jeton d'accès personnel dans le Autorisation en-tête :

Autorisation : Porteur YOUR_PERSONAL_ACCESS_TOKEN

Générer un jeton d'accès personnel

Ouvrez le Page de jeton d'accès personnel LOQED et suivez ces étapes :

Connectez-vous avec l'adresse email de votre compte LOQED app (vous devez être un administrateur).
Appuyez sur Créer.
Donnez au jeton un nom reconnaissable (par exemple le nom de l'intégration que vous créez).
Appuyez sur Enregistrer.
Copiez le jeton et stockez-le dans un endroit sûr – vous l'utiliserez comme Porteur jeton dans chaque demande. Traitez-le comme un mot de passe.

Listez vos serrures

Utilisez ce point de terminaison pour récupérer tous les verrous disponibles pour votre compte, y compris leur état et leurs paramètres actuels. Vous aurez besoin de la serrure identifiant pour les autres points de terminaison.

OBTENIR https://integrations.production.loqed.com/api/locks/

Exemple avec cURL :

curl -X GET "https://integrations.production.loqed.com/api/locks/" \
  -H "Autorisation : Porteur YOUR_PERSONAL_ACCESS_TOKEN"

Exemple de réponse :

{
  "données": [
    {
      "identifiant": "Yq1gK4oeE9KWe0ByxjX2",
      "name": "Porte d'entrée",
      "nom_modèle": "LOQED",
      "batterie_pourcentage": 95,
      "battery_type": "alcaline",
      "bolt_state": "day_lock",
      "party_mode": faux,
      "guest_access_mode": faux,
      "twist_assist": faux,
      "touch_to_connect": faux,
"lock_direction": "dans le sens inverse des aiguilles d'une montre",
      "mortise_lock_type": "cylinder_operated_no_handle_on_the_outside",
      "supported_lock_states": [
        "ouvrir",
        "jour_lock",
        "verrouillage_nuit"
      ]
    }
  ]
}

Changer l'état du verrouillage

Actionnez une serrure en appelant le état_boulon point final. Les états de boulons disponibles sont ouvert, jour_lock et nuit_lock.

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

Exemple avec cURL (déverrouillage vers le verrouillage journalier) :

curl -X GET "https://integrations.production.loqed.com/api/locks/Yq1gK4oeE9KWe0ByxjX2/bolt_state/day_lock" \
  -H "Autorisation : Porteur YOUR_PERSONAL_ACCESS_TOKEN"

Modifier un paramètre de verrouillage

Utilisez ce point de terminaison pour modifier un paramètre de verrouillage tel que Open House Mode, Twist Assist, le sens de verrouillage ou le fuseau horaire.

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

Envoyez un corps JSON avec le nom du paramètre et sa nouvelle valeur. Par exemple, pour activer Open House Mode:

{
  "setting_name": "open_house_mode",
  "setting_value": 1
}

À activer Twist Assist:

{
  "setting_name": "twist_assist",
  "setting_value": 1
}

Exemple complet avec cURL :

curl -X POST "https://integrations.production.loqed.com/api/locks/Yq1gK4oeE9KWe0ByxjX2/setting"\
  -H "Autorisation : Porteur YOUR_PERSONAL_ACCESS_TOKEN" \
  -H "Type de contenu : application/json" \
  -d '{"setting_name": "open_house_mode", "setting_value": 1}'

valeur_paramètre est un entier signé de 32 bits. La plupart des paramètres sont de simples bascules marche/arrêt qui acceptent 0 (éteint) et 1 (activé), mais certains attendent des valeurs spécifiques. Modifiez un paramètre à la fois et vérifiez le résultat sur votre serrure ou dans le LOQED app.

Paramètres disponibles

Les paramètres ci-dessous sont les bascules les plus couramment utilisées (0 = éteint, 1 = allumé) :

nom_paramètre	Ce que ça fait
`mode_maison_ouverte`	Maintient la porte dans la serrure de jour afin qu'elle puisse être ouverte avec la poignée sans la déverrouiller à chaque fois.
`twist_assist`	Donne au pêne une torsion supplémentaire pour aider à faire fonctionner les portes rigides.
`touch_to_connect`	Supprime l'exigence de barrière géographique de 500 m pour Touch to Open.
`touch_to_lock`	Verrouillez la porte en touchant l'extérieur de la serrure.
`hold_to_lock`	Verrouillez la porte en touchant et en maintenant l'extérieur de la serrure.

Astuce : pour confirmer que votre token fonctionne, envoyez un OBTENIR demander à https://integrations.production.loqed.com/api/locks/ avec votre Autorisation : Porteur en-tête. Une liste de vos verrous confirme que tout est correctement configuré.

Intégration de l'API Web LOQED