Preguntas frecuentes
Esta página agrupa los problemas más habituales durante la integración. Empieza por el síntoma que más se parezca a lo que ves; los esquemas de endpoint, los parámetros y las listas completas de errores están en la documentación de referencia.
Buscar por síntoma
| Lo que ves | Empieza aquí |
|---|---|
| No tienes una API key y no sabes dónde crearla | La llamada a la API todavía no funciona |
| Falla la emisión del token, o las peticiones devuelven 401 / 403 | La llamada a la API todavía no funciona |
| Falta un dispositivo, o su estado no parece actual | Los datos del dispositivo no cuadran |
| Quieres vigilar de forma continua periféricos, desconexiones o cortes de corriente | Los datos del dispositivo no cuadran |
| Un comando se aceptó, pero el dispositivo no respondió o dio timeout | Una operación no terminó como esperabas |
| WebSocket no conecta, se desconecta a menudo o pierde eventos | La conexión en tiempo real es inestable |
| No sabes si usar REST API o WebSocket | REST API o WebSocket |
| Las peticiones devuelven 429, 503 o gateway no disponible | Las peticiones están limitadas o el servicio no está disponible |
| El problema sigue después de seguir la documentación | Prepara los datos para soporte |
La llamada a la API todavía no funciona
¿Cómo creo un API Client y obtengo credenciales?
Crea un API Client en el Developer Console de WLTE.
- Entra en el Developer Console: https://developer.svnwi.com/wlte
- Abre una aplicación y ve a la gestión de API Client.
- Crea un API Client y selecciona los permisos mínimos que necesite la integración.
- Guarda el
clientIdy elclientSecretgenerados.
Al crear un API Client obtienes un clientId y un clientSecret, que se usan juntos para conseguir un access token.
El clientSecret solo se muestra al crearlo o al rotarlo. Guárdalo de inmediato en el almacén de secretos de tu servidor. Si lo pierdes, rota el secreto, porque el valor original no se puede volver a ver. Consulta Obtener API Keys.
Falla la emisión del access token
Comprueba estos puntos en orden:
- El API Client existe y está activo.
- El
clientIdy elclientSecretpertenecen al mismo cliente. - La aplicación y la cuenta están activas.
- La URL, el método y el cuerpo de la petición coinciden con Crear access token (en inglés).
No reintentes credenciales inválidas de forma indefinida: la autenticación también tiene límites de tasa.
El code de la respuesta es AUTH_INVALID
Las credenciales, o el estado actual de su propietario, no son válidos. Las causas habituales son credenciales incorrectas, un API Client desactivado o eliminado, una aplicación desactivada o una cuenta en un estado no válido.
Si acabas de rotar el secreto, comprueba que estás usando el nuevo. Ramifica según el code, no según el message.
El code de la respuesta es AUTH_SCOPE_DENIED
El API Client no tiene el permiso que exige el endpoint. data.requiredScope indica cuál falta.
Añade ese permiso en el Developer Console, guarda el cambio, obtén un token nuevo y reintenta. Consulta Permisos (en inglés).
¿Se puede seguir usando un token antiguo después de desactivar o eliminar un API Client?
No. Los endpoints protegidos validan el estado actual del API Client, de la aplicación y de la cuenta, no solo la caducidad del JWT.
Después de desactivar o eliminar el cliente, no se pueden emitir tokens nuevos y los existentes se rechazan.
¿Se puede guardar el clientSecret en una web o en una app móvil?
No. El clientSecret es una credencial de servidor. Ni los recursos del navegador, ni los paquetes de aplicación, ni los registros del cliente pueden protegerlo de forma fiable.
Mantén las credenciales en un servidor bajo tu control. No escribas el clientSecret, los access token ni los ticket de WebSocket en código de frontend, repositorios públicos o registros.
Los datos del dispositivo no cuadran
Falta un dispositivo en la lista
Confirma primero que el dispositivo pertenece a la cuenta actual y que el API Client tiene permiso para acceder a él.
Si el dispositivo aparece en el Developer Console pero no en la API, revisa los permisos concedidos sobre ese dispositivo y el scope device:read. Si la causa sigue sin estar clara, anota el requestId antes de contactar con soporte.
El estado de la lista no coincide con el dispositivo físico ahora mismo
La lista de dispositivos devuelve el estado que la plataforma ya tiene sincronizado. No actualiza activamente cada dispositivo físico en cada petición, y está pensada para vistas de lista, paneles y lecturas masivas.
Para una actualización explícita del usuario, o antes y después de una operación, usa Consultar dispositivo (en inglés) o una petición de estado por WebSocket.
¿Puedo sondear HTTP con frecuencia para ver periféricos, desconexiones o alimentación?
No es recomendable. El estado de periféricos, las desconexiones y los eventos de alimentación son datos orientados al tiempo real. Un sondeo HTTP agresivo aumenta la presión de actualización sobre los dispositivos y hace más probable que llegues a los límites de tasa.
Enfoque recomendado:
- Usa Listar dispositivos (en inglés) para listas, paneles y sincronización en segundo plano.
- Usa Consultar dispositivo (en inglés) o
device.state.getpor WebSocket cuando el usuario actualice explícitamente la página de detalle de un dispositivo. - Usa eventos WebSocket para vigilar de forma continua las desconexiones, la alimentación y los cambios de periféricos; tras reconectar, vuelve a confirmar el estado crítico con HTTP o con
device.state.get.
No llames al endpoint de actualización en tiempo real cada pocos segundos para cada dispositivo. No garantiza una entrega de eventos sin pérdidas y puede afectar a otras peticiones normales de la misma cuenta.
deviceType es UNSUPPORTED
La plataforma todavía no ofrece una definición de tipo utilizable para ese dispositivo. El dispositivo puede seguir perteneciendo a la cuenta, pero el cliente no debe dar por hecho que su esquema de estado o sus capacidades de control estén disponibles.
No deduzcas las capacidades a partir del prefijo del ID de dispositivo.
¿Cómo sé si un dispositivo admite una operación?
Consulta Listar definiciones de tipo de dispositivo (en inglés) y revisa capabilities.supportedOperations.
Solo deberías mostrar o invocar las operaciones que aparezcan ahí. Por ejemplo, no muestres la transmisión RS485 salvo que exista device.rs485.transceive.
Una operación no terminó como esperabas
La respuesta es COMMAND_ACCEPTED, pero el dispositivo no se ha movido
COMMAND_ACCEPTED significa que la plataforma aceptó la petición. No significa que el dispositivo haya completado la operación.
Guíate por el estado del comando: SUCCESS significa que el dispositivo confirmó la operación; TIMEOUT significa que no llegó ninguna confirmación final a tiempo. Usa Consultar resultado de comando (en inglés) para recuperar el estado de un comando anterior.
El comando está en TIMEOUT. ¿Seguro que el dispositivo no lo ejecutó?
No necesariamente. Puede que el dispositivo no recibiera el comando, o que lo ejecutara mientras la confirmación se retrasaba o se perdía.
No repitas el comando a ciegas. Consulta primero el estado actual del dispositivo, sobre todo en operaciones que no sea seguro duplicar.
El code de la respuesta es COMMAND_REJECTED
Comprueba primero dos cosas:
- La definición de tipo de dispositivo incluye la operación solicitada.
- Los parámetros encajan con la capacidad del dispositivo, por ejemplo un índice de relé válido.
Si ambas son correctas, revisa la conectividad del dispositivo y la ruta subyacente hasta él.
¿Un reintento debe usar un Idempotency-Key nuevo?
Reutiliza la clave original al reintentar la misma operación de negocio tras un fallo de red. Dispositivos distintos, estados de destino distintos u operaciones de negocio distintas necesitan claves distintas.
No uses una clave fija para todas las peticiones. Consulta Comportamiento HTTP (en inglés).
La conexión en tiempo real es inestable
WebSocket no consigue conectar
Confirma que el access token es válido y crea después un wsTicket nuevo. El ticket es de vida corta y de un solo uso: no debe cachearse ni reutilizarse.
Revisa Crear WebSocket Ticket y después Establecer conexión (ambos en inglés).
¿Cómo debe recuperarse el cliente tras una desconexión?
Reconecta con backoff y crea un ticket nuevo para cada conexión. Tras reconectar, recarga el estado que necesites en lugar de asumir que se reproducirán íntegramente los eventos del periodo desconectado.
Consulta Heartbeat y reconexión (en inglés).
Llegan eventos duplicados, o parece que faltan algunos
El tratamiento de eventos debe ser idempotente. WebSocket notifica cambios al cliente y no debe ser la única fuente permanente de estado.
Tras recargar la página, reconectar o detectar un hueco de estado, consulta el estado por REST API o con una petición de estado por WebSocket para establecer una base nueva.
Las peticiones están limitadas o el servicio no está disponible
La respuesta es HTTP 429
Deja de reintentar de inmediato. Lee Retry-After y reintenta pasado ese tiempo. Coordina el backoff entre las instancias de tu servicio para no provocar otra ráfaga sincronizada.
La actualización en tiempo real y el control de dispositivos están limitados más estrictamente que las consultas de estado sincronizado. Consulta Límites de tasa y reintentos (en inglés).
La respuesta es 503 o GATEWAY_UNAVAILABLE
La ruta en tiempo real hacia el dispositivo no está disponible temporalmente. Anota el requestId y reintenta un número limitado de veces con backoff.
Si la situación persiste, deja de reintentar y prepara los datos para soporte.
Prepara los datos para soporte
Si el problema sigue, reúne:
| Información | Ejemplo o indicación |
|---|---|
requestId | ID de traza que devuelve la respuesta de la API |
| ID del API Client | No incluyas nunca el clientSecret |
| Método y ruta de la petición | GET /wlte/v1/devices |
| Marca de tiempo UTC | Momento exacto del problema |
Estado HTTP y code de negocio | Por ejemplo, 403 / AUTH_SCOPE_DENIED |
| Parámetros depurados | Quita contraseñas, tokens e información personal |
Después envía el caso desde Contactar con soporte.