Vai al contenuto principale

Integrazione API web LOQED

Guida avanzata per sviluppatori: ricevi eventi di blocco con webhook, controlla il tuo blocco LOQED e modifica le impostazioni di blocco.

Si applica a: LOQED Touch e LOQED Pure.

Questo è un articolo avanzato per sviluppatori per API Web LOQED, webhook in entrata ed eventi webhook in uscita.

Le impostazioni specifiche di Touch Display come Open House Mode si applicano a LOQED Pure solo quando è installato LOQED Touch Display opzionale.

Alcune piattaforme e dispositivi per la casa intelligente non dispongono ancora di un'integrazione LOQED diretta. 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" prima.

LOQED offre tre modalità di integrazione con la 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 Open House Mode e Twist Assist.

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

Quando il lucchetto 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 stato_richiesto 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": "Porta d'ingresso",
  "key_name_admin": "Jane Doe",
  "key_account_e-mail": "jane@example.com",
  "key_account_name": "Jane Doe"
}

Campi

  • stato_richiesto – la posizione raggiunta: APERTO, GIORNO_BLOCCO, BLOCCO_NOTTE o SCONOSCIUTO.

  • tipo_evento – uno di:

    • STATO_CAMBIATO_APERTO (stato_richiesto = APERTO)

    • STATE_CHANGED_LATCH (stato_richiesto = GIORNO_BLOCCO)

    • STATE_CHANGED_NIGHT_LOCK (stato_richiesto = BLOCCO_NOTTE)

    • STATO_CHANGED_UNKNOWN (stato_richiesto = SCONOSCIUTO)

    • MOTORE_STALLO (stato_richiesto = SCONOSCIUTO)

  • lock_id – l'identificativo della tua serratura.

  • key_local_id, nome_chiave_utente, nome_chiave_admin – nullo quando l'azione non è stata attivata da un tasto (ad esempio una rotazione manuale della manopola o la pressione di un pulsante).

  • chiave_account_e-mail, nome_account_chiave – nullo 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 andare_allo_stato attributo con lo stato del bullone di destinazione.

{
  "go_to_state": "APERTO",
  "event_type": "GO_TO_STATE_INSTANTOPEN_OPEN",
  "lock_id": "Yq1gK4oeE9KWe0ByxjX2",
  "key_local_id": 3,
  "key_name_user": "Porta d'ingresso",
  "key_name_admin": "Jane Doe",
  "key_account_e-mail": "jane@example.com",
  "key_account_name": "Jane Doe"
}

Possibile andare_allo_stato valori: APERTO, GIORNO_BLOCCO, BLOCCO_NOTTE.

Possibile tipo_evento valori:

  • GO_TO_STATE_INSTANTOPEN_OPEN – Touch to Open (go_to_state = APERTO)

  • GO_TO_STATE_INSTANTOPEN_LATCH – Sblocco automatico (vai_a_stato = GIORNO_BLOCCO)

  • GO_TO_STATE_MANUAL_UNLOCK_BLE_OPEN (go_to_state = APERTO)

  • GO_TO_STATE_MANUAL_LOCK_BLE_LATCH (vai_a_stato = GIORNO_BLOCCO)

  • 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 (vai_a_stato = GIORNO_BLOCCO)

  • 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 chiave_* i campi si comportano come descritto sopra.

Webhook di forza 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_forza": 42,
  "potenza_wifi": 73,
  "percentuale_batteria": 88,
  "lock_id": "Yq1gK4oeE9KWe0ByxjX2"
}

  • ble_forza – Segnale Bluetooth in percentuale. Questo oscilla molto, quindi non preoccuparti se è basso.

  • wifi_forza – Segnale Wi-Fi in percentuale.

  • percentuale_batteria – 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.

{
  "in linea": 1,
  "lock_id": "Yq1gK4oeE9KWe0ByxjX2"
}

  • in linea – 1 viene inviato come valore.

  • lock_id– l'identificativo della tua serratura.

Testare il tuo webhook

Si consiglia di utilizzare Webhook.sito 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 OTTIENI richiesta a un URL LOQED.

Accedi e apri la sezione API

  1. Aperto app.loqed.com nel tuo browser.

  2. Accedi con l'indirizzo email del tuo account LOQED app. Un codice di verifica (2FA) verrà inviato alla tua email: inseriscilo per continuare.

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

  • Fare 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 discesa.

  • Fare clic Aggiungi chiave API.

La tua chiave API è stata creata.

Chiama l'API

