Alcune piattaforme e dispositivi per la casa intelligente non hanno ancora un'integrazione diretta con LOQED. Se sei un utente avanzato o uno sviluppatore, puoi creare la tua integrazione utilizzando le API LOQED. Prima di iniziare, ti consigliamo di leggere il nostro articolo "Utenti avanzati: API disponibili" first.

LOQED offre tre modalità di integrazione con la tua serratura:

Webhook in uscita – lascia che la tua serratura avvisi un URL esterno ogni volta che cambia il suo stato (ad esempio, per attivare le automazioni).
Webhook in entrata – comandare la tua serratura (apertura, scrocco, serratura notte) da un altro servizio o dispositivo.
API di integrazioni – un'API REST basata su token per elencare i tuoi blocchi, modificare lo stato del blocco e modificare le impostazioni del blocco come Modalità porte aperte E Assistente alla torsione.

Webhook in uscita: chiama un URL esterno quando il blocco cambia

Quando il blocco raggiunge una nuova posizione (aperto, sblocco/blocco diurno, blocco/blocco notturno), il backend LOQED può inviare dati (POST) a un URL di tua scelta. Puoi registrare l'URL che desideri essere chiamato nel file API sezione su app.loqed.com (vedi sotto).

Poiché non tutti i sistemi supportano JSON, puoi anche configurare un URL separato per ogni evento (ad esempio un URL per l'apertura e uno per il blocco). In tal caso il requested_state il valore è sempre lo stesso per quell'URL.

Payload dell'evento: stato raggiunto

Questo payload viene inviato quando il blocco ha raggiunto una posizione. Esempio di JSON pubblicato sul tuo 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"
}

Campi

requested_state – la posizione raggiunta: OPEN, DAY_LOCK, NIGHT_LOCK O UNKNOWN.
event_type – uno di:
- STATE_CHANGED_OPEN (stato_richiesto = APERTO)
- STATE_CHANGED_LATCH (stato_richiesto = GIORNO_BLOCCO)
- STATE_CHANGED_NIGHT_LOCK (stato_richiesto = BLOCCO_NOTTE)
- STATE_CHANGED_UNKNOWN (stato_richiesto = SCONOSCIUTO)
- MOTOR_STALL (stato_richiesto = SCONOSCIUTO)
lock_id – l'identificativo della tua serratura.
key_local_id, key_name_user, key_name_admin – null quando l'azione non è stata attivata da un tasto (ad esempio una rotazione manuale della manopola o la pressione di un pulsante).
key_account_e-mail, key_account_name – null per azioni manuali o quando viene utilizzato un PIN non collegato a un account.

Payload dell'evento: andare in uno stato

Puoi anche ricevere un webhook quando lock inizia a muoversi verso una nuova posizione. La serratura potrebbe non raggiungere effettivamente la posizione (ad esempio quando le batterie sono quasi scariche). Questi eventi determinano il go_to_state attributo con lo stato del bullone di destinazione.

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

Possibile go_to_state valori: OPEN, DAY_LOCK, NIGHT_LOCK.

Possibile event_type valori:

GO_TO_STATE_INSTANTOPEN_OPEN – Tocca per aprire (go_to_state = APERTO)
GO_TO_STATE_INSTANTOPEN_LATCH – Sblocco automatico (go_to_state = DAY_LOCK)
GO_TO_STATE_MANUAL_UNLOCK_BLE_OPEN (go_to_state = APERTO)
GO_TO_STATE_MANUAL_LOCK_BLE_LATCH (go_to_state = DAY_LOCK)
GO_TO_STATE_MANUAL_LOCK_BLE_NIGHT_LOCK (go_to_state = BLOCCO_NOTTE)
GO_TO_STATE_TWIST_ASSIST_OPEN (go_to_state = APERTO)
GO_TO_STATE_TWIST_ASSIST_LATCH (go_to_state = DAY_LOCK)
GO_TO_STATE_TWIST_ASSIST_LOCK (go_to_state = BLOCCO_NOTTE)
GO_TO_STATE_MANUAL_UNLOCK_VIA_OUTSIDE_MODULE_PIN (go_to_state = APERTO)
GO_TO_STATE_MANUAL_UNLOCK_VIA_OUTSIDE_MODULE_BUTTON (go_to_state = APERTO)
GO_TO_STATE_TOUCH_TO_LOCK (go_to_state = BLOCCO_NOTTE)
GO_TO_STATE_MANUAL_UNLOCK_REMOTE_OPEN
GO_TO_STATE_MANUAL_LOCK_REMOTE_LATCH
GO_TO_STATE_MANUAL_LOCK_REMOTE_NIGHT_LOCK

