SmartPVMS 24.5.0 Northbound API Reference
API for Querying Inverter Active Power Setting Tasks
API Description
This API is used to query the execution status of the inverter active power setting task based on the task ID. Only one task can be queried at a time.
Call the API only when necessary to reduce the access frequency. For the same PV plant, do not call this API repeatedly before a task is complete.
Request URL
https://management system domain name/rest/openapi/pvms/nbi/v2/control/active-power-control/task-info
Request Mode
HTTP method: POST
Request Parameters
Parameter |
Description |
Data Type |
Mandatory/Optional |
|---|---|---|---|
taskId |
Unique ID of the requested task, which can be obtained from taskId in API for Delivering an Inverter Active Power Setting Task. The value contains 16 characters. |
String |
M |
Response Packet
Parameter |
Description |
Data Type |
Remarks |
|---|---|---|---|
success |
Request success or failure flag. The value true indicates that the request is successful, and the value false indicates that the request fails. |
boolean |
Request success or failure flag |
failCode |
Error code. Value 0 indicates that the status is normal. For other error codes, see Error Code List. |
Integer |
- |
message |
Request description. When the value of failCode is 0, the request failure description is returned. In other cases, null is returned. |
String |
- |
data |
Returned data for each request, including the following information: |
Object |
- |
> dispatchResult |
dispatchResult contains the list of returned information about request execution, including the following information: |
List |
- |
>> plantCode |
Plant DN. |
String |
- |
>> status |
Status of the task delivered to the plant. |
String |
RUNNING: The task delivered to the plant is running. SUCCESS: The task is successfully delivered to the plant. FAIL: The task fails to deliver to the plant. |
>> message |
Request description. When the value of status is FAIL, the description of the plant delivery failure is returned. In other cases, no description is returned. |
String |
FAILURE: The delivery fails. TIMEOUT: A timeout occurs. BUSY: The device is busy. INVALID: The device is invalid. EXCEPTION: An exception occurs. |
>> controlMode |
Active power control mode. |
String |
0: unlimited 6: limited feed-in (kW) |
>> controlInfo |
Parameter for setting the active power. |
Object |
This parameter is returned when controlMode is set to 6. |
>>> maxGridFeedInPower |
Maximum grid feed-in power (kW). It specifies the maximum active power transmitted from the grid-connection point to the power grid. |
Double |
The value range of this parameter is related to the controller in the plant. The value ranges are as follows: Dongle: [-1000.000, 5000.000] EMMA: [-1000.000, inverter rated power] SmartLogger: [-1000.000, 5000.000] Distributed SmartLogger: [-1000.000, 50000.000] Inverter: [-1000.000, 5000.000] |
>>> limitationMode |
Limitation mode. Total power: controls the total power at the grid-connection point to limit the power fed to the power grid. Single-phase power: controls the power of each phase at the grid-connection point to limit the power fed to the power grid. |
String |
0: total power 1: single-phase power |
> startTime |
Time when a task is received, including the time zone information. |
String |
2020-02-06T00:00:00+08:00 |
> endTime |
Time when a task is completed, including the time zone information. If a task is not completed, null is returned. |
String |
2020-02-06T00:00:00+08:00 |
Example
Request example:
{
"taskId": "3051190140256431"
}
Response examples:
Example 1: An error code is returned.
{
"failCode": 20620,
"success": false,
"message": "The taskId is not exist.",
"data": null
}
Example 2: An exception is returned.
{
"exceptionId": "framwork.remote.Paramerror",
"exceptionType": "ROA_EXFRAME_EXCEPTION",
"descArgs": null,
"reasonArgs": [
"taskId"
],
"detailArgs": [
"taskId may not be null"
],
"adviceArgs": null
}
Example 3: The returned task status is RUNNING.
{
"failCode": 0,
"success": true,
"message": "The active power control task status queried successfully.",
"data": {
"dispatchResult": [
{
"plantCode": "NE=234567891",
"controlMode": "6",
"status": "RUNNING",
"message": null,
"controlInfo": {
"maxGridFeedInPower": 53,
"limitationMode": "1"
}
}
],
"startTime": "2024-03-07T09:36:13+08:00",
"endTime": null
}
}
Example 4: The returned task status is FAIL.
{
"failCode": 0,
"success": true,
"message": "The active power control task status queried successfully.",
"data": {
"dispatchResult": [
{
"plantCode": "NE=234567891",
"controlMode": "6",
"status": "FAIL",
"message": "FAILURE",
"controlInfo": {
"maxGridFeedInPower": 53,
"limitationMode": "1"
}
}
],
"startTime": "2024-03-07T09:36:13+08:00",
"endTime": "2024-03-07T09:36:23+08:00"
}
}
{
"failCode": 0,
"success": true,
"message": "The active power control task status queried successfully.",
"data": {
"dispatchResult": [
{
"plantCode": "NE=234567891",
"controlMode": "6",
"status": "SUCCESS",
"message": null,
"controlInfo": {
"maxGridFeedInPower": 53,
"limitationMode": "1"
}
}
],
"startTime": "2024-03-07T09:38:58+08:00",
"endTime": "2024-03-07T09:38:58+08:00"
}
}