Ir al contenido principal

Integración de API web LOQED

Guía avanzada para desarrolladores: reciba eventos de bloqueo con webhooks, controle su bloqueo LOQED y cambie la configuración de bloqueo.

Se aplica a: LOQED Touch y LOQED Pure.

Este es un artículo avanzado para desarrolladores sobre las API web LOQED, webhooks entrantes y eventos de webhooks salientes.

Las configuraciones específicas de Touch Display, como Open House Mode, se aplican a LOQED Pure solo cuando está instalado el LOQED Touch Display opcional.

Algunas plataformas y dispositivos domésticos inteligentes aún no tienen una integración directa con LOQED. Si es un usuario avanzado o un desarrollador, puede crear su propia integración utilizando las API LOQED. Antes de empezar, te recomendamos leer nuestro artículo. "Usuarios avanzados: API disponibles" primero.

LOQED ofrece tres formas de integrarse con su cerradura:

  • Webhooks salientes – permita que su bloqueo notifique a una URL externa cada vez que cambie su estado (por ejemplo, para activar automatizaciones).

  • Webhooks entrantes – controlar su cerradura (apertura, pestillo, cerradura nocturna) desde otro servicio o dispositivo.

  • API de integraciones – una API REST basada en token para enumerar sus bloqueos, cambiar el estado del bloqueo y cambiar la configuración del bloqueo, como Open House Mode y Twist Assist.

Webhooks salientes: llame a una URL externa cuando cambie el bloqueo

Cuando el bloqueo alcanza una nueva posición (abierto, desbloqueo/bloqueo diurno, bloqueo/bloqueo nocturno), el backend LOQED puede enviar datos (POST) a una URL de su elección. Puede registrar la URL a la que desea que le llamen en el API sección sobre app.loqed.com (ver más abajo).

Debido a que no todos los sistemas admiten JSON, también puede configurar una URL separada para cada evento (por ejemplo, una URL para abrir y otra para bloquear). En ese caso el estado_solicitado El valor es siempre el mismo para esa URL.

Carga útil del evento: estado alcanzado

Esta carga útil se envía cuando el bloqueo se ha activado. alcanzado una posición. Ejemplo del JSON publicado en su URL:

{
  "requested_state": "DAY_LOCK",
  "event_type": "STATE_CHANGED_LATCH",
  "lock_id": "Yq1gK4oeE9KWe0ByxjX2",
  "key_local_id": 3,
  "key_name_user": "Puerta de entrada",
  "key_name_admin": "Jane Doe",
  "key_account_e-mail": "jane@example.com",
  "key_account_name": "Jane Doe"
}

Campos

  • estado_solicitado – la posición alcanzada: ABRIR, DÍA_LOCK, NOCHE_BLOQUEO o DESCONOCIDO.

  • tipo_evento – uno de:

    • ESTADO_CHANGED_OPEN (estado_solicitado = ABIERTO)

    • STATE_CHANGED_LATCH (estado_solicitado = DAY_LOCK)

    • STATE_CHANGED_NIGHT_LOCK (estado_solicitado = NOCHE_BLOQUEO)

    • ESTADO_CHANGED_UNKNOWN (estado_solicitado = DESCONOCIDO)

    • MOTOR_STALL (estado_solicitado = DESCONOCIDO)

  • id_bloqueo – el identificador de su cerradura.

  • clave_local_id, nombre_clave_usuario, nombre_clave_admin – nulo cuando la acción no fue activada por una tecla (por ejemplo, un giro manual de la perilla o la pulsación de un botón).

  • cuenta_clave_correo electrónico, nombre_cuenta_clave – nulo para acciones manuales, o cuando se utiliza un PIN que no está vinculado a una cuenta.

Carga útil del evento: ir a un estado

También puedes recibir un webhook cuando el bloqueo comienza a moverse hacia una nueva posición. Es posible que el bloqueo no llegue a la posición (por ejemplo, cuando las pilas están casi agotadas). Estos acontecimientos marcaron la ir_al_estado atributo con el estado del perno objetivo.

