Con algunas plataformas o dispositivos domésticos inteligentes, LOQED no tiene integración directa. Si eres un usuario avanzado, puedes desarrollar tu integración utilizando la API de LOQED. Asegúrate de leer primero nuestro artículo "Usuarios avanzados: APIs disponibles" primero.

Cuando se abre/cierra la puerta, llama a una URL (webhook saliente)

Cuando cambia el estado de la cerradura (abierta, desbloqueada, bloqueada) y para obtener otra información (porcentaje de batería, estado en línea), el Puente LOQED puede llamar (enviar datos POST) a una URL. A continuación puedes ver qué datos se envían como JSON a esta URL. También puedes añadir parámetros GET de URL estableciendo la clave JSON entre "[" y "]". Por ejemplo https://your.server.nl/script?yourstate=[estado_solicitado ]. También puedes elegir para qué cambios debe activarse una llamada de webhook (por ejemplo, puedes elegir que sólo se llame a una URL cuando la puerta esté cerrada).

Siempre se envían las siguientes claves JSON:

mac_wifi: contiene la dirección MAC Wi-Fi del puente. Esto ayuda a identificar el puente. El nombre DNS multidifusión del puente también contiene esta dirección.
mac_ble: contiene la dirección MAC Bluetooth del puente.

Estado alcanzado

Cuando el motor deja de funcionar, se envían las siguientes claves JSON para los disparadores trigger_state_changed_open, trigger_state_changed_latch, trigger_state_changed_night_lock, trigger_state_changed_unknown:

estado_solicitado
- ABIERTO
- BLOQUEO_DÍA
- BLOQUEO NOCTURNO
- DESCONOCIDO
tipo_evento
- STATE_CHANGED_OPEN (estado_solicitado = OPEN)
- STATE_CHANGED_LATCH (estado_solicitado = DAY_LOCK)
- BLOQUEO_NOCTURNO_ESTATAL (estado_solicitado = BLOQUEO_NOCTURNO)
- STATE_CHANGED_UNKNOWN (estado_solicitado = UNKNOWN)
- MOTOR_STALL (estado_solicitado = UNKNOWN)
- STATE_CHANGED_OPEN_REMOTE (estado_solicitado = ABIERTO)
- STATE_CHANGED_LATCH_REMOTE (estado_solicitado = DAY_LOCK)
- STATE_CHANGED_NIGHT_LOCK_REMOTE (estado_solicitado = BLOQUEO_NOCTURNO)
- GO_TO_STATE_TO_LOCK (estado_solicitado = BLOQUEO_NOCTURNO)
key_local_id (nulo si p.ej. apertura manual mediante pomo o pulsando el botón). Contiene el KeyID que cambió el estado del candado.

Ir a un estado

Cuando la cerradura va a una nueva posición (puede que no alcance la posición si las pilas están casi agotadas, por ejemplo) se envían las siguientes claves JSON para los activadores trigger_state_goto_open, trigger_state_goto_latch, trigger_state_goto_night_lock:

