Introdução

Esta página estabelece o modelo básico antes de você integrar. Não lista todos os parâmetros de cada endpoint; explica os objetos principais, os padrões de requisição, o modelo de estado de dispositivo e o ciclo de vida dos comandos usados pelo WLTE OpenAPI.

Se você só quer executar a primeira requisição agora mesmo, vá para Início rápido.

O que é o WLTE OpenAPI?

O WLTE OpenAPI foi criado para sistemas do lado do servidor. Ele permite que sua plataforma leia, controle e monitore dispositivos WLTE.

Capacidades típicas:

• Listar os dispositivos acessíveis a uma conta
• Consultar o estado e os dados de periféricos de um dispositivo
• Carregar as definições de tipo de dispositivo e as operações suportadas
• Enviar comandos de relé, RS485 e configuração
• Consultar o resultado de um comando
• Receber eventos de dispositivo em tempo real via WebSocket

Conceitos principais

Conceito	Descrição
API Client	A identidade que chama, criada no Developer Console para uma aplicação
clientId / clientSecret	Credenciais do servidor usadas para obter um access token
Access token	Token de curta duração usado para chamar endpoints protegidos
Dispositivo	Um dispositivo WLTE acessível para a conta
Tipo de dispositivo	Definição que descreve os periféricos e operações suportados
Estado de periféricos	Estado de relés, entradas digitais, sensores, entradas analógicas e outros periféricos
Comando	Uma requisição de operação no dispositivo, como controle de relé, transceptor RS485 ou atualização de configuração
Evento WebSocket	Notificação em tempo real de mudanças de estado, conexão, eventos de energia e similares

Modelo de integração

Seu servidor deve armazenar o clientSecret e obter os access token. Navegadores, aplicativos móveis e outros clientes não devem armazenar o clientSecret diretamente.

REST API e WebSocket

REST API e WebSocket não se substituem. Eles atendem responsabilidades diferentes.

Cenário	Método recomendado
Obter um access token	REST API
Listar dispositivos	REST API
Carregar definições de tipo de dispositivo	REST API
Enviar comandos a um dispositivo	REST API ou WebSocket, dependendo do seu modelo de conexão
Consultar o resultado de um comando	REST API
Atualizar explicitamente um dispositivo	REST API GET /devices/{deviceId} ou WebSocket device.state.get
Monitorar conexão, desconexão, energia ou eventos de mudança de estado	WebSocket

Para uma primeira integração, use REST API para verificar autenticação, listagem de dispositivos e uma consulta de estado. Adicione WebSocket quando seu produto precisar de eventos em tempo real.

Veja REST API vs WebSocket para uma comparação mais detalhada.

Modelo de estado do dispositivo

O estado do dispositivo deve ser interpretado conforme o caso de uso.

Dado	Caso de uso	Descrição
Estado da lista de dispositivos	Visualizações de lista, painéis, sincronização em segundo plano	Dados já sincronizados pela plataforma, adequados para exibição em massa
Estado em tempo real de um dispositivo	Atualizações de página de detalhe e verificações antes/depois de uma operação	O servidor tenta atualizar ativamente esse dispositivo
Eventos WebSocket	Monitoramento contínuo de estado	Notificações em tempo real de mudanças de conexão, eventos de energia, mudanças em periféricos e similares

Não use sondagem HTTP de alta frequência em todos os dispositivos para monitorar periféricos, estado offline ou mudanças de energia. O monitoramento contínuo deve usar eventos WebSocket. Após reconectar, use a lista de dispositivos ou o endpoint de status individual para restabelecer o estado crítico.

Modelo de comandos

Os comandos de dispositivo geralmente têm duas fases:

1. A plataforma aceita a requisição.
2. O dispositivo confirma o resultado final, ou a janela de espera expira.

Estados comuns:

Estado	Significado
SUCCESS	O dispositivo confirmou o resultado
TIMEOUT	Nenhuma confirmação final chegou dentro da janela de espera
FAILED	O comando falhou ou foi explicitamente rejeitado
SENT	O comando foi enviado mas ainda não tem status terminal; isso geralmente ocorre ao consultar um comando já existente

TIMEOUT não prova que o dispositivo não executou o comando. Ele pode ter executado enquanto a confirmação foi atrasada ou perdida. Para comandos com efeitos colaterais, não repita a requisição cegamente após um timeout. Leia primeiro o estado atual do dispositivo e decida depois.

Modelo de permissões e segurança

Os API Client usam scopes para controlar o acesso. Regras comuns:

• Consultas somente leitura geralmente exigem device:read
• O controle do dispositivo geralmente exige device:control
• A configuração do dispositivo geralmente exige device:config
• O gerenciamento do dispositivo geralmente exige device:manage

Se uma requisição retornar AUTH_SCOPE_DENIED, a resposta identifica a permissão que falta. Atualize as permissões do API Client no Developer Console e obtenha um access token novo.

Limites de segurança:

• Armazene o clientSecret apenas no seu servidor
• Não escreva o clientSecret, access tokens ou tickets de WebSocket em código de frontend, repositórios públicos ou registros
• Depois que um API Client é desativado ou excluído, os tokens existentes são rejeitados
• Após rotacionar um segredo, atualize a configuração do servidor e obtenha um token novo

Caminho de integração recomendado

1. Crie um API Client no Developer Console.
2. Use o Bruno para verificar autenticação, listagem de dispositivos e uma consulta de estado.
3. Carregue as definições de tipo de dispositivo para confirmar os periféricos e operações suportados.
4. Escolha REST API, WebSocket ou ambos com base no fluxo de trabalho do seu produto.
5. Integre a partir do seu servidor usando um SDK ou chamadas diretas de HTTP/WebSocket.
6. Antes de produção, revise permissões, limites de taxa, tentativas, idempotência e redação de logs.

Próximo passo: vá para Início rápido.