API REST

Las API REST ( pAPIs ) permiten acceder a los datos de los activos de las plantas solares, eólicas y de almacenamiento de energía.

Obtener una clave API

Una vez que hayas iniciado sesión correctamente en Maximo® Renewables, haz clic en el icono de usuario del menú y, a continuación, haz clic en el icono de la llave para obtener la clave API. La validez de la clave API se muestra y se configura a nivel de cuenta.

Formato de solicitud y respuesta

URL base

Todos los puntos de conexión de la API utilizan el siguiente formato basado en la región: URL :

El sitio web URL para la región de Asia-Pacífico:

https://in-papi.prescinto.ai/

La página de inicio URL para otras regiones:

https://us-papi.prescinto.ai/
Formato de solicitud

Todas las solicitudes a la API deben incluir los siguientes encabezados:

  • Content-Type: application/json
  • x-api-key: your-api-key

Los parámetros de la solicitud se transmiten como objetos JSON en el cuerpo de la solicitud para las solicitudes POST.

El siguiente ejemplo muestra una solicitud de datos de activos solares:

{
  "pName": "IN.DEMO.AQUI",
  "categoryList": ["Inverter"],
  "parameterList": ["Active Power", "Total Energy"],
  "sDate": "2022-10-15",
  "eDate": "2022-10-16",
  "granularity": "5m",
  "condition": {
    "Active Power": "mean",
    "Total Energy": "sum"
  }
}
Formato de la respuesta

Todas las respuestas de la API se devuelven en formato JSON. Las respuestas correctas incluyen los datos solicitados junto con los metadatos. Las respuestas de error incluyen un código de error y un mensaje descriptivo.

El siguiente ejemplo muestra una respuesta correcta:

{
  "status": "success",
  "data": {
    // Response data
  },
  "metadata": {
    "timestamp": "2024-04-03T06:36:41Z",
    "version": "1.0"
  }
}

Datos de la cuenta

Recupera la lista de proyectos de la cartera.

Ver lista de proyectos
Método
POST
Punto final
/api/v1/get/projectList
Descripción
Recupera la información del proyecto correspondiente a la cuenta, incluidos los datos de latitud, longitud y nivel de detalle.
Parámetros
No se requiere (utiliza una clave API para identificar la cuenta)

Datos de la planta

Recuperar la plantilla de la planta, la estructura, el proyecto, la lista de proyectos, la capacidad y la información sobre los activos.

Descargar plantilla de planta
Método
POST
Punto final
/api/v1/get/template
Descripción
Recupera la información de la plantilla de la planta en función del nombre de la planta facilitado. Devuelve los datos de la plantilla de la planta correspondientes a las categorías de dispositivos, los dispositivos y las etiquetas.
Parámetros
Parámetro Tipo Descripción
pName serie Nombre abreviado de la planta (por ejemplo, IN.DEMO.AQUI )
isNodeId[opcional] booleano Si se establece en «true», recupera los ID de los nodos en lugar de los nombres de los parámetros (valor predeterminado: «false»)
Consigue una plantilla personalizada para plantas
Método
POST
Punto final
/api/v1/get/custom/template
Descripción
Recupera información personalizada de plantillas de centrales eólicas. Devuelve una plantilla con datos sobre categorías de dispositivos, dispositivos, componentes y etiquetas.
Parámetros
Parámetro Tipo Descripción
pName serie Nombre abreviado de la planta
Ver detalles de la capacidad
Método
POST
Punto final
/api/v1/get/capacity
Descripción
Recupera la capacidad de corriente continua de los dispositivos de la planta.
Parámetros
Parámetro Tipo Descripción
pName serie Nombre abreviado de la planta
Obtén los datos maestros del activo.
Método
POST
Punto final
/api/v1/get/assetMaster
Descripción
Recupera los datos maestros de activos de una planta solar concreta.
Nota: Esta API solo es aplicable a activos solares.
Parámetros
Parámetro Tipo Descripción
pName serie Nombre abreviado de la planta
eventType[opcional] serie Tipo de nombre de subclasificación en activos (por defecto: «cadena»)
Consulta la previsión
Método
POST
Punto final
/api/v1/get/forecast
Descripción
Recupera los datos de previsión (PVSYST) de una planta concreta para un intervalo de fechas determinado.
Parámetros
Parámetro Tipo Descripción
pName serie Nombre abreviado de la planta
sDate serie Fecha de inicio en el formato «AAAA-MM-DD»
eDate serie Fecha de finalización en el formato «AAAA-MM-DD»
Limpieza del módulo
Método
POST
Punto final
/api/v1/get/moduleCleaning
Descripción
Recupera los datos de limpieza de módulos correspondientes a una planta concreta en el intervalo de fechas indicado.
Nota: Esta API solo es aplicable a activos solares.
Parámetros
Parámetro Tipo Descripción
pName serie Nombre abreviado de la planta
sDate serie Fecha de inicio en el formato «AAAA-MM-DD» (por ejemplo, 15-10-2022)
eDate serie Fecha de finalización en el formato «AAAA-MM-DD» (por ejemplo, 15-10-2022)
Recuperar la pérdida de limpieza
Método
POST
Punto final
/api/v1/get/cleaningLoss
Descripción
Recupera la información sobre pérdidas de limpieza de la planta dentro de un intervalo de fechas especificado.
Nota: Esta API solo es aplicable a activos solares.
Parámetros
Parámetro Tipo Descripción
pName serie Nombre abreviado de la planta
sDate serie Fecha de inicio en el formato «AAAA-MM-DD»
eDate serie Fecha de finalización en el formato «AAAA-MM-DD»

