SmartPVMS 25.2.0 Northbound API Reference
Change History
25.2.0 Northbound API Changes
01
Optimized the description of error code 25001 in Error Code List.
API Name |
API Method and Path |
Description |
Remarks |
|---|---|---|---|
https://Domain name of the management system/thirdData/getDevRealKpi |
Added support for querying the real-time data of the EMMA. |
The API is changed. |
|
https://Domain name of the management system/thirdData/getDevHistoryKpi |
Added support for querying the historical data of the EMMA. |
The API is changed. |
25.1.0 Northbound API Changes
01
API Name |
API Method and Path |
Description |
Remarks |
|---|---|---|---|
https://Domain name of the management system/thirdData/getDevRealKpi |
The number of PV strings supported by a string inverter is adjusted to 36. |
The API is changed. |
|
https://Domain name of the management system/thirdData/getDevHistoryKpi |
The number of PV strings supported by a string inverter is adjusted to 36. |
The API is changed. |
|
https://Domain name of the management system/rest/openapi/pvms/nbi/v2/control/active-power-control/async-task |
The notice added the following constraint: In networking scenarios (Smart Dongle, SmartLogger, and inverter direct connection), if Scheduled tasks is enabled, the active power setting task cannot be delivered to the plant. |
The API is changed. |
24.8.0 Northbound API Changes
01
Optimized Creating an OAuth 2.0 Client for a Third-Party App.
Optimized Initiating Authorization to a Third-Party App by an Owner.
Optimized Obtaining the Access Token of the Open API by a Third-Party App.
Optimized Calling Open APIs by Third-Party Apps.
Optimized Calling an API.
Optimized Error Code List.
Optimized Handling the Exception Returned by Calling the Authorization Request API.
Optimized Handling the Exception Returned by Calling the Token Obtaining API.
Added API for Real-time Plant Data.
API Name |
API Method and Path |
Description |
Remarks |
|---|---|---|---|
https://Domain name of the management system/thirdData/getAlarmList |
Added Romanian and Czech to the language parameter in the request. |
The API is changed. |
24.7.0 Northbound API Changes
05
Optimized the description of error code 30032 in Error Code List.
04
The real-time device data list in Real-Time Device Data API is optimized. Exception scenario descriptions are added for the inverter shutdown time field (close_time) whose device type is string inverter (devTypeId:1) or residential inverter (devTypeId:38).
03
The real-time device data list in Real-Time Device Data API is optimized. The unit of the active power field (active_power) whose device type is grid meter is changed to W.
The historical device data list in Historical Device Data API is optimized. The unit of the active power field (active_power) whose device type is grid meter is changed to W.
API Name |
API Method and Path |
Description |
Remarks |
|---|---|---|---|
https://Domain name of the management system/thirdData/getDevList |
The device model field is added to the returned packet. |
The API is changed. |
|
https://Domain name of the management system/thirdData/getDevRealKpi |
The rated_capacity field is added to the packet returned by the residential energy storage device (devTypeId:39). |
The API is changed. |
01
Added Revoking Authorization by an Owner.
Optimized Error Code List.
Optimized Scenario-based Practices of Battery Scheduling.
Optimized Handling the Exception Returned by Calling the Token Obtaining API.
Optimized Why Does the Northbound API Login Fail?
API Name |
API Method and Path |
Description |
Remarks |
|---|---|---|---|
API for Delivering Dispatch-based Battery Charge and Discharge Tasks |
https://Domain name of the management system/rest/openapi/pvms/nbi/v1/control/battery/battery-dispatch/async-task |
Added the support for ESS charge/discharge based on grid dispatch in the scenario where the inverter is directly connected. |
The API is changed. |
API for Delivering a Task for Setting the Battery Working Mode |
https://Domain name of the management system/rest/openapi/pvms/nbi/v1/control/battery/mode/async-task |
Added the support for the third-party dispatch in the scenario where the inverter is directly connected. |
The API is changed. |
24.6.0 Northbound API Changes
02
Added devTypeId Reference Table Returned by the Device List API.
Optimized Why Is the Plant ID Returned by the Plant List Inconsistent with That Displayed on the SmartPVMS? and Why Do the Plant IDs Returned for the Same Plant Vary Depending on API Accounts?
01
API Name |
API Method and Path |
Description |
Remarks |
|---|---|---|---|
https://Domain name of the management system/rest/openapi/pvms/nbi/v1/configuration/battery-mode |
This API is used to query the battery working mode. The battery supports the following working modes: maximumSelfConsumption, TOU, Fully fid to grid, and thirdPartyDispatch. |
The API is added. |
|
https://Domain name of the management system/rest/openapi/pvms/nbi/v1/configuration/active-power-control-mode |
This API is used to query the active power control mode of inverters in plant networking. The control modes include noLimit, limitedPowerGridKW, limitedPowerGridPercent, and zeroExportLimitation. |
The API is added. |
|
API for Delivering Dispatch-based Battery Charge and Discharge Tasks |
https://Domain name of the management system/rest/openapi/pvms/nbi/v1/control/battery/battery-dispatch/async-task |
This API is used to deliver battery charge and discharge tasks based on the plant DN and battery DN in third-party dispatch mode. For the same battery, do not call this API repeatedly before a task is complete. The networking of a single controller (Dongle or EMMA) in a plant is supported. |
The API is added. |
API for Querying Dispatch-based Battery Charge and Discharge Tasks |
https://Domain name of the management system/rest/openapi/pvms/nbi/v1/control/battery/battery-dispatch/task-info |
This API is used to query the execution status of dispatch-based battery charge and discharge tasks. Do not call this API repeatedly before a task is complete. |
The API is added. |
https://Domain name of the management system/thirdData/getStationRealKpi |
Added the daily_on_grid_energy and daily_use_energy indicators. |
The API is changed. |
|
API for Delivering a Task for Setting the Battery Working Mode |
https://Domain name of the management system/rest/openapi/pvms/nbi/v1/control/battery/mode/async-task |
Added the third-party dispatch mode. |
The API is changed. |
API for Querying a Task for Setting the Battery Working Mode |
https://Domain name of the management system/rest/openapi/pvms/nbi/v1/control/battery/mode/task-info |
This API is used to query the task execution status of setting the third-party dispatch mode for a battery. |
The API is changed. |
Optimized Scenario-based Practices of Battery Scheduling.
Optimized Handling the Exception Returned by Calling the Token Obtaining API.
24.5.0 Northbound API Changes
03
Optimized Creating an OAuth 2.0 Client for a Third-Party App.
02
Added Scenario-based Practices of Battery Scheduling.
Optimized Flow Control Using the API Account and API for Delivering Battery Charge and Discharge Tasks.
01
API Name |
API Method and Path |
Description |
Remarks |
|---|---|---|---|
API for Delivering a Task for Setting the Battery Working Mode |
https://Domain name of the management system/rest/openapi/pvms/nbi/v1/control/battery/mode/async-task |
This API is used to deliver the task of setting the battery working mode based on the plant DN. For the same plant, do not call this API repeatedly before a task is complete. The battery working mode can be set to maximumSelfConsumption or TOU. |
The API is added. |
API for Querying a Task for Setting the Battery Working Mode |
https://Domain name of the management system/rest/openapi/pvms/nbi/v1/control/battery/mode/task-info |
This API is used to query the execution status of the task for setting the battery working mode. Do not call this API repeatedly before a task is complete. |
The API is added. |
https://Domain name of the management system/rest/openapi/pvms/nbi/v1/control/battery/configuration/async-task |
This API is used to deliver the task of setting the battery parameters based on the plant DN. For the same plant, do not call this API repeatedly before a task is complete. Users can set plant-level battery parameters (end-of-charge SOC, end-of-discharge SOC, maximum charge power, and maximum discharge power). |
The API is added. |
|
https://Domain name of the management system/rest/openapi/pvms/nbi/v1/control/battery/configuration/task-info |
This API is used to query the execution status of the task for setting the battery parameters. Do not call this API repeatedly before a task is complete. |
The API is added. |
|
https://Domain name of the management system/rest/openapi/pvms/nbi/v2/control/active-power-control/async-task |
This API is used to deliver an inverter active power setting task based on the plant DN. For the same plant, do not call this API repeatedly before a task is complete. The active power can be controlled in two modes: unlimited and limited feed-in (kW). |
The API is added. |
|
https://Domain name of the management system/rest/openapi/pvms/nbi/v2/control/active-power-control/task-info |
This API is used to query the execution status of the inverter active power setting task. Do not call this API repeatedly before a task is complete. |
The API is added. |
|
https://Domain name of the management system/thirdData/getKpiStationHour |
The PVYield and inverterYield fields are added to the returned packet. |
The API is changed. |
|
https://Domain name of the management system/thirdData/getKpiStationDay |
The PVYield and inverterYield fields are added to the returned packet. |
The API is changed. |
|
https://Domain name of the management system/thirdData/getKpiStationMonth |
The PVYield and inverterYield fields are added to the returned packet. |
The API is changed. |
|
https://Domain name of the management system/thirdData/getKpiStationYear |
The PVYield and inverterYield fields are added to the returned packet. |
The API is changed. |
|
API for Delivering an Inverter Active Power Setting Task |
https://Domain name of the management system/rest/openapi/pvms/nbi/v1/control/active-power-control/async-task |
You are advised not to use this API. API for Delivering an Inverter Active Power Setting Task is recommended. |
The API is changed. |
API for Querying Inverter Active Power Setting Tasks |
https://Domain name of the management system/rest/openapi/pvms/nbi/v1/control/active-power-control/task-info |
You are advised not to use this API. API for Querying Inverter Active Power Setting Tasks is recommended. |
The API is changed. |
24.4.0 Northbound API Changes
01
None
24.2.0 Northbound API Changes
03
Optimized Initiating Authorization to a Third-Party App by an Owner, Exception Code List, Handling the Exception Returned by Calling the Authorization Request API, Why Do I Fail to Create an API Account?, and Why Is No Data or Only Part of Data Found When I Call a Northbound API for Data Query?
02
Optimized OAuth Connect and Flow Control Policy in OAuth Connect Mode.
Added How Do I Obtain O&M Support When Open APIs Are Accessed in OAuth Connect Mode?
01
During the evolution of open APIs, the original V6 APIs are incorporated into the basic APIs. For details, see Basic APIs. This change does not affect the normal use of the original APIs.
Some APIs are iterated, as listed in the following table. You are advised to use new high-performance APIs instead.
Added OAuth Connect.
Old API |
New API |
Description |
|---|---|---|
/thirdData/getStationList |
/thirdData/stations |
The new API supports pagination and data query by grid connection time. For details, see Plant List API. |
/thirdData/getDevFiveMinutes |
/thirdData/getDevHistoryKpi |
The new API supports a longer time range and better query performance. For details, see Historical Device Data API. |
/rest/openapi/pvms/v1/vpp/chargeAndDischarge |
/rest/openapi/pvms/nbi/v2/control/charge-and-discharge/async-task |
The new API can deliver different parameters to each plant. For details, see API for Delivering Battery Charge and Discharge Tasks. |