Introducción

Esta página establece el modelo básico antes de que integres. No enumera todos los parámetros de cada endpoint; explica los objetos principales, los patrones de petición, el modelo de estado de dispositivo y el ciclo de vida de los comandos que usa WLTE OpenAPI.

Si solo quieres lanzar la primera petición ya mismo, ve a Inicio rápido.

¿Qué es WLTE OpenAPI?

WLTE OpenAPI está pensado para sistemas de servidor. Permite que tu plataforma consulte, controle y monitorice dispositivos WLTE.

Capacidades habituales:

• Listar los dispositivos accesibles para una cuenta
• Consultar el estado y los datos de periféricos de un dispositivo
• Cargar las definiciones de tipo de dispositivo y las operaciones admitidas
• Enviar comandos de relé, RS485 y configuración
• Consultar el resultado de un comando
• Recibir eventos de dispositivo en tiempo real por WebSocket

Conceptos clave

Concepto	Descripción
API Client	La identidad que llama, creada en el Developer Console para una aplicación
clientId / clientSecret	Credenciales de servidor usadas para obtener un access token
Access token	Token de vida corta para llamar a los endpoints protegidos
Dispositivo	Un dispositivo WLTE accesible para la cuenta
Tipo de dispositivo	Definición que describe los periféricos y operaciones admitidos
Estado de periféricos	Estado de relés, entradas digitales, sensores, entradas analógicas y otros periféricos
Comando	Una petición de operación sobre el dispositivo: control de relé, transmisión RS485 o cambio de configuración
Evento WebSocket	Notificación en tiempo real de cambios de estado, de conexión, eventos de alimentación y similares

Modelo de integración

Tu servidor debe guardar el clientSecret y obtener los access token. Los navegadores, las aplicaciones móviles y otros clientes no deben guardar el clientSecret directamente.

REST API y WebSocket

REST API y WebSocket no se sustituyen entre sí. Cubren responsabilidades distintas.

Escenario	Método recomendado
Obtener un access token	REST API
Listar dispositivos	REST API
Cargar definiciones de tipo de dispositivo	REST API
Enviar comandos a un dispositivo	REST API o WebSocket, según tu modelo de conexión
Consultar el resultado de un comando	REST API
Actualizar explícitamente un dispositivo	REST API GET /devices/{deviceId} o WebSocket device.state.get
Vigilar conexión, desconexión, alimentación o cambios de estado	WebSocket

Para una primera integración, usa REST API para verificar la autenticación, el listado de dispositivos y una consulta de estado. Añade WebSocket cuando tu producto necesite eventos en tiempo real.

Consulta REST API o WebSocket para una comparación más detallada.

Modelo de estado del dispositivo

El estado del dispositivo debe interpretarse según el caso de uso.

Dato	Caso de uso	Descripción
Estado de la lista de dispositivos	Vistas de lista, paneles, sincronización en segundo plano	Datos ya sincronizados por la plataforma, adecuados para mostrar en bloque
Estado en tiempo real de un dispositivo	Actualizar una página de detalle, comprobar antes y después de una operación	El servidor intenta actualizar activamente ese dispositivo
Eventos WebSocket	Monitorización continua	Notificaciones en tiempo real de cambios de conexión, eventos de alimentación, cambios en periféricos y similares

No uses sondeo HTTP de alta frecuencia sobre todos los dispositivos para vigilar periféricos, desconexiones o cortes de corriente. La monitorización continua debe usar eventos WebSocket. Tras reconectar, usa la lista de dispositivos o el endpoint de estado individual para restablecer el estado crítico.

Modelo de comandos

Los comandos de dispositivo suelen tener dos fases:

1. La plataforma acepta la petición.
2. El dispositivo confirma el resultado final, o vence la ventana de espera.

Estados habituales:

Estado	Significado
SUCCESS	El dispositivo confirmó el resultado
TIMEOUT	No llegó ninguna confirmación final dentro de la ventana de espera
FAILED	El comando falló o fue rechazado explícitamente
SENT	El comando se envió pero aún no tiene estado final; se ve sobre todo al consultar un comando ya existente

TIMEOUT no demuestra que el dispositivo no ejecutara el comando. Puede haberlo ejecutado mientras la confirmación se retrasaba o se perdía. En comandos con efectos secundarios, no repitas la petición a ciegas tras un timeout: consulta primero el estado actual del dispositivo y decide después.

Modelo de permisos y seguridad

Los API Client controlan el acceso mediante scopes. Reglas habituales:

• Las consultas de solo lectura suelen requerir device:read
• El control del dispositivo suele requerir device:control
• La configuración del dispositivo suele requerir device:config
• La gestión del dispositivo suele requerir device:manage

Si una petición devuelve AUTH_SCOPE_DENIED, la respuesta indica qué permiso falta. Actualiza los permisos del API Client en el Developer Console y obtén un access token nuevo.

Límites de seguridad:

• Guarda el clientSecret solo en tu servidor
• No escribas el clientSecret, los access token ni los ticket de WebSocket en código de frontend, repositorios públicos o registros
• Cuando un API Client se desactiva o se elimina, los tokens existentes se rechazan
• Tras rotar un secreto, actualiza la configuración de tu servidor y obtén un token nuevo

Ruta de integración recomendada

1. Crea un API Client en el Developer Console.
2. Usa Bruno para verificar la autenticación, el listado de dispositivos y una consulta de estado.
3. Carga las definiciones de tipo de dispositivo para confirmar los periféricos y operaciones admitidos.
4. Elige REST API, WebSocket o ambos según el flujo de trabajo de tu producto.
5. Integra desde tu servidor con un SDK o con llamadas HTTP/WebSocket directas.
6. Antes de producción, revisa permisos, límites de tasa, reintentos, idempotencia y depuración de registros.

Siguiente paso: ve a Inicio rápido.