{
  "go_to_state": "ABIERTO",
  "event_type": "GO_TO_STATE_INSTANTOPEN_OPEN",
  "lock_id": "Yq1gK4oeE9KWe0ByxjX2",
  "key_local_id": 3,
  "key_name_user": "Puerta de entrada",
  "key_name_admin": "Jane Doe",
  "key_account_e-mail": "jane@example.com",
  "key_account_name": "Jane Doe"
}

Posible ir_al_estado valores: ABRIR, DÍA_LOCK, NOCHE_BLOQUEO.

Posible tipo_evento valores:

  • 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 (ir_a_estado = NOCHE_BLOQUEO)

  • 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 (ir_a_estado = NOCHE_BLOQUEO)

  • 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 (ir_a_estado = NOCHE_BLOQUEO)

  • GO_TO_STATE_MANUAL_UNLOCK_REMOTE_OPEN

  • GO_TO_STATE_MANUAL_LOCK_REMOTE_LATCH

  • GO_TO_STATE_MANUAL_LOCK_REMOTE_NIGHT_LOCK

el id_bloqueo y clave_* Los campos se comportan igual que se describe arriba.

Gancho web de resistencia Bluetooth y Wi-Fi

Cada pocas horas, y siempre que la cerradura o el puente estén encendidos, se puede enviar una actualización de los niveles de señal. Habilite la marca de verificación correspondiente en el API sección sobre app.loqed.com para recibir esta información.

{
  "ble_strength": 42,
  "fuerza_wifi": 73,
  "porcentaje_batería": 88,
  "lock_id": "Yq1gK4oeE9KWe0ByxjX2"
}

  • fuerza_ble – Señal Bluetooth como porcentaje. Esto fluctúa mucho, así que no te preocupes si es bajo.

  • fuerza_wifi – Señal Wi-Fi como porcentaje.

  • porcentaje_batería – nivel de batería como porcentaje.

  • id_bloqueo – el identificador de su cerradura.

Bloquear webhook en línea

Cada pocas horas, y siempre que la cerradura o el puente estén encendidos, se puede enviar una actualización "en línea". Habilite la marca de verificación correspondiente para recibir esta información.

{
  "en línea": 1,
  "lock_id": "Yq1gK4oeE9KWe0ByxjX2"
}

  • en línea – 1 se envía como valor.

  • id_bloqueo– el identificador de su cerradura.

Probando su webhook

Recomendamos usar Webhook.sitio para verificar que su cerradura inteligente esté llamando a la URL del webhook. También le permite inspeccionar los datos JSON que se envían.

Webhooks entrantes: controla el bloqueo

Si desea controlar su bloqueo desde un servicio o dispositivo de terceros, puede hacerlo con un HTTPS OBTENER solicitud a una URL LOQED.

Inicie sesión y abra la sección API

  1. Abierto app.loqed.com en tu navegador.

  2. Inicie sesión con la dirección de correo electrónico de su cuenta LOQED app. Se enviará un código de verificación (2FA) a su correo electrónico; ingréselo para continuar.

  3. En el menú, elija API. Aquí es donde administra sus webhooks y claves API salientes y entrantes.

Crear una clave API

En esta página puede agregar webhooks salientes y crear webhooks entrantes.

  • Haga clic Agregar nueva clave API.

  • Ingrese un nombre para que pueda reconocer la clave más tarde. Puede ser cualquier cosa; no es necesario que coincida con el nombre de su clave.

  • Si tiene varias cerraduras, seleccione la correcta de la lista. Seleccionar Bloquear menú desplegable.

  • Haga clic Agregar clave API.

Su clave API ya ha sido creada.

Llame a la API