Datos de activos

Recuperar datos de series temporales de los parámetros de la planta y los dispositivos.

Obtener datos
Método
POST
Punto final
/api/v1/get/dataV2
Descripción
Recupera datos de una planta concreta con compatibilidad con zonas horarias. Devuelve datos con columnas como «Nombre del dispositivo». «Parámetro» y una columna de hora.
Parámetros
Parámetro Tipo Descripción
pName serie Nombre abreviado de la planta
categoryList matriz o cadena Lista de categorías de instalaciones (por ejemplo, «Inversor»)
parameterList matriz o cadena Lista de parámetros de la planta (por ejemplo, «Potencia activa», «Energía total», «Corriente alterna»)
deviceList[opcional] matriz o cadena Lista de dispositivos de la planta (por defecto: lista vacía o Ninguno)
sDate serie Fecha de inicio en el formato «AAAA-MM-DD», «AAAA-MM-DD HH:MM:SS» o «AAAA-MM-DD HH:MM:SS±HH:MM»
eDate serie Fecha de finalización en el mismo formato que la fecha de inicio
granularity[opcional] serie Granularidad de los datos (valor predeterminado: « 5m »). Formatos admitidos: segundos ( 1s, 2s ), minutos ( 5m, 10m ), horas ( 1h, 5h ), días ( 1d, 2d ), semanas ( 1w, 2w ), meses ( 30d, 31d )
condition[opcional] objeto Condición de agregación para cada parámetro (por defecto: «first»). Agregaciones admitidas: media, mediana, moda, suma, primer valor, último valor, máximo, mínimo, recuento. Formato: {"Parameter": "Aggregation"}
fetchInUserTimeZone[opcional] booleano Recuperar datos en la zona horaria del usuario (por defecto: false). Si se establece en «true», las fechas de inicio y fin deben incluir la diferencia horaria
Instrucciones para las alarmas
  • Para recuperar los datos de las alarmas de viento, utilice la categoría ["Alarma"] y el parámetro ["Alarma de turbina"]
  • Para recuperar los datos de alarmas solares, utiliza la categoría ["Alarma"] y el parámetro ["Alarma del inversor"]
Instrucciones especiales para parques eólicos
  • Para las etiquetas relacionadas con las plantas, utiliza «Planta eólica» como categoría del dispositivo
  • En el caso de los parámetros de la turbina, introduce el nombre abreviado del componente junto con el nombre del parámetro. Ejemplo: Para obtener la dirección del viento por hora desde la góndola, introduce « WNAC.Wind Direction» como parámetro y « {"Wind Direction": "mean"} » en la condición.
    Componente Nombre abreviado
    Convertidor WCONV
    Generador WGEN
    Cuadrícula WGRD
    Góndola WNAC
    Rotor WROT
    Torre WTOW
    Transmisión WTRM
    Tema general WTUR
    Bostezar WYAW
    Contenedor WCNT
    Caja de cambios WGBX
    Cubo de rejilla WGRC
    Transformador WTRF
    Contador WCTR