ir_a_estado
- ABIERTO
- BLOQUEO_DÍA
- BLOQUEO NOCTURNO
tipo_evento
- GO_TO_STATE_INSTANTOPEN_OPEN ( Tocar para abrir ) (go_to_state = OPEN)
- GO_TO_STATE_INSTANTOPEN_LATCH ( Desbloqueo automático ) (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_NOCHE_LOCK (go_to__state = NOCHE_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 = BLOQUEO_NOCHE)
key_local_id (255 significa desconocido, por ejemplo apertura manual mediante pomo o pulsando un botón)

Porcentaje de batería

Cuando la cerradura envía el porcentaje de batería actual (cada pocas horas) se envían las siguientes claves JSON para el activador activador_batería:

tipo_pila (0 = alcalina, 1 = NiMH, 2 = litio (no recargable), 3 = desconocida)
porcentaje_batería

Estado en línea

Cuando la cerradura pierde la conexión con el puente, se envían las siguientes claves JSON para el disparador trigger_online_status:

wifi_strength (actualmente en dB, pronto cambiará a un porcentaje)
ble_fuerza (actualmente en dB, pronto cambiará a un porcentaje. -1 significa que la cerradura no está conectada)

Comprueba si la solicitud del webhook procede del Puente LOQED

Podrías realizar acciones delicadas si la puerta se abre (por ejemplo, encender las luces, apagar la alarma, encender la calefacción). Por lo tanto, tienes que asegurarte de que en la URL que has proporcionado, ningún otro dispositivo pueda desencadenar esas acciones. Puedes hacerlo:

Asegúrate de que ningún otro dispositivo puede llamar a la URL limitando la IP sólo a la dirección IP del Puente LOQED. Además, asegúrate de que la dirección IP del puente no cambia, fijándola en el servicio DHCP de tu router.
Verifica la firma hash enviada en las cabeceras de la llamada al webhook. En la cabecera, encontrarás TIMESTAMP (8 bytes) y HASH (hexadecimal). Puedes calcular tú mismo el hash haciendo sha256(BODY + TIMESTAMP + base64_decode(bridge_authentication_key). La clave de autenticación del puente se encuentra en https://app.loqed.com/API-Config . El BODY es el cuerpo inalterado recibido con la solicitud (con todo el código JSON). No te olvides tampoco de validar si la marca de tiempo está a unos segundos de la hora real, para evitar ataques de repetición.

Lista, añade y elimina un webhook en el puente utilizando nuestra herramienta

La forma más sencilla de listar, añadir o eliminar webhooks es utilizando nuestra herramienta Javascript:

Conéctate en https://app.loqed.com/API-Config
Desplázate hasta el título "Webhooks salientes a través del puente LOQED"
Haz clic en el botón "Añadir/Borrar webhooks" junto al puente correcto. Se abrirá la herramienta y se rellenarán previamente tu dirección IP del puente y la clave de autenticación.

Lista, añade y elimina un webhook en el puente utilizando tu código

Si quieres facilitar que los usuarios de tu producto lo conecten a LOQED, también puedes utilizar la API puente para configurar los webhooks. A continuación se describen los puntos finales de la API. Puedes consultar el código de la herramienta Javascript mencionada anteriormente si buscas un ejemplo. Puedes encontrar el Puente LOQED utilizando mDNS en tu aplicación (prueba con "DNS-sd -B _http._tcp" en Windows, por ejemplo).

Para todos los métodos del servidor web /webhooks son obligatorias dos cabeceras:

TIMESTAMP: contiene la marca de tiempo actual
HASH - cadena hash sha256

El cálculo del hash es específico para cada tipo de solicitud y se describe en la sección correspondiente. Necesitas la clave de autenticación del puente para poder calcular el hash. Esta clave se puede encontrar después de iniciar sesión en https://app.loqed.com/API-Config . No hay otra forma de recuperar esta clave.

GET:

Devuelve una matriz JSON con claves:

'id' : 1 (int)
'url' : ' https://user:pass@example.com:8080/some?key=[trigger_state_changed_open]&key2=somethingelse '
disparador_estado_cambiado_abierto' : 0/1
'enganche_disparo_estado_cambiado' : 0/1
'desencadenar_estado_cambiado_bloqueo_noche' : 0/1
disparador_estado_cambiado_desconocido' : 0/1
'trigger_state_goto_open' : 0/1
'gatillo_estado_goto_enganche' : 0/1
'activador_estado_goto_bloqueo_noche' : 0/1
batería_disparador' : 0/1
trigger_online_status' : 0/1

Devuelve los códigos HTTP:

Devuelve el código HTTP 400 BAD REQUEST y una cadena con la descripción en caso de que las cabeceras no sean válidas o no se encuentren
Devuelve HTTP 401 NO AUTORIZADO si falló la autenticación

POST:

'url' : ' https://user:pass@example.com:8080/some?key=[trigger_state_changed_open]&key2=somethingelse '
disparador_estado_cambiado_abierto' : 0/1
'enganche_disparo_estado_cambiado' : 0/1
'desencadenar_estado_cambiado_bloqueo_noche' : 0/1
disparador_estado_cambiado_desconocido' : 0/1
'trigger_state_goto_open' : 0/1
'gatillo_estado_goto_enganche' : 0/1
'activador_estado_goto_bloqueo_noche' : 0/1
batería_disparador' : 0/1
trigger_online_status' : 0/1

El HASH de la cabecera debe tener el formato: SHA256(URL + trigger_bitmap + TIMESTAMP + LOCK_TOKEN), URL es una cadena, trigger_bitmap 4 bytes, TIMESTAMP es un número de 8 bytes, y LOCK_TOKEN es la clave de seguridad del puente decodificada en base64 (!) (la clave de la página webhooks.loqed.com está en base64). El HASH debe estar en hexadecimal. El mapa_de_bit contiene los activadores. Por ejemplo, 0x000F (15 decimal) es 0000 0000 0000 1010 en binario, lo que significa que están activados los siguientes disparadores:

"activador_estado_cambiado_abierto":0
"trigger_state_changed_latch":1
"desencadenar_estado_cambiado_bloqueo_noche":0
"activador_estado_cambiado_desconocido":1
"activador_estado_goto_abierto":0
"gatillo_estado_goto_enganche":0
"activador_estado_goto_bloqueo_noche":0
"batería_disparador":0
"estado_disparador_online":0

También tenemos un pequeño fragmento de PHP que muestra cómo se crea un webhook, puedes descargarlo aquí .

Devuelve:

Código HTTP 200 OK y cadena con descripción en caso de creación correcta del webhook
Código HTTP 400 BAD REQUEST y cadena con descripción en caso de que el JSON no sea válido para la creación del webhook
Código HTTP 400 BAD REQUEST y cadena con descripción en caso de que las cabeceras no sean válidas o no se encuentren
HTTP 401 NO AUTORIZADO si falló la autenticación
Código HTTP 500 ERROR INTERNO DEL SERVIDOR y cadena con descripción en caso de que ya exista un webhook con esta URL
Código HTTP 500 ERROR INTERNO DEL SERVIDOR y cadena con descripción en caso de que se alcance el número MÁXIMO de webhooks

BORRAR:

Devuelve:

Código HTTP 200 OK y cadena con descripción en caso de borrado correcto del webhook
Código HTTP 400 BAD REQUEST y cadena con descripción en caso de que las cabeceras no sean válidas o no se encuentren
HTTP 401 NO AUTORIZADO si falló la autenticación
Código HTTP 404 NOT FOUND y cadena con descripción en caso de que no se haya encontrado el webhook con {webhookId}.
Código HTTP 500 ERROR INTERNO DEL SERVIDOR y cadena con descripción en caso de que se haya producido algún error durante la eliminación

Prueba

Te recomendamos que utilices Webhook.site si quieres verificar que tu cerradura/puente inteligente está llamando a la URL del Webhook. Allí también podrás ver los datos JSON.

Abre/cierra la puerta cuando ocurra algo (webhook entrante)

Si quieres controlar tu cerradura desde un servicio o dispositivo de terceros, puedes hacerlo mediante una llamada HTTPS GET a tu URL de LOQED Bridge.

Crear una clave API

En primer lugar, tienes que crear una nueva llave en tu Cerradura Inteligente Táctil LOQED.

Abre la página https://app.loqed.com/API-Config .
Inicia sesión con tu dirección de correo electrónico y la contraseña que utilizas para acceder a la aplicación LOQED.

Haz clic en "Añadir nueva clave API".

Introduce un nombre para facilitar la identificación. Puede ser lo que quieras.
Si tienes varios candados, puedes seleccionar el candado adecuado en el menú desplegable que aparece justo al lado de "Seleccionar candado".
Haz clic en "Añadir clave API".

Ahora has creado la clave API.

Llama a la API

Actualmente, la API admite los siguientes comandos:

Abrir (la cerradura se abre y luego vuelve al pestillo. Sólo se admite en puertas sin manilla en el exterior). Se devuelve un objeto JSON vacío.
Pestillo (desbloqueado). Se devuelve un objeto JSON vacío.
Bloqueo nocturno (bloqueado). Se devuelve un objeto JSON vacío.
Estado. ATENCIÓN: recomendamos solicitar el estado sólo una vez al día, para mantener al mínimo la carga sobre el puente. En lugar de preguntar por el estado, deberías implementar un webhook que llame a tu servidor, de modo que recibas una notificación instantánea en cuanto cambie el estado del bloqueo. Devuelve las siguientes claves JSON:
- mac_wifi (identificación del candado)
- mac_bluetooth
- cerradura_online (1 si la cerradura está online, 0 en caso contrario)
- porcentaje_de_batería (-1 si la cerradura está desconectada, en caso contrario 0 - 100)
- tipo_pila (0 = alcalina, 1 = NiMH, 2 = litio (no recargable), 3 = desconocida)
- estado_cerrojo_numérico (0 = desconocido, 1 = abierto, 2 = cierre_diurno, 3 = cierre_noche)
- estado_cerrojo (desconocido, abierto, cierre_diurno, cierre_noche)

Deja que el puente LOQED genere la firma digital

Los comandos a la cerradura inteligente deben estar firmados digitalmente. Lo más fácil es dejar que el puente LOQED genere esta firma. Sólo tienes que utilizar las cuatro URL proporcionadas (apertura, cierre, cierre nocturno, estado) que se muestran en webhooks.loqed.com. Ten en cuenta que la conexión HTTP al puente no es segura, por lo que otras personas de tu red local podrían recuperar la clave de encriptación. Si quieres enviar comandos de forma segura, tienes que generar tú mismo la firma digital.

Genera tú mismo la firma digital

En https://app.loqed.com/Bridge-API-example/ proporcionamos código de ejemplo (Javascript y PHP) que muestra cómo se crea la firma digital. Sólo puedes utilizar este método si puedes crear tu plugin para el sistema doméstico inteligente al que quieres conectarte. Los datos que necesitas (IP, secreto, KeyID) se encuentran en https://app.loqed.com/API-Config después de hacer clic en el botón "Ver / Editar" situado junto a la Clave API.