Actualmente, la API admite los siguientes comandos:

  • Abierto – la puerta se abre. Se devuelve un objeto JSON vacío.

  • pestillo – la puerta está desbloqueada (bloqueo diurno). Se devuelve un objeto JSON vacío.

  • bloqueo nocturno – la puerta está cerrada. Se devuelve un objeto JSON vacío.

  • Estado – devuelve el estado actual de la cerradura (ver más abajo).

⚠️ Importante: solicitar el Estado como máximo una vez al día. Si lo solicitas más de 12 veces serás bloqueado por 12 horas. En lugar de sondear el estado, configure un webhook saliente para que su servidor reciba una notificación instantánea cada vez que cambie el estado de bloqueo.

el Estado El comando devuelve el siguiente JSON:

{
  "id": "Yq1gK4oeE9KWe0ByxjX2",
  "puente_en línea": 1,
  "lock_online": 1,
  "porcentaje_batería": 88,
  "tipo_batería": 0,
  "bolt_state_numeric": 2,
  "bolt_state": "día_lock",
  "modo_acceso_invitado": 0,
  "asistencia_giro": 0,
  "tocar_para_conectar": 0
}

  • identificación – identificador de bloqueo.

  • puente_en línea – 1 si el puente está en línea, de lo contrario 0.

  • lock_online – 1 si el bloqueo está en línea, de lo contrario 0.

  • porcentaje_batería – -1 si el bloqueo está fuera de línea, de lo contrario 0–100.

  • tipo_batería – 0 = alcalino, 1 =NiMH, 2 = Litio (no recargable), 3 = desconocido.

  • perno_estado_numérico – 0 = desconocido, 1 = abierto, 2= bloqueo_día, 3 = bloqueo_noche.

  • estado_perno – desconocido, abierto, bloqueo_dia o bloqueo_noche.

  • modo_acceso_invitado – 1 si está habilitado, 0 si está deshabilitado.

  • asistencia_giro – 1 si está habilitado, 0 si está deshabilitado.

  • tocar_para_conectar – 1 si se elimina la restricción de 500 m Touch to Open, en caso contrario 0.

Deje que LOQED genere la firma digital

Los comandos de la cerradura inteligente deben estar firmados digitalmente. La opción más sencilla es dejar que el servidor LOQED genere esta firma por usted: simplemente utilice las cuatro URL ya preparadas (abierta, cerrada, bloqueo nocturno, estado) que se muestran en la API sección sobre app.loqed.com.

Genera tú mismo la firma digital

Si prefiere conservar su clave de cifrado y no enviarla al servidor LOQED, puede generar la firma digital usted mismo. en app.loqed.com/ejemplo-API-backend proporcionamos código de ejemplo (JavaScript y PHP) que muestra cómo se crea la firma.

API de integraciones: leer bloqueos y cambiar configuraciones

el API de integraciones es una API REST basada en tokens. Con un único token de acceso personal, puede enumerar sus bloqueos, cambiar el estado del bloqueo y cambiar la configuración del bloqueo, como Open House Mode y Twist Assist.

La URL base para todos los puntos finales es:

https://integrations.production.loqed.com

Cada solicitud debe incluir su token de acceso personal en el Autorización encabezado:

Autorización: Portador YOUR_PERSONAL_ACCESS_TOKEN

Generar un token de acceso personal

Abre el Página de token de acceso personal LOQED y sigue estos pasos:

  1. Inicie sesión con la dirección de correo electrónico de su cuenta LOQED app (debe ser un administrador).

  2. Toque crear.

  3. Asigne al token un nombre reconocible (por ejemplo, el nombre de la integración que está creando).

  4. Toque Guardar.

  5. Copie el token y guárdelo en un lugar seguro; lo utilizará como Portador token en cada solicitud. Trátelo como una contraseña.

Lista tus cerraduras

Utilice este punto final para recuperar todos los bloqueos disponibles para su cuenta, incluido su estado y configuración actuales. Necesitarás la cerradura identificación para los otros puntos finales.

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

Ejemplo con cURL:

