Levar dados de dispositivo para o seu SaaS

Caso de uso

Use este padrão quando a capacidade dos dispositivos WLTE for uma parte do seu próprio produto (um SaaS multiinquilino, um sistema de operações interno ou similar). Seus usuários finais interagem com o seu produto e com o seu próprio sistema de contas: eles nunca lidam diretamente com as credenciais do WLTE.

• Uma única conta WLTE e um único API Client sustentam toda a sua implantação, não uma credencial por cliente final.
• Os dispositivos de uma conta WLTE são planos; não existe o conceito de inquilino. Quais dispositivos pertencem a qual cliente é um mapeamento que você define e mantém.
• Os eventos ao vivo precisam fluir de forma contínua para o seu próprio pipeline de dados (banco de dados, fila de mensagens, seu próprio WebSocket ou webhook), em vez de cada página de cada cliente final manter sua própria conexão com o WLTE.

Nunca entregue o clientId, o clientSecret nem um access token a um cliente final. Não presuma que os dispositivos de uma conta são isolados por inquilino: eles não são.

Arquitetura recomendada

Somente o seu backend guarda as credenciais do WLTE. Mantenha um mapeamento deviceId → tenantId, atenda todos os inquilinos a partir de uma única conexão WebSocket, e distribua os dados para o restante do seu sistema.

Implementação passo a passo

1. Projete e mantenha um mapeamento deviceId → tenantId (ou o identificador de cliente/site que você usar). As contas WLTE não distinguem inquilinos: esta tabela é a estrutura de dados central de toda a integração.
2. Obtenha um access token a partir do seu único API Client, mantido no servidor: device:read para uso somente leitura, mais device:control ou device:config se você enviar comandos.
3. Chame Listar dispositivos (em inglês) e Listar definições de tipo de dispositivo (em inglês) para construir a base de estado inicial, e depois divida-a em visões por inquilino usando sua tabela de mapeamento.
4. Crie um ticket de WebSocket (em inglês) de uso único e estabeleça uma única conexão — não uma por inquilino — para receber eventos de conexão, eventos de mudança de estado e eventos de energia (em inglês).
5. Em cada evento, primeiro busque o inquilino a partir do deviceId, e depois grave no seu próprio armazenamento ou fila para que sua API/WebSocket/webhook possa enviá-lo aos clientes desse inquilino.
6. Quando um cliente final enviar uma solicitação de controle, autorize-a primeiro contra o seu próprio sistema de permissões (as permissões por inquilino do seu produto, não um scope do WLTE), e faça com que seu backend atue como proxy da requisição para o WLTE com uma chave de idempotência.
7. Persista você mesmo os resultados de comandos e os eventos onde precisar de retenção de longo prazo ou de um registro para faturamento: o WLTE não reproduz o histórico de eventos, e os registros de comandos são mantidos apenas por pouco tempo.

Interfaces e eventos principais

Finalidade	Referência
Construir a base de estado	Listar dispositivos (em inglês)
Visões multiinquilino orientadas por capacidades	Listar definições de tipo de dispositivo (em inglês)
Adicionar um dispositivo à conta	Adicionar dispositivo à conta (em inglês)
Autenticação WebSocket	Criar WebSocket Ticket (em inglês)
Mudanças de conectividade	Eventos de conexão de dispositivo (em inglês)
Mudanças de estado de periféricos	Evento de mudança de estado do dispositivo (em inglês)
Notificações de queda e restauração de energia	Eventos de energia de dispositivo (em inglês)
Fazer proxy de um comando de controle	Criar comando de relé (em inglês)
Consultar o resultado de um comando	Consultar resultado de comando (em inglês)

Falhas e recuperação

• Os limites de taxa são contados por API Client. Vários inquilinos que compartilham uma conta compartilham o mesmo orçamento de limite de taxa: a taxa alta de um único inquilino pode esgotar a cota de toda a conta, então limite e enfileire na sua própria camada em vez de repassar diretamente ao WLTE a taxa de requisições dos seus clientes finais.
• Se a conexão WebSocket a montante for perdida, reconecte essa única conexão de servidor em vez de reconectar por inquilino; marque os dados a jusante como potencialmente desatualizados enquanto reconecta.
• Os eventos perdidos enquanto você estava desconectado não são reproduzidos. Reconstrua a base de estado via REST após reconectar, e depois retome as atualizações orientadas por eventos.
• Os registros de comandos e as chaves de idempotência são mantidos no lado do WLTE por apenas cerca de 48 horas. Persista você mesmo os resultados de comandos e o status final se precisar de uma janela de auditoria ou faturamento mais longa.
• Diante de um 429 RATE_LIMITED, aguarde o Retry-After. Não implemente um loop de tentativas independente por inquilino no seu próprio serviço.

Considerações para produção

• Os clientes finais nunca devem ver nem obter, sob nenhuma circunstância, o clientId, o clientSecret nem um access token do WLTE: toda chamada ao WLTE deve passar pelo seu backend.
• Os quatro scopes do WLTE (device:read/device:control/device:config/device:manage) são permissões grosseiras, em nível de conta. Eles não substituem o seu próprio modelo de permissões refinado por cliente: são duas camadas de autorização separadas.
• Trate o mapeamento deviceId → tenantId como a tabela mais importante do seu sistema; mantenha-o sincronizado sempre que dispositivos forem adicionados ou removidos da conta, ou que clientes adicionem ou removam sites, para evitar que dados cruzem para o inquilino errado.
• Planeje seu orçamento de limite de taxa com antecedência: o número de inquilinos faz seu volume de requisições crescer de forma linear, mas o limite de taxa da conta não cresce com ele.
• Consulte Scopes de autorização (em inglês) para as combinações de scopes disponíveis, e Limites de taxa e tentativas (em inglês) para as dimensões do limite de taxa.

Próximos passos

• Construir um painel de monitoramento de dispositivos
• REST API ou WebSocket
• Scopes de autorização (em inglês)
• Limites de taxa e tentativas (em inglês)