IL lock_id E key_* i campi si comportano come descritto sopra.

Webhook di potenza Bluetooth e Wi-Fi

Ogni poche ore e ogni volta che la serratura o il bridge vengono accesi, è possibile inviare un aggiornamento dei livelli del segnale. Abilita il segno di spunta corrispondente nel API sezione su app.loqed.com per ricevere queste informazioni.

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

ble_strength – Segnale Bluetooth in percentuale. Questo oscilla molto, quindi non preoccuparti se è basso.
wifi_strength – Segnale Wi-Fi in percentuale.
battery_percentage – livello della batteria in percentuale.
lock_id – l'identificativo della tua serratura.

Blocca il webhook online

Ogni poche ore e ogni volta che la serratura o il bridge vengono accesi, è possibile inviare un aggiornamento "online". Abilita il segno di spunta corrispondente per ricevere queste informazioni.

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

online – 1 viene inviato come valore.
lock_id – l'identificativo della tua serratura.

Testare il tuo webhook

Si consiglia di utilizzare Webhook.site per verificare che la tua serratura intelligente chiami l'URL del webhook. Consente inoltre di controllare i dati JSON inviati.

Webhook in entrata: controlla il blocco

Se desideri controllare la tua serratura da un servizio o dispositivo di terze parti, puoi farlo con un HTTPS GET richiesta a un URL LOQED.

Accedi e apri la sezione API

Aprire app.loqed.com nel tuo browser.
Accedi con l'indirizzo email del tuo account dell'app LOQED. Un codice di verifica (2FA) verrà inviato alla tua email: inseriscilo per continuare.
Nel menu, scegli API. Qui è dove gestisci i webhook e le chiavi API in uscita e in entrata.

Crea una chiave API

In questa pagina puoi aggiungere webhook in uscita e creare webhook in entrata.

Clic Aggiungi una nuova chiave API.

Inserisci un nome in modo da poter riconoscere la chiave in seguito. Può essere qualsiasi cosa: non deve necessariamente corrispondere al nome della tua chiave.
Se disponi di più lucchetti, seleziona quello corretto dal Seleziona Blocca dropdown.
Clic Aggiungi chiave API.

La tua chiave API è stata creata.

Chiama l'API

L'API attualmente supporta i seguenti comandi:

Aprire – la porta si apre. Viene restituito un oggetto JSON vuoto.
Fermo – la porta è sbloccata (serratura diurna). Viene restituito un oggetto JSON vuoto.
Blocco notturno – la porta è chiusa a chiave. Viene restituito un oggetto JSON vuoto.
Stato – restituisce lo stato attuale della serratura (vedi sotto).

⚠️ Importante: richiedere il Stato al massimo una volta al giorno. Se lo richiedi più di 12 volte verrai bloccato per 12 ore. Invece di interrogare lo stato, imposta un file webhook in uscita in questo modo il tuo server viene avvisato immediatamente ogni volta che cambia lo stato di blocco.

IL Stato il comando restituisce il seguente 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 – identificatore di blocco.
bridge_online – 1 se il bridge è online, altrimenti 0.
lock_online – 1 se la serratura è online, altrimenti 0.
battery_percentage – -1 se la serratura è offline, altrimenti 0–100.
battery_type – 0 = alcalino, 1 = NiMH, 2 = Litio (non ricaricabile), 3 = sconosciuto.
bolt_state_numeric – 0 = sconosciuto, 1 = aperto, 2 = giorno_blocco, 3 = serratura_notte.
bolt_state – unknown, open, day_lock O night_lock.
guest_access_mode – 1 se abilitato, 0 se disabilitato.
twist_assist – 1 se abilitato, 0 se disabilitato.
touch_to_connect – 1 se la restrizione 500 m tocca per aprire viene rimossa, altrimenti 0.

