Sommige smart home-platforms en -apparaten hebben nog geen directe LOQED-integratie. Als u een gevorderde gebruiker of ontwikkelaar bent, kunt u uw eigen integratie bouwen met behulp van de LOQED API's. Voordat u begint, raden wij u aan ons artikel te lezen "Geavanceerde gebruikers: beschikbare API's" first.

LOQED biedt drie manieren om te integreren met uw slot:

Uitgaande webhooks – laat uw slot een externe URL waarschuwen wanneer de status ervan verandert (bijvoorbeeld om automatiseringen te activeren).
Inkomende webhooks – bedien uw slot (open, dagslot, nachtslot) vanaf een andere dienst of apparaat.
Integraties-API – een op tokens gebaseerde REST API om uw sloten weer te geven, de vergrendelingsstatus te wijzigen en vergrendelingsinstellingen te wijzigen, zoals Open Huis-modus En Draaihulp.

Uitgaande webhooks: roep een externe URL aan wanneer het slot verandert

Wanneer het slot een nieuwe positie bereikt (open, ontgrendel/dagslot, slot/nachtslot) kan de LOQED backend (POST) data naar een URL naar keuze sturen. U kunt de URL waarmee u gebeld wilt worden registreren in het API sectie op app.loqed.com (zie hieronder).

Omdat niet alle systemen JSON ondersteunen, kun je ook per gebeurtenis een aparte URL configureren (bijvoorbeeld één URL voor openen en één voor vergrendelen). In dat geval de requested_state waarde is altijd hetzelfde voor die URL.

Payload van gebeurtenis: status bereikt

Deze payload wordt verzonden wanneer het slot dat heeft bereikt een positie. Voorbeeld van de JSON die naar uw URL wordt gepost:

{
  "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"
}

Velden

requested_state – de positie die werd bereikt: OPEN, DAY_LOCK, NIGHT_LOCK of UNKNOWN.
event_type – een van:
- 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 = ONBEKEND)
- MOTOR_STALL (requested_state = ONBEKEND)
lock_id – de identificatie van uw slot.
key_local_id, key_name_user, key_name_admin – null wanneer de actie niet door een toets werd geactiveerd (bijvoorbeeld het handmatig draaien van de knop of het indrukken van een knop).
key_account_e-mail, key_account_name – null voor handmatige acties of wanneer een pincode wordt gebruikt die niet aan een account is gekoppeld.

Payload van gebeurtenis: naar een staat gaan

Ook kunt u bij het slot een webhook ontvangen begint te bewegen naar een nieuwe positie. Het kan zijn dat het slot de stand niet daadwerkelijk bereikt (bijvoorbeeld als de batterijen bijna leeg zijn). Deze gebeurtenissen bepalen de go_to_state attribuut met de doelboutstatus.

{
  "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"
}

Mogelijk go_to_state waarden: OPEN, DAY_LOCK, NIGHT_LOCK.

Mogelijk event_type waarden:

GO_TO_STATE_INSTANTOPEN_OPEN – Raak aan om te openen (go_to_state = OPEN)
GO_TO_STATE_INSTANTOPEN_LATCH – Automatisch ontgrendelen (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)
GO_TO_STATE_MANUAL_UNLOCK_REMOTE_OPEN
GO_TO_STATE_MANUAL_LOCK_REMOTE_LATCH
GO_TO_STATE_MANUAL_LOCK_REMOTE_NIGHT_LOCK

De lock_id En key_* velden gedragen zich hetzelfde als hierboven beschreven.

Webhook met Bluetooth- en Wi-Fi-sterkte

Elke paar uur en telkens wanneer de sluis of brug wordt ingeschakeld, kan een update van de signaalniveaus worden verzonden. Schakel het overeenkomstige vinkje in het API sectie op app.loqed.com om deze informatie te ontvangen.

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

ble_strength – Bluetooth-signaal als percentage. Dit fluctueert sterk, dus maak je geen zorgen als het laag is.
wifi_strength – Wi-Fi-signaal als percentage.
battery_percentage – batterijniveau als percentage.
lock_id – de identificatie van uw slot.

Online webhook vergrendelen

Elke paar uur, en telkens wanneer de sluis of brug wordt ingeschakeld, kan er een "online" update worden verzonden. Schakel het bijbehorende vinkje in om deze informatie te ontvangen.

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

online – 1 wordt als waarde verzonden.
lock_id – de identificatie van uw slot.

Uw webhook testen

Wij raden aan om te gebruiken Webhook.site om te verifiëren dat uw slimme slot de webhook-URL aanroept. Hiermee kunt u ook de verzonden JSON-gegevens inspecteren.

Inkomende webhooks: beheer het slot

Als u uw slot wilt bedienen vanaf een service of apparaat van derden, kunt u dit doen met een HTTPS GET verzoek naar een LOQED-URL.

Log in en open de API-sectie

Open app.loqed.com in uw browser.
Log in met het e-mailadres van uw LOQED app-account. Er wordt een verificatiecode (2FA) naar uw e-mailadres verzonden. Voer deze in om door te gaan.
Kies in het menu API. Hier beheert u uw uitgaande en inkomende webhooks en API-sleutels.

Maak een API-sleutel

Op deze pagina kunt u uitgaande webhooks toevoegen en inkomende webhooks aanmaken.

Klik Voeg een nieuwe API-sleutel toe.

Voer een naam in, zodat u de sleutel later kunt herkennen. Het kan van alles zijn – het hoeft niet overeen te komen met uw sleutelnaam.
Als u meerdere sloten heeft, selecteert u de juiste uit de Selecteer Vergrendelen dropdown.
Klik API-sleutel toevoegen.

Uw API-sleutel is nu aangemaakt.

Roep de API aan

De API ondersteunt momenteel de volgende opdrachten:

