1. Resumo
As APIs permitem que as pessoas/desenvolvedores interajam com serviços em nuvem e gerenciem recursos fornecidos por um provedor de nuvem (no nosso caso Shelly Cloud).
DOCUMENTAÇÃO
2. Características
Com a API do Shelly Cloud, por enquanto (19/06/23), pode fazer as seguintes coisas
obter o estado atual do dispositivo
para relés: comutar cada saída individualmente
para tampas: comandos de abrir/fechar/parar e definir uma posição
para luzes coloridas: ligar/desligar, atualizar a cor, atualizar o ganho para cada canal
para luzes brancas: ligar/desligar, atualizar a luminosidade para cada canal
grupos (vários relés ao mesmo tempo/com um único pedido): apenas relés de acordo com a documentação
Suporta tipos de pedidos:
GET - quando vai buscar informações ao servidor (não são necessárias alterações na base de dados): para obter o estado do dispositivo
POST - quando altera/carrega novos dados para a base de dados: para alterar o estado, a cor ou as definições de saída do dispositivo
3. Como utilizar
Os pedidos podem ser enviados através de muitos métodos como curl, postman, script python, script a correr no dispositivo Shelly e etc.
Como obter o estado mais recente do dispositivo via Shelly Cloud API e curl
Caminho: https://<***server_uri>/device/status
Métodos suportados: GET e POST
Os parâmetros são fornecidos através da *query ou com o **body do pedido
Informações necessárias para enviar o pedido:
O ID do dispositivo de destino: key = 'id'
A conta ****authentication key: key = 'auth_key'
O resultado é um objeto JSON com o estado do dispositivo
Como controlar a saída de um dispositivo de relé:
Caminho: https://<***server_uri>/device/relay/control
Métodos suportados: POST
Os parâmetros são fornecidos APENAS através do **corpo do pedido
Informações necessárias para enviar o pedido:
O ID do dispositivo de destino: key = 'id'
A conta ****authentication key': key = 'auth_key'
O canal que deve ser atualizado: key = 'channel' (primeiro canal: 0 (dispositivos de canal único), segundo canal: 1)
O estado atualizado para a saída: key = 'turn' (valores suportados: ligado e desligado)
O resultado é um JSON com o ID do dispositivo de destino
Como abrir/fechar um dispositivo de persiana:
Caminho: https://<***server_uri>/device/relay/roller/control
Métodos suportados: POST
Os parâmetros são fornecidos APENAS através do **corpo do pedido
Informações necessárias para enviar o pedido:
O ID do dispositivo de destino: key = 'id'
A conta ****authentication key': key = 'auth_key'
O comando de direção: key = 'direction' (valores suportados: open, close e stop)
O resultado é um JSON com o ID do dispositivo de destino
Como definir uma posição para um dispositivo de persiana:
Caminho: https://<***server_uri>/device/relay/roller/control
Métodos suportados: POST
Os parâmetros são fornecidos APENAS através do **corpo do pedido
Informações necessárias para enviar o pedido:
O ID do dispositivo de destino: key = 'id'
A conta ****authentication key': key = 'auth_key'
Posição numa percentagem: key = 'pos' (valores suportados: todos os valores completos de 0 a 100 (inclusive))
O resultado é um JSON com o ID do dispositivo de destino
Como atualizar a saída do dispositivo de controlo de cores:
Caminho: https://<***server_uri>/device/light/control
Métodos suportados: POST
Os parâmetros são fornecidos APENAS através do **corpo do pedido
Informações necessárias para enviar o pedido:
O ID do dispositivo de destino: key = 'id'
A conta ****authentication key': key = 'auth_key'
O estado atualizado para a saída: key = 'turn' (valores suportados: on e off)
O valor para o canal branco: key= 'white' (valores suportados: todos os valores completos de 0 a 255 (inclusive))
O valor para o canal vermelho: key= 'red' (valores suportados: todos os valores completos de 0 a 255 (inclusive))
O valor para o canal verde: key= 'green' (valores suportados: todos os valores completos de 0 a 255 (inclusive))
O valor para o canal azul: key= 'blue' (valores suportados: todos os valores completos de 0 a 255 (inclusive))
O valor para o ganho: key= 'gain' (valores suportados: todos os valores completos de 0 a 100 (inclusive))
O resultado é um JSON com o ID do dispositivo de destino
Como atualizar a saída de um dispositivo de regulação da intensidade da luz:
Caminho: https://<***server_uri>/device/light/control
Métodos suportados: POST
Os parâmetros são fornecidos APENAS através do **corpo do pedido
Informações necessárias para enviar o pedido:
O ID do dispositivo de destino: key = 'id'
A conta ****authentication key': key = 'auth_key'
O estado atualizado para a saída: key = 'turn' (valores suportados: on e off)
O valor do brilho: key= 'brightness' (valores suportados: todos os valores completos de 0 a 100 (inclusive))
O resultado é um JSON com o ID do dispositivo de destino
*Consulta: Parâmetros localizados após o ponto final, começando com o símbolo de ponto de interrogação (?) e terminando com o símbolo de hashtag ou até ao fim do pedido. Os dados são formatados como pares chave=valor, em que a chave está antes do símbolo de igual (=) (ex. ivan=petyr, a chave é "ivan" e o valor é "petyr") e o valor está depois. Quando são necessários vários pares, deve separá-los com o símbolo and (&)
**corpo: Esta é a parte do pedido onde as informações sensíveis podem ser enviadas, ocultas do URL do pedido (não como a consulta). Se utilizar curl para enviar o pedido, os dados do corpo são prefixados com '-d' e os parâmetros são escritos da mesma forma que a consulta como pares chave=valor e separados com o símbolo and
***server_uri: O URL do servidor onde estão localizados todos os dispositivos e contas do cliente. Pode ser obtido na aplicação Shelly > Definições do utilizador > Chave da nuvem de autorização
**** Chave de autenticação: A chave única que é gerada é baseada na palavra-passe da conta do cliente. Quando a palavra-passe é alterada, a chave de autenticação também é alterada