Lascia che LOQED generi la firma digitale

I comandi alla serratura intelligente devono essere firmati digitalmente. L'opzione più semplice è lasciare che il server LOQED generi questa firma per te: utilizza semplicemente i quattro URL già pronti (aperto, latch, blocco notturno, stato) mostrati nel API sezione su app.loqed.com.

Genera tu stesso la firma digitale

Se preferisci tenere per te la chiave di crittografia e non inviarla al server LOQED, puoi generare tu stesso la firma digitale. A app.loqed.com/Backend-API-example forniamo codice di esempio (JavaScript e PHP) che mostra come viene creata la firma.

API di integrazioni: leggi i blocchi e modifica le impostazioni

IL API di integrazioni è un'API REST basata su token. Con un singolo token di accesso personale puoi elencare i tuoi lucchetti, modificare lo stato del blocco e modificare le impostazioni del blocco come Modalità porte aperte E Assistente alla torsione.

L'URL di base per tutti gli endpoint è:

https://integrations.production.loqed.com

Ogni richiesta deve includere nel file il tuo token di accesso personale Authorization intestazione:

Authorization: Bearer YOUR_PERSONAL_ACCESS_TOKEN

Genera un token di accesso personale

Apri il Pagina del token di accesso personale LOQED e segui questi passaggi:

Accedi con l'indirizzo email del tuo account dell'app LOQED (devi essere un amministratore).
Rubinetto Creare.
Assegna al token un nome riconoscibile (ad esempio il nome dell'integrazione che stai creando).
Rubinetto Salva.
Copia il token e conservalo in un posto sicuro: lo utilizzerai come file Bearer token in ogni richiesta. Trattalo come una password.

Elenca le tue serrature

Utilizza questo endpoint per recuperare tutti i blocchi disponibili per il tuo account, inclusi lo stato e le impostazioni attuali. Avrai bisogno della serratura id per gli altri endpoint.

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

Esempio con cURL:

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

Risposta di esempio:

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

Modificare lo stato di blocco

Azionare una serratura chiamando il bolt_state punto finale. Gli stati dei bulloni disponibili sono open, day_lock E night_lock.

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

Esempio con cURL (sblocco con blocco giornaliero):

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

Modificare un'impostazione di blocco

Utilizza questo endpoint per modificare un'impostazione di blocco come Modalità porte aperte, Assistente alla torsione, la direzione di chiusura o il fuso orario.

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

Invia un corpo JSON con il nome dell'impostazione e il suo nuovo valore. Ad esempio, a abilitare la modalità Open House:

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

A abilitare l'Assistenza alla torsione:

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

Esempio completo con 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 è un numero intero con segno a 32 bit. La maggior parte delle impostazioni sono semplici interruttori di attivazione/disattivazione che accettano 0 (spento) e 1 (on), ma alcuni si aspettano valori specifici. Modifica un'impostazione alla volta e verifica il risultato sulla serratura o nell'app LOQED.

Impostazioni disponibili

Le impostazioni riportate di seguito sono le levette più comunemente utilizzate (0 = spento, 1 = acceso):

nome_impostazione	Cosa fa
`open_house_mode`	Mantiene la porta nella serratura diurna in modo che possa essere aperta con la maniglia senza sbloccarla ogni volta.
`twist_assist`	Dà al bullone una rotazione extra per aiutare ad azionare le porte rigide.
`touch_to_connect`	Rimuove il requisito del recinto geografico di 500 m per Touch to Open.
`touch_to_lock`	Bloccare la porta toccando l'esterno della serratura.
`hold_to_lock`	Blocca la porta toccando e tenendo premuta la parte esterna della serratura.

Mancia: per confermare che il tuo token funziona, invia un GET richiesta a https://integrations.production.loqed.com/api/locks/ con il tuo Authorization: Bearer intestazione. Un elenco dei tuoi lucchetti conferma che tutto è impostato correttamente.

Integrazione API web LOQED