Obtener la última marca de tiempo
Método
POST
Punto final
/api/v1/get/LastTimeStamp
Descripción
Recupera la última marca de tiempo de los datos con el último valor para la planta, la categoría y los parámetros especificados.
Parámetros
Parámetro Tipo Descripción
pName serie Nombre abreviado de la planta
categoryList matriz o cadena Lista de categorías de plantas
parameterList matriz o cadena Lista de parámetros de la planta
deviceList[opcional] matriz o cadena Lista de dispositivos de la planta (por defecto: lista vacía)
Obtener las etiquetas modificadas recientemente
Método
POST
Punto final
/api/v1/get/LastModifiedTags
Descripción
Recupera los datos de las etiquetas según la hora de la última modificación, con el último valor para la planta, la categoría y los parámetros especificados.
Parámetros
Parámetro Tipo Descripción
pName serie Nombre abreviado de la planta
categoryList matriz o cadena Lista de categorías de plantas
parameterList matriz o cadena Lista de parámetros de la planta
granularity[opcional] serie Granularidad de los datos (valor predeterminado: « 5m »)
quality[opcional] serie Filtro de calidad de datos (por defecto: «G»). Opciones: Bueno, Malo, Regular
lastModifiedTime número Filtro de fecha y hora de última modificación en formato de marca de tiempo « Unix » (por ejemplo, 1698753148454.8281 )
Obtener datos del recorrido
Método
POST
Punto final
/api/v1/get/getCycleData
Descripción
Recupera los datos de ciclo de una planta, un subgrupo y un bloque concretos dentro de un intervalo de fechas determinado.
Nota: Esta API solo es aplicable a activos BESS.
Parámetros
Parámetro Tipo Descripción
pName serie Nombre abreviado de la planta
subGroupNames[opcional] matriz o cadena Lista de subgrupos o nombre del subgrupo (por ejemplo, [« subgroup-1 »])
blockNames[opcional] matriz o cadena Lista de bloqueados o nombre del bloqueado (por ejemplo, [" EB01 "])
sDate serie Fecha de inicio en el formato «AAAA-MM-DD»
eDate serie Fecha de finalización en el formato «AAAA-MM-DD»
Consulta las estadísticas diarias
Método
POST
Punto final
/api/v1/get/getDailyStats
Descripción
Recupera los datos del ciclo diario de una planta, un subgrupo y un bloque concretos dentro de un intervalo de fechas determinado.
Nota: Esta API solo es aplicable a activos BESS.
Parámetros
Parámetro Tipo Descripción
pName serie Nombre abreviado de la planta
subGroupNames[opcional] matriz o cadena Lista de subgrupos o nombre del subgrupo
blockNames[opcional] matriz o cadena Lista de bloqueados o nombre del bloqueado
sDate serie Fecha de inicio en el formato «AAAA-MM-DD»
eDate serie Fecha de finalización en el formato «AAAA-MM-DD»

Puntos finales del sistema

Los siguientes puntos finales proporcionan información sobre el estado y el funcionamiento del sistema:

Punto final Método Descripción
/health OBTENER Punto final de comprobación de estado para verificar la disponibilidad de la API
/ping OBTENER Realizar una prueba de ping al punto final para comprobar la conectividad de la API

Manejo de errores

La API devuelve códigos de estado estándar de HTTP :

Código de estado Descripción
200 Respuesta satisfactoria
422 Error de validación (parámetros de solicitud no válidos)
401 Error de autenticación (clave API no válida o faltante)
500 Error interno del servidor

Los errores de validación incluyen información detallada sobre los parámetros que no han superado la validación.

El siguiente ejemplo muestra una respuesta de error:

{
  "status": "error",
  "error": {
    "code": "ERROR_CODE",
    "message": "Descriptive error message"
  }
}

Aspectos a tener en cuenta

  • Guarda las claves de la API en un lugar seguro y no las compartas con nadie.
  • Implementa un sistema de gestión de errores para todas las llamadas a la API con el fin de gestionar adecuadamente los problemas de red y los errores de la API.
  • Utilice los ajustes de granularidad adecuados para equilibrar la resolución de los datos con el rendimiento.
  • Almacena las respuestas en caché cuando sea conveniente para reducir las llamadas a la API y mejorar el rendimiento de la aplicación.
  • Supervisa el uso de la API: las solicitudes están sujetas a límites de frecuencia para garantizar la estabilidad del sistema.
  • En las consultas que incluyan parámetros de zona horaria, los formatos de fecha deben incluir las diferencias horarias correspondientes.
  • Para obtener un rendimiento óptimo, agrupe las consultas en lotes de un máximo de 100 dispositivos en un intervalo de 10‑day, con una granularidad de 5‑minute.