Si applica a: LOQED Touch e LOQED Pure.
Questo è un articolo avanzato per sviluppatori per integrazioni di rete locale e webhook in uscita.
L'API bridge locale è principalmente orientata al bridge. Per LOQED Pure o configurazioni basate su gateway, controlla la disponibilità corrente dell'API prima di creare una nuova integrazione.
Con alcune piattaforme o dispositivi domestici intelligenti, LOQED non ha un'integrazione diretta. Se sei un utente avanzato, puoi sviluppare la tua integrazione utilizzando l'API LOQED. Assicurati di leggere prima il nostro articolo "Utenti avanzati: API disponibili".
Quando la porta viene aperta/bloccata, chiama un URL (webhook in uscita)
Quando lo stato del lucchetto cambia (aperto, sbloccato, bloccato) e per altre informazioni (percentuale della batteria, stato online), LOQED Bridge può chiamare (POST dati su) un URL. Di seguito puoi trovare quali dati vengono POSTATI come JSON a questo URL. Puoi anche aggiungere i parametri GET dell'URL impostando la chiave JSON tra "[" e "]". Ad esempio: https://your.server.nl/script?yourstate=[requested_state]. Puoi anche scegliere per quali modifiche deve essere attivata una chiamata webhook (ad esempio, puoi scegliere di chiamare un URL solo quando la porta è chiusa).
Vengono sempre inviate le seguenti chiavi JSON:
mac_wifi: contiene l'indirizzo MAC Wi-Fi del bridge. Questo aiuta a identificare il ponte. Anche il nome DNS multicast del bridge contiene questo indirizzo.
mac_ble: contiene l'indirizzo MAC Bluetooth del bridge.
Stato raggiunto
Dopo che il motore ha smesso di funzionare, vengono inviate le chiavi JSON seguenti per i trigger trigger_state_changed_open, trigger_state_changed_latch, trigger_state_changed_night_lock, trigger_state_changed_unknown:
stato_richiesto
APERTO
GIORNO_BLOCCO
BLOCCO_NOTTE
SCONOSCIUTO
tipo_evento
STATE_CHANGED_OPEN (stato_richiesto = APERTO)
STATE_CHANGED_LATCH (stato_richiesto = GIORNO_BLOCCO)
STATE_CHANGED_NIGHT_LOCK (stato_richiesto = NIGHT_LOCK)
STATE_CHANGED_UNKNOWN (stato_richiesto = SCONOSCIUTO)
MOTOR_STALL (stato_richiesto = SCONOSCIUTO)
STATE_CHANGED_OPEN_REMOTE (stato_richiesto = APERTO)
STATE_CHANGED_LATCH_REMOTE (stato_richiesto = GIORNO_BLOCCO)
STATE_CHANGED_NIGHT_LOCK_REMOTE (stato_richiesto = NIGHT_LOCK)
GO_TO_STATE_TOUCH_TO_LOCK (stato_richiesto = NIGHT_LOCK)
key_local_id (null se ad esempio apertura manuale tramite manopola o pressione di pulsante). Contiene il KeyID che ha modificato lo stato della serratura.
Andare in uno stato
Quando il lucchetto si sposta in una nuova posizione (ad esempio potrebbe non raggiungere la posizione se le batterie sono quasi scariche) vengono inviati i tasti JSON seguenti per i trigger trigger_state_goto_open, trigger_state_goto_latch, trigger_state_goto_night_lock:
andare_allo_stato
APERTO
GIORNO_BLOCCO
BLOCCO_NOTTE
tipo_evento
GO_TO_STATE_INSTANTOPEN_OPEN (Touch to Open) (go_to_state = APERTO)
GO_TO_STATE_INSTANTOPEN_LATCH (Sblocco automatico) (go_to_state = GIORNO_BLOCCO)
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 = NIGHT_LOCK)
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 = NIGHT_LOCK)
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 = NIGHT_LOCK)
key_local_id (255 significa sconosciuto, ad esempio apertura manuale tramite manopola o pressione di un pulsante)
Percentuale della batteria
Quando la serratura invia la percentuale corrente della batteria (ogni poche ore), vengono inviate le chiavi JSON seguenti per l'attivazione trigger_batteria:
tipo_batteria (0 = alcalina, 1 = NiMH, 2 = litio (non ricaricabile), 3 = sconosciuto)
percentuale_batteria
Stato in linea
Quando la serratura perde la connessione al bridge, le chiavi JSON riportate di seguito vengono inviate per il trigger trigger_online_status:
wifi_strength (attualmente in dB, presto cambierà in percentuale)
ble_strength (attualmente in dB, presto cambierà in percentuale. -1 significa che la serratura non è collegata)
Verifica se la richiesta del webhook proviene da LOQED Bridge
Potresti intraprendere azioni sensibili se la porta si apre (ad esempio, accendere le luci, spegnere l'allarme, accendere il riscaldamento). Pertanto è necessario assicurarsi che sull'URL fornito nessun altro dispositivo possa attivare tali azioni. Puoi:
Assicurati che nessun altro dispositivo possa chiamare l'URL limitando l'IP solo all'indirizzo IP dello LOQED Bridge. Inoltre, assicurati che l'indirizzo IP del bridge non cambi fissandolo nel servizio DHCP del tuo router.
Verifica la firma hash inviata nelle intestazioni della chiamata al webhook. Nell'intestazione trovi TIMESTAMP (8 byte) e HASH (hex). Puoi calcolare tu stesso l'hash eseguendo sha256(BODY + TIMESTAMP + base64_decode(bridge_authentication_key). La chiave di autenticazione del bridge può essere trovata su https://app.loqed.com/API-Config. Il BODY è il corpo inalterato ricevuto con la richiesta (con tutto il codice JSON). Inoltre, non dimenticare di verificare se il timestamp si trova entro pochi secondi dall'ora effettiva, per evitare attacchi di replay.
Elenca, aggiungi ed elimina un webhook sul bridge utilizzando il nostro strumento
Il modo più semplice per elencare, aggiungere o eliminare webhook è utilizzare il nostro strumento Javascript:
Scorrere fino alla voce "Webhook in uscita tramite LOQED Bridge"
Fare clic sul pulsante "Aggiungi/Elimina webhook" accanto al bridge corretto. Lo strumento si aprirà e l'indirizzo IP del bridge e la chiave di autenticazione saranno precompilati.
Elenca, aggiungi ed elimina un webhook sul bridge utilizzando il tuo codice
Se vuoi rendere più semplice per gli utenti del tuo prodotto collegarlo a LOQED, puoi anche utilizzare l'API bridge per configurare i webhook. Di seguito vengono descritti gli endpoint API. Puoi guardare il codice dello strumento Javascript sopra menzionato se stai cercando un esempio. LOQED Bridge può essere trovato utilizzando mDNS nella tua applicazione (prova ad esempio "DNS-sd -B _http._tcp" su Windows)
Per tutti i metodi del server web /webhooks sono obbligatorie due intestazioni:
TIMESTAMP: contiene il timestamp corrente
HASH – stringa hash sha256
Il calcolo dell'hash è specifico per ogni tipologia di richiesta e descritto nella sezione corrispondente. Hai bisogno della chiave di autenticazione del bridge per poter calcolare l'hash. Questa chiave può essere trovata dopo aver effettuato l'accesso a https://app.loqed.com/API-Config. Non esiste altro modo per recuperare questa chiave.
Elenca webhook
OTTIENI: https://bridge-ip-address/webhooks
L'HASH nell'intestazione deve essere formattato: SHA256(TIMESTAMP + LOCK_TOKEN), dove TIMESTAMP è un numero di 8 byte e LOCK_TOKEN è la chiave di sicurezza del bridge decodificato in base64 (!) (la chiave sulla pagina webhooks.loqed.com è in base64). L'HASH dovrebbe essere in formato esadecimale.
Restituisce l'array JSON con le chiavi:
'id': 1 (int)
'trigger_state_changed_open': 0/1
'trigger_state_changed_latch': 0/1
'trigger_state_changed_night_lock': 0/1
'trigger_state_changed_unknown': 0/1
'trigger_state_goto_open': 0/1
'trigger_state_goto_latch': 0/1
'trigger_state_goto_night_lock': 0/1
'batteria_attivatore': 0/1
'trigger_online_status': 0/1
Restituisce i codici HTTP:
Restituisce il codice HTTP 400 BAD REQUEST e la stringa con la descrizione nel caso in cui le intestazioni non siano valide o non siano state trovate
Restituisce HTTP 401 UNAUTHORIZED se l'autenticazione non è riuscita
Crea webhook
POST: http://indirizzo IP del bridge/webhook
Corpo: JSON con chiavi:
'trigger_state_changed_open': 0/1
'trigger_state_changed_latch': 0/1
'trigger_state_changed_night_lock': 0/1
'trigger_state_changed_unknown': 0/1
'trigger_state_goto_open': 0/1
'trigger_state_goto_latch': 0/1
'trigger_state_goto_night_lock': 0/1
'batteria_attivatore': 0/1
'trigger_online_status': 0/1
L'HASH nell'intestazione deve essere formattato: SHA256(URL + trigger_bitmap + TIMESTAMP + LOCK_TOKEN), URL è una stringa, trigger_bitmap 4 byte, TIMESTAMP è un numero di 8 byte e LOCK_TOKEN è la chiave di sicurezza del bridge decodificato in base64 (!) (la chiave sulla pagina webhooks.loqed.com è in base64). L'HASH dovrebbe essere in formato esadecimale. La trigger_bitmap contiene i trigger. Ad esempio, 0x000F (15 decimale) è 0000 0000 0000 1010 in binario, il che significa che i seguenti trigger sono abilitati:
"trigger_state_changed_open":0
"trigger_state_changed_latch":1
"trigger_state_changed_night_lock":0
"trigger_state_changed_unknown":1
"trigger_state_goto_open":0
"trigger_state_goto_latch":0
"trigger_state_goto_night_lock":0
"trigger_batteria":0
"trigger_online_status":0
Abbiamo anche un piccolo snippet PHP che mostra come viene creato un webhook, puoi scaricarlo qui.
Resi:
Codice HTTP 200 OK e stringa con descrizione in caso di creazione riuscita del webhook
Codice HTTP 400 BAD REQUEST e stringa con descrizione nel caso in cui JSON non sia valido per la creazione del webhook
Codice HTTP 400 BAD REQUEST e stringa con descrizione nel caso in cui le intestazioni non siano valide o non siano state trovate
HTTP 401 UNAUTHORIZED se l'autenticazione non è riuscita
HTTP 500 INTERNAL SERVER ERROR codice e stringa con descrizione nel caso in cui esista già un webhook con questo URL
HTTP 500 INTERNAL SERVER ERROR codice e stringa con descrizione nel caso in cui venga raggiunto il numero MAX di webhook
Elimina webhook
ELIMINA: http://indirizzo IP del bridge/webhook/{webhookId}
L'HASH nell'intestazione deve essere formattato: SHA256(id + TIMESTAMP + LOCK_TOKEN), ID è un numero di 8 byte, TIMESTAMP è un numero di 8 byte e LOCK_TOKEN è la chiave di sicurezza del bridge decodificato in base64 (!) (la chiave sulla pagina webhooks.loqed.com è in base64). L'HASH dovrebbe essere in formato esadecimale.
Resi:
Codice HTTP 200 OK e stringa con descrizione in caso di eliminazione corretta del webhook
Codice HTTP 400 BAD REQUEST e stringa con descrizione nel caso in cui le intestazioni non siano valide o non siano state trovate
HTTP 401 UNAUTHORIZED se l'autenticazione non è riuscita
Codice HTTP 404 NOT FOUND e stringa con descrizione nel caso in cui il webhook con {webhookId} non sia stato trovato
Codice e stringa HTTP 500 INTERNAL SERVER ERROR con descrizione nel caso in cui si sia verificato un errore durante l'eliminazione
Test
Si consiglia di utilizzare Webhook.sito se desideri verificare che il tuo smart lock/bridge chiami l'URL del webhook. Qui potrai anche vedere i dati JSON.
Aprire/bloccare la porta quando succede qualcosa (webhook in entrata)
Se desideri controllare la serratura da un servizio o dispositivo di terze parti, puoi farlo tramite una chiamata HTTPS GET al tuo URL LOQED Bridge.
Creazione di una chiave API
Innanzitutto, devi creare una nuova chiave sulla tua serratura intelligente LOQED.
Apri la pagina https://app.loqed.com/API-Config.
Accedi utilizzando l'indirizzo e-mail e la password che utilizzi per accedere a LOQED app.
Fare clic su "Aggiungi nuova chiave API".
Immettere un nome per una facile identificazione. Può essere qualsiasi cosa tu voglia.
Se disponi di più lucchetti, puoi selezionare il lucchetto giusto nel menu a discesa accanto a "Seleziona lucchetto".
Fai clic su "Aggiungi chiave API".
Ora hai creato la chiave API.
Chiama l'API
Attualmente, l'API supporta i seguenti comandi:
Aperto (la serratura si apre, poi ritorna allo scrocco. Supportato solo su porte senza maniglia esterna). Viene restituito un oggetto JSON vuoto.
Fermo (sbloccato). Viene restituito un oggetto JSON vuoto.
Blocco notturno (bloccato). Viene restituito un oggetto JSON vuoto.
Stato. ATTENZIONE: si consiglia di richiedere lo stato una sola volta al giorno, per ridurre al minimo il carico sul ponte. Invece di chiedere lo stato, dovresti implementare un webhook che chiami il tuo server, in modo da ricevere una notifica immediata non appena lo stato di blocco cambia. Restituisce le seguenti chiavi JSON:
mac_wifi (identificazione del lucchetto)
mac_bluetooth
lock_online (1 se la serratura è online, altrimenti 0)
batteria_percentuale (-1 se la serratura è offline, altrimenti 0 - 100)
tipo_batteria (0 = alcalina, 1 = NiMH, 2 = litio (non ricaricabile), 3 = sconosciuto)
bullone_stato_numerico (0 = sconosciuto, 1 = aperto, 2 = giorno_blocco, 3 = notte_blocco)
Bolt_state (sconosciuto, aperto, day_lock, night_lock)
Lascia che sia il bridge LOQED a generare la firma digitale
I comandi alla serratura intelligente devono essere firmati digitalmente. Il modo più semplice è lasciare che il bridge LOQED generi questa firma. Utilizza semplicemente i quattro URL forniti (aperto, latch, blocco notturno, stato) mostrati su webhooks.loqed.com. Tieni presente che la connessione HTTP al bridge non è protetta, quindi altre persone sulla tua rete locale potrebbero potenzialmente recuperare la chiave di crittografia. Se desideri inviare comandi in modo sicuro, devi generare tu stesso la firma digitale.
Genera tu stesso la firma digitale
A https://app.loqed.com/Bridge-API-example/ forniamo codice di esempio (Javascript e PHP) che mostra come viene creata la firma digitale. Puoi utilizzare questo metodo solo se puoi creare il tuo plug-in per il sistema di casa intelligente a cui desideri connetterti. I dati necessari (IP, segreto, KeyID) possono essere trovati su https://app.loqed.com/API-Config dopo aver fatto clic sul pulsante "Visualizza/Modifica" accanto alla chiave API.