Llevar datos de dispositivo a tu SaaS

Caso de uso

Usa este patrón cuando la capacidad de los dispositivos WLTE sea una parte de tu propio producto (un SaaS multiinquilino, un sistema de operaciones interno o similar). Tus usuarios finales interactúan con tu producto y con tu propio sistema de cuentas: nunca tocan directamente las credenciales de WLTE.

• Una sola cuenta WLTE y un único API Client respaldan todo tu despliegue, no una credencial por cliente final.
• Los dispositivos de una cuenta WLTE son planos; no existe el concepto de inquilino. Qué dispositivos pertenecen a qué cliente es un mapeo que tú mismo defines y mantienes.
• Los eventos en vivo deben fluir de forma continua hacia tu propio pipeline de datos (base de datos, cola de mensajes, tu propio WebSocket o webhook), en lugar de que cada página de cada cliente final mantenga su propia conexión a WLTE.

No entregues nunca el clientId, el clientSecret ni un access token a un cliente final. No des por hecho que los dispositivos de una cuenta están aislados por inquilino: no lo están.

Arquitectura recomendada

Solo tu backend guarda las credenciales de WLTE. Mantén un mapeo deviceId → tenantId, sirve a todos los inquilinos desde una sola conexión WebSocket, y reparte los datos hacia el resto de tu sistema.

Implementación paso a paso

1. Diseña y mantén un mapeo deviceId → tenantId (o el identificador de cliente/sede que uses). Las cuentas WLTE no distinguen inquilinos: esta tabla es la estructura de datos central de toda la integración.
2. Obtén un access token desde tu único API Client, guardado en el servidor: device:read para uso de solo lectura, más device:control o device:config si envías comandos.
3. Llama a Listar dispositivos (en inglés) y Listar definiciones de tipo de dispositivo (en inglés) para construir la base de estado inicial, y después divídela en vistas por inquilino usando tu tabla de mapeo.
4. Crea un ticket de WebSocket (en inglés) de un solo uso y establece una única conexión —no una por inquilino— para recibir eventos de conexión, eventos de cambio de estado y eventos de alimentación (en inglés).
5. En cada evento, busca primero el inquilino a partir del deviceId, y después escribe en tu propio almacén o cola para que tu API/WebSocket/webhook pueda llevarlo a los clientes de ese inquilino.
6. Cuando un cliente final envíe una petición de control, autorízala primero contra tu propio sistema de permisos (los permisos por inquilino de tu producto, no un scope de WLTE), y haz que tu backend haga de proxy de la petición a WLTE con una clave de idempotencia.
7. Persiste tú mismo los resultados de comandos y los eventos allí donde necesites retención a largo plazo o un registro para facturación: WLTE no reproduce el historial de eventos, y los registros de comandos se conservan solo brevemente.

Interfaces y eventos clave

Para qué	Referencia
Construir la base de estado	Listar dispositivos (en inglés)
Vistas multiinquilino dirigidas por capacidades	Listar definiciones de tipo de dispositivo (en inglés)
Añadir un dispositivo a la cuenta	Añadir dispositivo a la cuenta (en inglés)
Autenticación WebSocket	Crear WebSocket Ticket (en inglés)
Cambios de conectividad	Eventos de conexión de dispositivo (en inglés)
Cambios de estado de periféricos	Evento de cambio de estado del dispositivo (en inglés)
Notificaciones de corte y restauración de alimentación	Eventos de alimentación de dispositivo (en inglés)
Hacer de proxy de un comando de control	Crear comando de relé (en inglés)
Consultar el resultado de un comando	Consultar resultado de comando (en inglés)

Fallos y recuperación

• Los límites de tasa se cuentan por API Client. Varios inquilinos que comparten una cuenta comparten un mismo presupuesto de límite de tasa: la tasa alta de un solo inquilino puede agotar la cuota de toda la cuenta, así que limita y encola en tu propia capa en lugar de pasar directamente a WLTE la tasa de peticiones de tus clientes finales.
• Si se pierde la conexión WebSocket ascendente, reconecta esa única conexión de servidor en lugar de reconectar por inquilino; marca los datos posteriores como potencialmente desactualizados mientras reconectas.
• Los eventos perdidos mientras estabas desconectado no se reproducen. Reconstruye la base de estado por REST tras reconectar, y después retoma las actualizaciones dirigidas por eventos.
• Los registros de comandos y las claves de idempotencia se conservan en WLTE solo unas 48 horas. Persiste tú mismo los resultados de comandos y el estado final si necesitas una ventana de auditoría o facturación más larga.
• Ante un 429 RATE_LIMITED, espera lo que indique Retry-After. No implementes un bucle de reintentos independiente por cada inquilino en tu propio servicio.

Consideraciones para producción

• Los clientes finales no deben ver ni obtener nunca, bajo ninguna circunstancia, el clientId, el clientSecret ni un access token de WLTE: toda llamada a WLTE debe pasar por tu backend.
• Los cuatro scopes de WLTE (device:read/device:control/device:config/device:manage) son permisos gruesos, a nivel de cuenta. No sustituyen a tu propio modelo de permisos fino por cliente: son dos capas de autorización distintas.
• Trata el mapeo deviceId → tenantId como la tabla más importante de tu sistema; mantenlo sincronizado cada vez que se añadan o quiten dispositivos de la cuenta, o que los clientes añadan o quiten sedes, para evitar que los datos crucen hacia el inquilino equivocado.
• Planifica tu presupuesto de límite de tasa con antelación: el número de inquilinos hace crecer tu volumen de peticiones de forma lineal, pero el límite de tasa de la cuenta no crece con él.
• Consulta Scopes de autorización (en inglés) para las combinaciones de scopes disponibles, y Límites de tasa y reintentos (en inglés) para las dimensiones del límite de tasa.

Siguientes pasos

• Construir un panel de monitorización de dispositivos
• REST API o WebSocket
• Scopes de autorización (en inglés)
• Límites de tasa y reintentos (en inglés)