Skip to content

Documentación de la API REST

Las funcionalidades de visualización de datos de Scout son accesibles desde la web mediante la autenticación estándar con usuario y contraseña. Si quieres añadir datos a la plataforma, debes crear un app token.

Un app token es un método de autenticación alternativo al usuario / contraseña. Este sistema de autenticación está vinculado a una cuenta y permite realizar operaciones de lectura / escritura sobre las entidades que contiene esa cuenta, principalmente activos (assets), equipos, pasarelas y métricas.

Creación de un app token desde la web

Ve a la sección de proyectos y haz clic en el proyecto en el que quieres crear una app app_token_1_projects.png

En el menú superior, haz clic en Apps app_token_2_apps.png

Haz clic en el botón "Add app" app_token_3_add_app.png

Asigna un nombre a tu app app_token_4_name.png

Haz clic en copiar y cerrar app_token_5_copy.png

Con esto, tu token de API se copiará al portapapeles. Te recomendamos guardarlo en un archivo, ya que lo necesitarás para autenticar tus peticiones a la API.

Creación de un app token desde la API

Si quieres crear un app token desde la API, debes hacer una petición POST al endpoint /api/v2/accounts/{accountId}/keys con los siguientes parámetros:

  • accountId: id de la cuenta en la que quieres crear la app
  • Cabecera de autenticación: Bearer JSON Web Token obtenido del endpoint de login
  • el siguiente body:
        {
            "app": {
                "name": "string"
            }
        }
    
  • la llamada devolverá el siguiente body:
    {
      "key": {
        "app": {
          "id": "<UUID>",
          "name": "string"
        },
        "id": "<UUID>",
        "secret": "string"
      }
    }
    
    Aquí nos interesa el campo "secret", que contiene el app token necesario para realizar las peticiones a la API.

Descripción general de Swagger

Nuestra documentación incluye una página Swagger que permite a los usuarios realizar peticiones y ver el resultado obtenido. Para acceder a la documentación, ve a la siguiente URL: https://scout.circutor.com/api/v2/docs/index.html

Lo primero que verás es una lista de endpoints swagger_1_overview.png

Al hacer clic en un endpoint, verás la lista de campos que requiere swagger_2_endpoints.png

Para ejecutar la petición, haz clic en Try it out, rellena los campos obligatorios y haz clic en Execute. Si la petición se realiza correctamente, verás el body de la respuesta con el resultado swagger_3_results.png

Ejemplo de uso con Swagger

Con nuestro app token podemos usar los endpoints que aparecen en la documentación de Swagger y empezar a hacer peticiones a la API.

En este ejemplo te mostramos cómo añadir métricas a un activo y recuperarlas.

Obtener la información del activo

Ve al endpoint GET /api/v2/assets, añade tu token en el campo X-API-KEY, establece recursive a true y ejecuta la petición. Obtendrás todos los activos de la cuenta. Copia el id del activo al que quieres añadir métricas.

Insertar métricas

Ve al endpoint POST /api/v2/assets/{assetId}/metricsv3/raw/batch

Añade tu X-API-KEY y el assetID del paso anterior y, a continuación, añade las métricas en la sección body, por ejemplo:

{
  "metrics": [
    {
      "data": {
        "P_CON_TOT_ENERGY": 113.5,
        "V_AN": 22
      },
      "ts": "2024-10-23T15:00:00+00:00"
    }
  ]
}

Haz clic en Execute y comprueba que el body de la respuesta tiene el estado "OK" example_2_post.png

Obtener métricas

Ve al endpoint GET /api/v2/assets/{assetId}/metricsv3/raw y añade tu X-API-KEY, assetID, from, to y vars, por ejemplo: example_2_get.png

Haz clic en Execute y la respuesta debería contener las métricas que has añadido.