L'API attualmente supporta i seguenti comandi:

  • Aperto – 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,
  "percentuale_batteria": 88,
  "tipo_batteria": 0,
  "bolt_state_numeric": 2,
  "bolt_state": "day_lock",
  "guest_access_mode": 0,
  "twist_assist": 0,
  "tocca_per_connettersi": 0
}

  • id – identificatore di blocco.

  • ponte_online – 1 se il bridge è online, altrimenti 0.

  • lock_online – 1 se la serratura è online, altrimenti 0.

  • percentuale_batteria – -1 se la serratura è offline, altrimenti 0–100.

  • tipo_batteria – 0 = alcalino, 1 = NiMH, 2 = Litio (non ricaricabile), 3 = sconosciuto.

  • bullone_stato_numerico – 0 = sconosciuto, 1 = aperto, 2= giorno_blocco, 3 = serratura_notte.

  • bullone_stato – sconosciuto, aperto, day_lock o night_lock.

  • modalità_accesso_ospite – 1 se abilitato, 0 se disabilitato.

  • twist_assist – 1 se abilitato, 0 se disabilitato.

  • toccare_per_connettersi – 1 se la restrizione Touch to Open 500 m 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/Esempio di API backend 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 blocchi, modificare lo stato del blocco e modificare le impostazioni del blocco come Open House Mode e Twist Assist.

L'URL di base per tutti gli endpoint è:

https://integrations.production.loqed.com

Ogni richiesta dovrà includere nel file il proprio token di accesso personale Autorizzazione intestazione:

Autorizzazione: Titolare YOUR_PERSONAL_ACCESS_TOKEN

Genera un token di accesso personale

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

  1. Accedi con l'indirizzo email del tuo account LOQED app (devi essere un amministratore).

  2. Tocca Crea.

  3. Assegna al token un nome riconoscibile (ad esempio il nome dell'integrazione che stai creando).

  4. Tocca Salva.

  5. Copia il token e conservalo in un posto sicuro: lo utilizzerai come file Portatore 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.

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

Esempio con cURL:

arricciatura -X GET "https://integrations.production.loqed.com/api/locks/" \
  -H "Autorizzazione: Titolare YOUR_PERSONAL_ACCESS_TOKEN"

Risposta di esempio:

{
  "dati": [
    {
      "id": "Yq1gK4oeE9KWe0ByxjX2",
      "nome": "Porta d'ingresso",
      "nome_modello": "LOQED",
      "percentuale_batteria": 95,
      "battery_type": "alcalina",
      "bolt_state": "day_lock",
      "party_mode": falso,
      "guest_access_mode": falso,
      "twist_assist": falso,
      "touch_to_connect": falso,
"lock_direction": "antiorario_orario",
      "mortise_lock_type": "cylinder_operated_no_handle_on_the_outside",
      "supported_lock_states": [
        "aperto",
        "lucchetto_giorno",
        "blocco_notte"
      ]
    }
  ]
}

Modificare lo stato di blocco

Azionare una serratura chiamando il bullone_stato punto finale. Gli stati dei bulloni disponibili sono aperto, day_lock e night_lock.

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

Esempio con cURL (sblocco con blocco giornaliero):

arricciatura -X GET "https://integrations.production.loqed.com/api/locks/Yq1gK4oeE9KWe0ByxjX2/bolt_state/day_lock" \
  -H "Autorizzazione: Titolare YOUR_PERSONAL_ACCESS_TOKEN"

Modificare un'impostazione di blocco

Utilizza questo endpoint per modificare un'impostazione di blocco come Open House Mode, Twist Assist, 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 Open House Mode:

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

A abilitare Twist Assist:

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

Esempio completo con cURL:

arricciatura -X POST "https://integrations.production.loqed.com/api/locks/Yq1gK4oeE9KWe0ByxjX2/setting" \
  -H "Autorizzazione: Titolare YOUR_PERSONAL_ACCESS_TOKEN" \
  -H "Tipo di contenuto: application/json" \
  -d '{"setting_name": "open_house_mode", "setting_value": 1}'

valore_impostazione è 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 nello LOQED app.

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.

toccare_per_connettersi

Rimuove il requisito del recinto geografico di 500 m per Touch to Open.

tocca_per_bloccare

Bloccare la porta toccando l'esterno della serratura.

tieni_per_bloccare

Blocca la porta toccando e tenendo premuta la parte esterna della serratura.

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

Articoli correlati
LOQED API disponibili
LOQED Integrazione API bridge locale
Integrazione Loxone e LOQED
Integrazione Domoticz e LOQED
Integrazione Fibaro e LOQED
Hai ricevuto la risposta alla tua domanda?