Integraciones y API
La API de datos de Nescloud permite obtener por programación la información de tus redes, dispositivos y sensores, para integrarla en tus propios sistemas.
Ten en cuenta
Antes de empezar — necesitas una API Key, que se solicita a Nespra. Confirma con soporte que dispones de acceso vigente a la API de datos antes de empezar a integrar.
Referencia interactiva
La descripción completa de cada llamada —parámetros, formatos de respuesta y ejemplos— está en el portal de documentación, donde además puedes probar las llamadas desde el navegador:
Este artículo cubre lo que conviene saber antes de entrar ahí: cómo autenticarse y las tres particularidades de esta API que no se deducen de la referencia.
Qué puedes consultar
•Redes — tus Nesgates y Nesmotes agrupados por red, con su estado de conexión, modelo, coordenadas y la lista de sensores de cada uno.
•Datos de sensores — el histórico de mediciones de un dispositivo, en crudo o agregado por horas.
•Avisos — las alertas y alarmas que se han disparado.
•Interpretación de valores — el color y el texto del conocimiento experto que corresponde a una medición.
Cómo autenticarse
Son dos credenciales distintas y las dos hacen falta:
1
La API Key, siempre, en la cabecera
x-api-key. Identifica a tu integración y es la que Nespra te asigna.
2
El token de usuario, en la cabecera
Authorization. Lo obtienes con la primera llamada y lo reutilizas en todas las demás.Para conseguir el token, envía las credenciales de un usuario de Nescloud a
POST /auth/validate sobre https://data.nescloud.net:{ "username": "usuario@ejemplo.com", "password": "..." }La respuesta trae el token, su caducidad y las organizaciones a las que ese usuario tiene acceso:
[{ "login_status": true, "user_id": 65,
"organizations": [{ "id": 2, "name": "Nespra Demo" }],
"api_token": "L5S6FzpgslWuBhRsKQfRx4rTXKXwQst-XV6oOKvTVGs",
"expiration_time": 1596105471 }]El
id de organización que necesitan las demás llamadas es uno de los que aparecen en organizations: el token solo da acceso a los datos de las organizaciones de su usuario.Consejo
Guarda el token y reutilízalo hasta que se acerque su
expiration_time, en lugar de pedir uno nuevo en cada llamada. Cada petición a /auth/validate consume cuota igual que las demás.Tres particularidades que conviene saber
Los errores llegan con código 200
Esta API responde siempre con código HTTP 200, también cuando algo falla. El error viaja en el cuerpo:
[{ "error": "The given API token has expired." }]Si tu integración decide si algo ha ido bien mirando el código de estado, dará por buenas las respuestas fallidas. Comprueba la clave
error antes de tratar el resultado.El intervalo de datos no puede superar 180 días
Las consultas de histórico están limitadas a 180 días entre el instante inicial y el final. Para series más largas, trocea la consulta en varias peticiones.
Hay un límite de llamadas diarias
Tu API Key tiene una cuota diaria asociada. Al agotarla, las peticiones se rechazan hasta el día siguiente, así que conviene espaciar los sondeos y no reintentar en bucle: un reintento agresivo consume la cuota del día siguiente antes de empezar. Si tu integración necesita más volumen, habla con soporte en lugar de subir la frecuencia.
Consejo
Si lo que necesitas es reaccionar a datos nuevos en cuanto llegan, un webhook es mejor que consultar la API en bucle: Nescloud te avisa cuando hay novedad y no consumes cuota preguntando. Consulta «Pasos para crear un webhook».
Atención
La API Key es privada: identifica a tu organización y su cuota. No la publiques en código cliente, repositorios ni aplicaciones móviles, donde cualquiera podría extraerla.
Ten en cuenta
Consulta también: «Pasos para crear un webhook» y «Cómo crear e integrar dispositivos sensores externos en Nescloud».
Manual de usuario de Nescloud · Integraciones y API. Si necesitas ayuda con un caso concreto, contacta con el soporte de tu organización.