Se aplica a: LOQED Touch y LOQED Pure.
Este es un artículo avanzado para desarrolladores sobre integraciones de redes locales y webhooks salientes.
La API del puente local está principalmente orientada a puentes. Para LOQED Pure o configuraciones basadas en puerta de enlace, verifique la disponibilidad actual de API antes de crear una nueva integración.
Con algunas plataformas o dispositivos domésticos inteligentes, LOQED no tiene integración directa. Si es un usuario avanzado, puede desarrollar su integración utilizando la API LOQED. Asegúrese de leer primero nuestro artículo "Usuarios avanzados: API disponibles".
Cuando la puerta esté abierta/bloqueada, llame a una URL (webhook saliente)
Cuando el estado de la cerradura cambia (abrir, desbloquear, bloquear) y para obtener otra información (porcentaje de batería, estado en línea), el LOQED Bridge puede llamar (POST datos a) una URL. A continuación puede encontrar qué datos se PUBLICAN como JSON en esta URL. También puede agregar parámetros GET de URL configurando la clave JSON entre "[" y "]". Por ejemplo: https://your.server.nl/script?yourstate=[requested_state]. También puede elegir para qué cambios se debe activar una llamada de webhook (por ejemplo, puede elegir llamar a una URL solo 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 de multidifusión del puente también contiene esta dirección.
mac_ble: contiene la dirección MAC Bluetooth del puente.
estado alcanzado
Después de que el motor dejó de funcionar, se envían las siguientes claves JSON para los activadores trigger_state_changed_open, trigger_state_changed_latch, trigger_state_changed_night_lock, trigger_state_changed_unknown:
estado_solicitado
ABRIR
DÍA_LOCK
NOCHE_BLOQUEO
DESCONOCIDO
tipo_evento
STATE_CHANGED_OPEN (estado_solicitado = ABIERTO)
STATE_CHANGED_LATCH (estado_solicitado = DAY_LOCK)
STATE_CHANGED_NIGHT_LOCK (estado_solicitado = NIGHT_LOCK)
STATE_CHANGED_UNKNOWN (estado_solicitado = DESCONOCIDO)
MOTOR_STALL (estado_solicitado = DESCONOCIDO)
STATE_CHANGED_OPEN_REMOTE (estado_solicitado = ABIERTO)
STATE_CHANGED_LATCH_REMOTE (estado_solicitado = DAY_LOCK)
STATE_CHANGED_NIGHT_LOCK_REMOTE (estado_solicitado = NIGHT_LOCK)
GO_TO_STATE_TOUCH_TO_LOCK (estado_solicitado = NIGHT_LOCK)
key_local_id (nulo si, por ejemplo, apertura manual mediante perilla o pulsando un botón). Contiene el KeyID que cambió el estado de la cerradura.
Ir a un estado
Cuando la cerradura va a una nueva posición (es posible que no alcance la posición si las baterías 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_al_estado
ABRIR
DÍA_LOCK
NOCHE_BLOQUEO
tipo_evento
GO_TO_STATE_INSTANTOPEN_OPEN (Touch to Open) (go_to_state = ABIERTO)
GO_TO_STATE_INSTANTOPEN_LATCH (Desbloqueo automático) (go_to_state = DAY_LOCK)
GO_TO_STATE_MANUAL_UNLOCK_BLE_OPEN (go_to_state = ABIERTO)
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 = ABIERTO)
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 = ABIERTO)
GO_TO_STATE_MANUAL_UNLOCK_VIA_OUTSIDE_MODULE_BUTTON (go_to_state = ABIERTO)
GO_TO_STATE_TOUCH_TO_LOCK (go_to_state = NOCHE_LOCK)
key_local_id (255 significa desconocido, por ejemplo, apertura manual mediante perilla o pulsando un botón)
Porcentaje de batería
Cuando la cerradura envía el porcentaje actual de la batería (cada pocas horas), se envían las siguientes claves JSON para el activador. disparador_batería:
tipo_batería (0 = alcalina, 1 = NiMH, 2 = litio (no recargable), 3 = desconocido)
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_strength (actualmente en dB, pronto esto cambiará a un porcentaje. -1 significa que la cerradura no está conectada)
Verifique si la solicitud del webhook provino del LOQED Bridge
Podrías tomar acciones sensibles si la puerta se abre (por ejemplo, encender las luces, apagar la alarma, encender el calentador). Por lo tanto, debe asegurarse de que en la URL que proporcionó ningún otro dispositivo pueda desencadenar tales acciones. Puedes:
Asegúrese de que ningún otro dispositivo pueda llamar a la URL limitando la IP solo a la dirección IP del LOQED Bridge. Además, asegúrese de que la dirección IP del puente no cambie solucionándola en el servicio DHCP de su enrutador.
Verifique la firma hash enviada en los encabezados de la llamada del webhook. En el encabezado, encontrará TIMESTAMP (8 bytes) y HASH (hexadecimal). Puede calcular el hash usted mismo haciendo sha256(BODY + TIMESTAMP + base64_decode(bridge_authentication_key). La clave de autenticación del puente se puede encontrar en https://app.loqed.com/API-Config. El BODY es el cuerpo inalterado recibido con la solicitud (con todo el código JSON). Además, no olvide validar si la marca de tiempo está dentro de unos segundos de la hora real, para evitar ataques de repetición.
Enumere, agregue y elimine un webhook en el puente usando nuestra herramienta
La forma más sencilla de enumerar, agregar o eliminar webhooks es mediante nuestra herramienta Javascript:
Iniciar sesión https://app.loqed.com/API-Config
Desplácese hasta el título "Webhooks salientes a través de LOQED Bridge"
Haga clic en el botón "Agregar/eliminar webhooks" al lado del puente correcto. La herramienta se abrirá y su dirección IP de puente y su clave de autenticación estarán precompletadas.
Enumere, agregue y elimine un webhook en el puente usando su código
Si desea que a los usuarios de su producto les resulte más fácil conectarlo a LOQED, también puede utilizar la API puente para configurar los webhooks. A continuación se describen los puntos finales de la API. Puede consultar el código de la herramienta Javascript mencionada anteriormente si está buscando un ejemplo. El LOQED Bridge se puede encontrar usando mDNS en su aplicación (pruebe con "DNS-sd -B _http._tcp" en Windows, por ejemplo)
Para todos los métodos de servidor web /webhooks, son obligatorios dos encabezados:
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 el apartado correspondiente. Necesita 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.
Listar webhooks
OBTENER: https://bridge-ip-address/webhooks
El HASH en el encabezado debe tener el formato: SHA256(TIMESTAMP + LOCK_TOKEN), donde TIMESTAMP es un número de 8 bytes y LOCK_TOKEN es la clave de seguridad del puente decodificada en base64 (!) (la clave en la página webhooks.loqed.com está en base64). El HASH debe estar en hexadecimal.
Devuelve una matriz JSON con claves:
'identificación' : 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
'trigger_battery': 0/1
'trigger_online_status': 0/1
Devuelve códigos HTTP:
Devuelve el código HTTP 400 BAD REQUEST y una cadena con una descripción en caso de que los encabezados no sean válidos o no se encuentren
Devuelve HTTP 401 NO AUTORIZADO si falla la autenticación
Crear webhook
PUBLICAR: http://dirección-ip-puente/webhooks
Cuerpo: JSON con claves:
'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
'trigger_battery': 0/1
'trigger_online_status': 0/1
El HASH en el encabezado debe tener 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 en la página webhooks.loqed.com está en base64). El HASH debe estar en hexadecimal. El trigger_bitmap contiene los activadores. Por ejemplo, 0x000F (15 decimal) es 0000 0000 0000 1010 en binario, lo que significa que los siguientes activadores están habilitados:
"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
"batería_disparador": 0
"trigger_online_status":0
También tenemos un pequeño fragmento de PHP que muestra cómo se crea un webhook. puedes descargarlo aquí.
Devoluciones:
Código HTTP 200 OK y cadena con descripción en caso de creación exitosa del webhook
Código HTTP 400 BAD REQUEST y cadena con descripción en caso de que JSON no sea válido para la creación de webhook
Código HTTP 400 BAD REQUEST y cadena con descripción en caso de que los encabezados no sean válidos o no se encuentren
HTTP 401 NO AUTORIZADO si la autenticación falló
Código de ERROR DEL SERVIDOR INTERNO HTTP 500 y cadena con descripción en caso de que ya exista un webhook con esta URL
Código de ERROR DEL SERVIDOR INTERNO HTTP 500 y cadena con descripción en caso de que se alcance el número MÁXIMO de webhooks
Eliminar webhook
BORRAR: http://dirección-ip-puente/webhooks/{webhookId}
El HASH en el encabezado debe tener formato: SHA256(id + TIMESTAMP + LOCK_TOKEN), ID es un número de 8 bytes, TIMESTAMP es un número de 8 bytes y LOCK_TOKEN es la clave de seguridad del puente decodificada en base64 (!) (la clave en la página webhooks.loqed.com está en base64). El HASH debe estar en hexadecimal.
Devoluciones:
Código HTTP 200 OK y cadena con descripción en caso de eliminación exitosa del webhook
Código HTTP 400 BAD REQUEST y cadena con descripción en caso de que los encabezados no sean válidos o no se encuentren
HTTP 401 NO AUTORIZADO si la autenticación falló
Código HTTP 404 NO ENCONTRADO y cadena con descripción en caso de que no se encuentre el webhook con {webhookId}
Código de ERROR DEL SERVIDOR INTERNO HTTP 500 y cadena con descripción en caso de que se produzca algún error durante la eliminación
Pruebas
Recomendamos usar Webhook.sitio si desea verificar que su cerradura/puente inteligente esté llamando a la URL del Webhook. También podrás ver los datos JSON allí.
Abrir/cerrar la puerta cuando suceda algo (webhook entrante)
Si desea controlar su bloqueo desde un servicio o dispositivo de terceros, puede hacerlo mediante una llamada HTTPS GET a su URL LOQED Bridge.
Crear una clave API
Primero, debe crear una nueva clave en su cerradura inteligente LOQED.
abre la pagina https://app.loqed.com/API-Config.
Inicie sesión con su dirección de correo electrónico y contraseña que utiliza para iniciar sesión en LOQED app.
Haga clic en "Agregar nueva clave API".
Introduzca un nombre para una fácil identificación. Esto puede ser lo que quieras.
Si tiene varios candados, puede seleccionar el candado correcto en el menú desplegable justo al lado de "Seleccionar candado".
Haga clic en "Agregar clave API".
Ahora ha creado la clave API.
Llame a la API
Actualmente, la API admite los siguientes comandos:
Abierto (la cerradura se abre y luego vuelve al pestillo. Solo se admite en puertas sin manija 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 solo una vez al día, para mantener al mínimo la carga en el puente. En lugar de preguntar por el estado, debe implementar un webhook que llame a su servidor, de modo que reciba una notificación instantánea tan pronto como cambie el estado de bloqueo. Devuelve las siguientes claves JSON:
mac_wifi (identificación de bloqueo)
mac_bluetooth
lock_online (1 si el bloqueo está en línea, en caso contrario 0)
porcentaje de batería (-1 si el bloqueo está fuera de línea; de lo contrario, 0 - 100)
tipo_batería (0 = alcalina, 1 = NiMH, 2 = litio (no recargable), 3 = desconocido)
Bolt_state_numeric (0 = desconocido, 1 = abierto, 2 = bloqueo diurno, 3 = bloqueo nocturno)
Bolt_state (desconocido, abierto, day_lock, night_lock)
Deje que el puente LOQED genere la firma digital
Los comandos de la cerradura inteligente deben estar firmados digitalmente. Lo más sencillo es dejar que el puente LOQED genere esta firma. Simplemente use las cuatro URL proporcionadas (abierto, cerrado, bloqueo nocturno, estado) que se muestran en webhooks.loqed.com. Tenga en cuenta que la conexión HTTP al puente no está segura, por lo que otras personas en su red local podrían recuperar la clave de cifrado. Si desea enviar comandos de forma segura, debe generar la firma digital usted mismo.
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 complemento para el sistema doméstico inteligente al que deseas conectarte. Los datos que necesita (IP, secreto, KeyID) se pueden encontrar en https://app.loqed.com/API-Config después de hacer clic en el botón "Ver/Editar" al lado de la clave API.