1. Resumen
Las APIs permiten a las personas/desarrolladores interactuar con servicios en la nube y gestionar recursos proporcionados por un proveedor de nube (en nuestro caso Shelly Cloud).
2. Características
Con la API de Shelly Cloud hasta ahora (6/19/23) puedes hacer las siguientes cosas:
- obtener el estado actual del dispositivo
- para relés: cambiar cada salida individualmente
- para cubiertas: comandos abrir/cerrar/parar y establecer una posición
- para luces de color: encender/apagar, actualizar color, actualizar ganancia para cada canal
- para luces blancas: encender/apagar, actualizar brillo para cada canal
- grupos (múltiples relés al mismo tiempo/con una sola solicitud): solo relés según la documentación
Tipos de solicitudes compatibles:
- GET - cuando se obtiene información del servidor (no se requieren cambios en la base de datos): para obtener el estado del dispositivo
- POST - cuando se cambian/suben nuevos datos a la base de datos: para cambiar el estado de salida, color o configuraciones del dispositivo
3. Cómo usar
Las solicitudes se pueden enviar a través de muchos métodos como curl, postman, script de python, script ejecutándose en dispositivo Shelly y etc.
Cómo obtener el estado más reciente del dispositivo a través de Shelly Cloud API y curl
- Ruta: https://<***server_uri>/device/status
- Métodos soportados: GET y POST
- Los parámetros se proporcionan a través de la *consulta o con el **cuerpo de la solicitud
- Información requerida para enviar la solicitud:
- El ID del dispositivo objetivo: clave = 'id'
- La clave de ****autenticación de la cuenta: clave = 'auth_key'
- El resultado es un objeto JSON con el estado del dispositivo
Cómo controlar la salida para un dispositivo de relé:
- Ruta: https://<***server_uri>/device/relay/control
- Métodos soportados: POST
- Los parámetros se suministran ÚNICAMENTE a través del **cuerpo de la solicitud
- Información requerida para enviar la solicitud:
- El ID del dispositivo objetivo: clave = 'id'
- La clave de ****autenticación de la cuenta': clave = 'auth_key'
- El canal que debe actualizarse: clave = 'channel' (primer canal: 0 (dispositivos de un solo canal), segundo canal: 1)
- El estado actualizado para la salida: clave = 'turn' (valores soportados: on y off)
- El resultado es un JSON con el ID del dispositivo objetivo
Cómo abrir/cerrar un dispositivo de persiana enrollable:
- Ruta: https://<***server_uri>/device/relay/roller/control
- Métodos soportados: POST
- Los parámetros se suministran ÚNICAMENTE a través del **cuerpo de la solicitud
- Información requerida para enviar la solicitud:
- El ID del dispositivo objetivo: clave = 'id'
- La clave de ****autenticación de la cuenta': clave = 'auth_key'
- El comando de dirección: clave = 'direction' (valores soportados: open, close y stop)
- El resultado es un JSON con el ID del dispositivo objetivo
Cómo establecer una posición para un dispositivo de persiana enrollable:
- Ruta: https://<***server_uri>/device/relay/roller/control
- Métodos soportados: POST
- Los parámetros se proporcionan ÚNICAMENTE a través del **cuerpo de la solicitud
- Información requerida para enviar la solicitud:
- El ID del dispositivo objetivo: clave = 'id'
- La clave de ****autenticación de la cuenta': clave = 'auth_key'
- Posición en porcentaje: clave = 'pos' (valores soportados: cada valor entero de 0 a 100 (incluido))
- El resultado es un JSON con el ID del dispositivo objetivo
Cómo actualizar la salida del dispositivo de control de color:
- Ruta: https://<***server_uri>/device/light/control
- Métodos soportados: POST
- Los parámetros se proporcionan ÚNICAMENTE a través del **cuerpo de la solicitud
- Información requerida para enviar la solicitud:
- El ID del dispositivo objetivo: clave = 'id'
- La clave de ****autenticación de la cuenta': clave = 'auth_key'
- El estado actualizado para la salida: clave = 'turn' (valores soportados: on y off)
- El valor para el canal blanco: clave= 'white' (valores soportados: cada valor entero de 0 a 255 (incluido))
- El valor para el canal rojo: key= 'red' (valores soportados: cualquier valor entero de 0 a 255 (incluido))
- El valor para el canal verde: key= 'green' (valores soportados: cualquier valor entero de 0 a 255 (incluido))
- El valor para el canal azul: key= 'blue' (valores soportados: cualquier valor entero de 0 a 255 (incluido))
- El valor para la ganancia: key= 'gain' (valores soportados: cualquier valor entero de 0 a 100 (incluido))
- El resultado es un JSON con el ID del dispositivo objetivo
Cómo actualizar la salida de un dispositivo de atenuación :
- Ruta: https://<***server_uri>/device/light/control
- Métodos soportados: POST
- Los parámetros se proporcionan ÚNICAMENTE a través del **cuerpo de la solicitud
- Información requerida para enviar la solicitud:
- El ID del dispositivo objetivo: key = 'id'
- La clave de ****autenticación de la cuenta': key = 'auth_key'
- El estado actualizado para la salida: key = 'turn' (valores soportados: on y off)
- El valor de brillo: key= 'brightness' (valores soportados: cualquier valor entero de 0 a 100 (incluido))
- El resultado es un JSON con el ID del dispositivo objetivo
*consulta: Parámetros ubicados después del endpoint que comienzan con el símbolo de interrogación (?) y terminan con el símbolo de hashtag o hasta el final de la solicitud. Los datos están formateados como pares clave=valor, donde la clave está antes del símbolo igual (=) (ej. ivan=petyr, la clave es "ivan", y el valor es "petyr") y el valor está después de él. Cuando se necesitan múltiples pares deben estar separados con el símbolo y (&)
**cuerpo: Esta es la parte de la solicitud donde se puede enviar información sensible, oculta de la URL de la solicitud (no como la consulta). Si se usa curl para enviar la solicitud, los datos del cuerpo van precedidos por '-d' y los parámetros se escriben igual que la consulta como pares clave=valor y separados con el símbolo y
***server_uri: La URL del servidor donde se encuentran todos los dispositivos y cuentas del cliente. Esto se puede obtener desde la App Shelly > Configuración de usuario > Clave de nube de autorización
****Clave de autenticación: Clave única cuya generación se basa en la contraseña de la cuenta del cliente. Cuando se cambia la contraseña, la clave de autenticación también cambia