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" first.

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 Mode portes ouvertes et Assistance à la torsion.

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 requested_state 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": "Front door",
  "key_name_admin": "Jane Doe",
  "key_account_e-mail": "jane@example.com",
  "key_account_name": "Jane Doe"
}

Champs

requested_state – la position atteinte : OPEN, DAY_LOCK, NIGHT_LOCK ou UNKNOWN.
event_type – 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)
- MOTOR_STALL (état_demandé = INCONNU)
lock_id – l’identifiant de votre serrure.
key_local_id, key_name_user, key_name_admin – null 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, key_account_name – null 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 go_to_state attribut avec l'état du boulon cible.

{
  "go_to_state": "OPEN",
  "event_type": "GO_TO_STATE_INSTANTOPEN_OPEN",
  "lock_id": "Yq1gK4oeE9KWe0ByxjX2",
  "key_local_id": 3,
  "key_name_user": "Front door",
  "key_name_admin": "Jane Doe",
  "key_account_e-mail": "jane@example.com",
  "key_account_name": "Jane Doe"
}

Possible go_to_state valeurs: OPEN, DAY_LOCK, NIGHT_LOCK.

Possible event_type valeurs:

GO_TO_STATE_INSTANTOPEN_OPEN – Touchez pour ouvrir (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 key_* les champs se comportent de la même manière que décrit ci-dessus.

Webhook de puissance 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,
  "battery_percentage": 88,
  "lock_id": "Yq1gK4oeE9KWe0ByxjX2"
}

ble_strength – Signal Bluetooth en pourcentage. Cela fluctue beaucoup, alors ne vous inquiétez pas s'il est faible.
wifi_strength – Signal Wi-Fi en pourcentage.
battery_percentage – 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.

{
  "online": 1,
  "lock_id": "Yq1gK4oeE9KWe0ByxjX2"
}

online – 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 GET demande à une URL LOQED.

Connectez-vous et ouvrez la section API

Ouvrir app.loqed.com dans votre navigateur.
Connectez-vous avec l'adresse e-mail de votre compte d'application LOQED. 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 dropdown.
Cliquez Ajouter une clé API.

Votre clé API est maintenant créée.

Appeler l'API

L'API prend actuellement en charge les commandes suivantes :

Ouvrir – 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 :

{
  "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 – identifiant de verrouillage.
bridge_online – 1 si le pont est en ligne, sinon 0.
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 = alcalin, 1 = NiMH, 2 = Lithium (non rechargeable), 3 = inconnu.
bolt_state_numeric – 0 = inconnu, 1 = ouvert, 2 = jour_lock, 3 = night_lock.
bolt_state – unknown, open, day_lock ou night_lock.
guest_access_mode – 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 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. À app.loqed.com/Backend-API-example 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 Mode portes ouvertes et Assistance à la torsion.

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 Authorization en-tête :

Authorization: Bearer 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 e-mail de votre compte d'application LOQED (vous devez être un administrateur).
Robinet Créer.
Donnez au jeton un nom reconnaissable (par exemple le nom de l'intégration que vous créez).
Robinet Sauvegarder.
Copiez le jeton et stockez-le dans un endroit sûr – vous l'utiliserez comme Bearer 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 id pour les autres points de terminaison.

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

Exemple avec cURL :

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

Exemple de réponse :

{
  "data": [
    {
      "id": "Yq1gK4oeE9KWe0ByxjX2",
      "name": "Front door",
      "model_name": "LOQED Touch",
      "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": "counter_clockwise",
      "mortise_lock_type": "cylinder_operated_no_handle_on_the_outside",
      "supported_lock_states": [
        "open",
        "day_lock",
        "night_lock"
      ]
    }
  ]
}

Changer l'état du verrouillage

Actionnez une serrure en appelant le bolt_state point final. Les états de boulons disponibles sont open, day_lock et night_lock.

GET 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 "Authorization: Bearer YOUR_PERSONAL_ACCESS_TOKEN"

Modifier un paramètre de verrouillage

Utilisez ce point de terminaison pour modifier un paramètre de verrouillage tel que Mode portes ouvertes, Assistance à la torsion, 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 le mode portes ouvertes:

{
  "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 "Authorization: Bearer YOUR_PERSONAL_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"setting_name": "open_house_mode", "setting_value": 1}'

setting_value 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 l'application LOQED.

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
`open_house_mode`	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.

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

Intégration de l'API Web LOQED