rizo -X OBTENER "https://integrations.production.loqed.com/api/locks/" \
  -H "Autorización: Portador YOUR_PERSONAL_ACCESS_TOKEN"

Respuesta de ejemplo:

{
  "datos": [
    {
      "id": "Yq1gK4oeE9KWe0ByxjX2",
      "nombre": "Puerta de entrada",
      "model_name": "LOQED",
      "porcentaje_batería": 95,
      "battery_type": "alcalina",
      "bolt_state": "día_lock",
      "modo_fiesta": falso,
      "guest_access_mode": falso,
      "twist_assist": falso,
      "touch_to_connect": falso,
"lock_direction": "en sentido antihorario",
      "mortise_lock_type": "cilindro_operado_sin_manija_en_el_exterior",
      "estados_bloqueo_compatibles": [
        "abierto",
        "día_bloqueo",
        "bloqueo_noche"
      ]
    }
  ]
}

Cambiar el estado de bloqueo

Opere una cerradura llamando al estado_perno punto final. Los estados de pernos disponibles son abierto, bloqueo_dia y bloqueo_noche.

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

Ejemplo con cURL (desbloqueo para bloqueo de día):

rizo -X OBTENER "https://integrations.production.loqed.com/api/locks/Yq1gK4oeE9KWe0ByxjX2/bolt_state/day_lock" \
  -H "Autorización: Portador YOUR_PERSONAL_ACCESS_TOKEN"

Cambiar una configuración de bloqueo

Utilice este punto final para cambiar una configuración de bloqueo como Open House Mode, Twist Assist, la dirección de bloqueo o la zona horaria.

PUBLICACIÓN https://integrations.production.loqed.com/api/locks/{lockId}/setting

Envíe un cuerpo JSON con el nombre de la configuración y su nuevo valor. Por ejemplo, a habilitar Open House Mode:

{
  "setting_name": "open_house_mode",
  "valor_configuración": 1
}

a habilitar Twist Assist:

{
  "setting_name": "twist_assist",
  "valor_configuración": 1
}

Ejemplo completo con cURL:

rizo -X POST "https://integrations.production.loqed.com/api/locks/Yq1gK4oeE9KWe0ByxjX2/setting" \
  -H "Autorización: Portador YOUR_PERSONAL_ACCESS_TOKEN" \
  -H "Tipo de contenido: aplicación/json" \
  -d '{"nombre_configuración": "modo_casa_abierta", "valor_configuración": 1}'

valor_configuración es un entero de 32 bits con signo. La mayoría de las configuraciones son simples opciones de encendido/apagado que aceptan 0 (apagado) y 1 (activado), pero algunos esperan valores específicos. Cambie una configuración a la vez y verifique el resultado en su cerradura o en el LOQED app.

Configuraciones disponibles

Las configuraciones siguientes son los conmutadores más utilizados (0 = apagado, 1 = encendido):

nombre_configuración

que hace

modo_casa_abierta

Mantiene la puerta cerrada durante el día para que se pueda abrir con la manija sin desbloquearla cada vez.

asistencia_giro

Le da al cerrojo un giro adicional para ayudar a operar puertas rígidas.

tocar_para_conectar

Elimina el requisito de geovalla de 500 m para Touch to Open.

tocar_para_bloquear

Cierra la puerta tocando el exterior de la cerradura.

mantener_para_bloquear

Bloquee la puerta tocando y sosteniendo el exterior de la cerradura.

Consejo: para confirmar que su token funciona, envíe un OBTENER solicitar a https://integrations.production.loqed.com/api/locks/ con tu Autorización: Portador encabezado. Una lista de sus cerraduras confirma que todo está configurado correctamente.

Artículos relacionados
API disponibles LOQED
Integración de API de puente local LOQED
Integración de Loxone y LOQED
Integración de Home Assistant y LOQED
Integración de Domoticz y LOQED
¿Ha quedado contestada tu pregunta?