Naar de hoofdinhoud

LOQED web-API-integratie

Geavanceerde handleiding voor ontwikkelaars: ontvang vergrendelingsgebeurtenissen met webhooks, beheer uw LOQED-vergrendeling en wijzig de vergrendelingsinstellingen.

Geldt voor: LOQED Touch en LOQED Pure.

Dit is een geavanceerd ontwikkelaarsartikel voor LOQED-web-API's, inkomende webhooks en uitgaande webhook-gebeurtenissen.

Touch Display-specifieke instellingen zoals Open House Mode zijn alleen van toepassing op LOQED Pure wanneer de optionele LOQED Touch Display is geïnstalleerd.

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

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 House Mode en Twist Assist.

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

Velden

  • gevraagde_staat – de positie die werd bereikt: GEOPEND, DAG_LOCK, NIGHT_LOCK of ONBEKEND.

  • gebeurtenistype – 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_UNBNOWN (requested_state = ONBEKEND)

    • MOTOR_STALL (requested_state = ONBEKEND)

  • lock_id – de identificatie van uw slot.

  • key_local_id, sleutel_naam_gebruiker, sleutel_naam_admin – nul 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, sleutel_account_naam – nul 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 ga_naar_staat attribuut met de doelboutstatus.

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

Mogelijk ga_naar_staat waarden: GEOPEND, DAG_LOCK, NIGHT_LOCK.

Mogelijk gebeurtenistype waarden:

  • GO_TO_STATE_INSTANTOPEN_OPEN – Touch to Open (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 sleutel_* velden gedragen zich hetzelfde als hierboven beschreven.

Bluetooth en Wi-Fi sterke webhook

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_sterkte": 42,
  "wifi_sterkte": 73,
  "battery_percentage": 88,
  "lock_id": "Yq1gK4oeE9KWe0ByxjX2"
}

  • ble_sterkte – Bluetooth-signaal als percentage. Dit fluctueert sterk, dus maak je geen zorgen als het laag is.

  • wifi_sterkte – Wi-Fi-signaal als percentage.

  • batterij_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 KRIJG verzoek naar een LOQED-URL.

Log in en open de API-sectie

  1. Openen app.loqed.com in uw browser.

  2. 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.

  3. 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 vervolgkeuzelijst.

  • Klik API-sleutel toevoegen.

Uw API-sleutel is nu aangemaakt.

Roep de API aan

De API ondersteunt momenteel de volgende opdrachten:

  • Openen – 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,
  "batterij_type": 0,
  "bolt_state_numeric": 2,
  "bolt_state": "dagslot",
  "guest_access_mode": 0,
  "twist_assist": 0,
  "touch_to_connect": 0
}

  • Identiteitskaart – slot-ID.

  • brug_online – 1 als de bridge online is, anders 0.

  • lock_online – 1 als het slot online is, anders 0.

  • batterij_percentage – -1 als het slot offline is, anders 0–100.

  • batterij_type – 0 = Alkalisch, 1 = NiMH, 2 = Lithium (niet oplaadbaar), 3 = onbekend.

  • bolt_state_numeriek – 0 = onbekend, 1 = geopend, 2= dagslot, 3 = nachtslot.

  • bout_staat – onbekend, geopend, dagslot of nachtslot.

  • gast_toegangsmodus – 1 indien ingeschakeld, 0 indien uitgeschakeld.

  • twist_assist – 1 indien ingeschakeld, 0 indien uitgeschakeld.

  • touch_to_connect – 1 als de Touch to Open-beperking van 500 m wordt opgeheven, 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 (openen, vergrendelen, 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 deze niet naar de LOQED-server stuurt, kunt u zelf de digitale handtekening genereren. Bij app.loqed.com/Backend-API-voorbeeld 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 House Mode en Twist Assist.

De basis-URL voor alle eindpunten is:

https://integrations.production.loqed.com

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

Autorisatie: drager YOUR_PERSONAL_ACCESS_TOKEN

Genereer een persoonlijk toegangstoken

Open de LOQED persoonlijke toegangstokenpagina en volg deze stappen:

  1. Log in met het e-mailadres van uw LOQED app-account (u moet een beheerder).

  2. Tik Creëer.

  3. Geef het token een herkenbare naam (bijvoorbeeld de naam van de integratie die je bouwt).

  4. Tik Opslaan.

  5. Kopieer het token en bewaar het op een veilige plek. U gebruikt het als het Drager 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 Identiteitskaart voor de andere eindpunten.

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

Voorbeeld met cURL:

curl -X KRIJG "https://integrations.production.loqed.com/api/locks/" \
  -H "Autorisatie: drager YOUR_PERSONAL_ACCESS_TOKEN"

Voorbeeld antwoord:

{
  "gegevens": [
    {
      "id": "Yq1gK4oeE9KWe0ByxjX2",
      "naam": "Voordeur",
      "model_name": "LOQED",
      "battery_percentage": 95,
      "battery_type": "alkaline",
      "bolt_state": "dagslot",
      "party_mode": vals,
      "guest_access_mode": false,
      "twist_assist": false,
      "touch_to_connect": vals,
"lock_direction": "tegen de klok in",
      "mortise_lock_type": "cylinder_operated_no_handle_on_the_outside",
      "ondersteunde_lock_states": [
        "openen",
        "dag_slot",
        "nachtslot"
      ]
    }
  ]
}

Wijzig de vergrendelingsstatus

Bedien een slot door te bellen naar de bout_staat eindpunt. De beschikbare boutstatussen zijn geopend, dagslot en nachtslot.

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

Voorbeeld met cURL (ontgrendelen naar dagslot):

curl -X KRIJG "https://integrations.production.loqed.com/api/locks/Yq1gK4oeE9KWe0ByxjX2/bolt_state/day_lock" \
  -H "Autorisatie: drager YOUR_PERSONAL_ACCESS_TOKEN"

Wijzig een vergrendelingsinstelling

Gebruik dit eindpunt om een vergrendelingsinstelling te wijzigen, zoals Open House Mode, Twist Assist, 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 Open House Mode in:

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

Aan schakel Twist Assist in:

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

Volledig voorbeeld met cURL:

curl -X POST "https://integrations.production.loqed.com/api/locks/Yq1gK4oeE9KWe0ByxjX2/setting" \
  -H "Autorisatie: drager YOUR_PERSONAL_ACCESS_TOKEN" \
  -H "Inhoudstype: applicatie/json" \
  -d '{"setting_name": "open_house_mode", "setting_value": 1}'

instelling_waarde 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 geofencevereiste 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 KRIJG verzoek aan https://integrations.production.loqed.com/api/locks/ met jouw Machtiging: Aan toonder koptekst. Een lijst met uw sloten bevestigt dat alles correct is ingesteld.

Gerelateerde artikelen
LOQED lokale bridge-API-integratie
Loxone- en LOQED-integratie
Home Assistant- en LOQED-integratie
Domoticz- en LOQED-integratie
Fibaro- en LOQED-integratie
Was dit een antwoord op uw vraag?