Open – de deur gaat open. Er wordt een leeg JSON-object geretourneerd.
Vergrendeling – de deur is ontgrendeld (dagslot). Er wordt een leeg JSON-object geretourneerd.
Nachtslot – de deur is op slot. Er wordt een leeg JSON-object geretourneerd.
Status – geeft de huidige status van het slot terug (zie hieronder).

⚠️ Belangrijk: vraag de Status maximaal één keer per dag. Als u het meer dan 12 keer aanvraagt, wordt u voor 12 uur geblokkeerd. In plaats van de status op te vragen, kunt u een uitgaande webhook zodat uw server onmiddellijk op de hoogte wordt gesteld wanneer de vergrendelingsstatus verandert.

De Status opdracht retourneert de volgende JSON:

{
  "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 – slot-ID.
bridge_online – 1 als de bridge online is, anders 0.
lock_online – 1 als het slot online is, anders 0.
battery_percentage – -1 als het slot offline is, anders 0–100.
battery_type – 0 = Alkalisch, 1 = NiMH, 2 = Lithium (niet oplaadbaar), 3 = onbekend.
bolt_state_numeric – 0 = onbekend, 1 = geopend, 2 = dagslot, 3 = nachtslot.
bolt_state – unknown, open, day_lock of night_lock.
guest_access_mode – 1 indien ingeschakeld, 0 indien uitgeschakeld.
twist_assist – 1 indien ingeschakeld, 0 indien uitgeschakeld.
touch_to_connect – 1 als de Touch to Open 500 m-beperking wordt verwijderd, anders 0.

Laat LOQED de digitale handtekening genereren

Commando's naar het slimme slot moeten digitaal worden ondertekend. De eenvoudigste optie is om de LOQED-server deze handtekening voor u te laten genereren: gebruik eenvoudigweg de vier kant-en-klare URL's (open, grendel, nachtslot, status) die worden weergegeven in de API sectie op app.loqed.com.

Genereer zelf de digitale handtekening

Als u uw encryptiesleutel liever voor uzelf houdt en niet naar de LOQED-server verzendt, kunt u zelf de digitale handtekening genereren. Bij app.loqed.com/Backend-API-example we bieden voorbeeldcode (JavaScript en PHP) die laat zien hoe de handtekening wordt gemaakt.

Integraties API: sloten lezen en instellingen wijzigen

De Integraties-API is een op tokens gebaseerde REST API. Met één persoonlijk toegangstoken kunt u uw sloten weergeven, de vergrendelingsstatus wijzigen en vergrendelingsinstellingen wijzigen, zoals Open Huis-modus En Draaihulp.

De basis-URL voor alle eindpunten is:

https://integrations.production.loqed.com

Bij elk verzoek moet uw persoonlijke toegangstoken in de Authorization koptekst:

Authorization: Bearer YOUR_PERSONAL_ACCESS_TOKEN

Genereer een persoonlijk toegangstoken

Open de LOQED persoonlijke toegangstokenpagina en volg deze stappen:

Log in met het e-mailadres van uw LOQED app-account (u moet een beheerder).
Kraan Creëren.
Geef het token een herkenbare naam (bijvoorbeeld de naam van de integratie die je bouwt).
Kraan Redden.
Kopieer het token en bewaar het op een veilige plek. U gebruikt het als het Bearer token in elk verzoek. Behandel het als een wachtwoord.

Maak een lijst van uw sloten

Gebruik dit eindpunt om alle vergrendelingen op te halen die beschikbaar zijn voor uw account, inclusief hun huidige status en instellingen. Je hebt het slot nodig id voor de andere eindpunten.

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

Voorbeeld met cURL:

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

Voorbeeld antwoord:

{
  "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"
      ]
    }
  ]
}

Wijzig de vergrendelingsstatus

Bedien een slot door te bellen naar de bolt_state eindpunt. De beschikbare boutstatussen zijn open, day_lock En night_lock.

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

Voorbeeld met cURL (ontgrendelen naar dagslot):

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

Wijzig een vergrendelingsinstelling

Gebruik dit eindpunt om een vergrendelingsinstelling te wijzigen, zoals Open Huis-modus, Draaihulp, de sluitrichting of de tijdzone.

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

Stuur een JSON-hoofdtekst met de naam van de instelling en de nieuwe waarde ervan. Bijvoorbeeld naar schakel de Open Huis-modus in:

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

Naar Schakel Twist Assist in:

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

Volledig voorbeeld met 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 is een 32-bits geheel getal met teken. De meeste instellingen zijn eenvoudige aan/uit-schakelaars die accepteren 0 (uit) en 1 (aan), maar sommigen verwachten specifieke waarden. Wijzig één instelling tegelijk en controleer het resultaat op uw slot of in de LOQED-app.

Beschikbare instellingen

De onderstaande instellingen zijn de meest gebruikte schakelaars (0 = uit, 1 = aan):

instellingsnaam	Wat het doet
`open_house_mode`	Houdt de deur op slot, zodat deze met de handgreep kan worden geopend zonder telkens te ontgrendelen.
`twist_assist`	Geeft de grendel een extra draai om stijve deuren te helpen bedienen.
`touch_to_connect`	Verwijdert de geofence-vereiste van 500 m voor Touch to Open.
`touch_to_lock`	Vergrendel de deur door de buitenkant van het slot aan te raken.
`hold_to_lock`	Vergrendel de deur door de buitenkant van het slot aan te raken en vast te houden.

Tip: Om te bevestigen dat uw token werkt, stuurt u een GET verzoek aan https://integrations.production.loqed.com/api/locks/ met jouw Authorization: Bearer koptekst. Een lijst met uw sloten bevestigt dat alles correct is ingesteld.

LOQED web-API-integratie