SmartPVMS 24.5.0 Northbound API Reference

SmartPVMS
24.5.0
NBI Reference
Issue 01
Date 2024-07-01
HUAWEI DIGITAL POWER TECHNOLOGIES CO., LTD.

Copyright © Huawei Digital Power Technologies Co., Ltd. 2024. All rights reserved.
No part of this document may be reproduced or transmitted in any form or by any means without prior
written consent of Huawei Digital Power Technologies Co., Ltd.
Trademarks and Permissions
and other Huawei trademarks are the property of Huawei Technologies Co., Ltd.
All other trademarks and trade names mentioned in this document are the property of their respective
holders.
Notice
The purchased products, services and features are stipulated by the contract made between Huawei
Digital Power Technologies Co., Ltd. and the customer. All or part of the products, services and features
described in this document may not be within the purchase scope or the usage scope. Unless otherwise
specified in the contract, all statements, information, and recommendations in this document are
provided "AS IS" without warranties, guarantees or representations of any kind, either express or implied.
The information in this document is subject to change without notice. Every effort has been made in the
preparation of this document to ensure accuracy of the contents, but all statements, information, and
recommendations in this document do not constitute a warranty of any kind, express or implied.
Huawei Digital Power Technologies Co., Ltd.

Address: Huawei Digital Power Antuoshan Headquarters
Futian, Shenzhen 518043
People's Republic of China
Website: https://digitalpower.huawei.com
Issue 01 (2024-07-01) Copyright © Huawei Digital Power Technologies Co., Ltd. i

SmartPVMS
NBI Reference Contents
Contents
1 Change History.........................................................................................................................1
2 Overview....................................................................................................................................6
2.1 Introduction to Northbound Open APIs.......................................................................................................................... 6
2.2 API Architecture....................................................................................................................................................................... 7
2.3 API Overview.............................................................................................................................................................................8
3 API Access................................................................................................................................12
3.1 OAuth Connect...................................................................................................................................................................... 12
3.1.1 Creating an OAuth 2.0 Client for a Third-Party App............................................................................................. 12
3.1.2 Integrating OAuth 2.0 to Third-Party Apps.............................................................................................................. 14
3.1.2.1 Adaptation Process Overview.................................................................................................................................... 15
3.1.2.2 Initiating Authorization to a Third-party App by an Owner........................................................................... 16
3.1.2.3 Obtaining the Access Token of the Open API by a Third-Party App............................................................21
3.1.3 Calling Open APIs by Third-Party Apps..................................................................................................................... 25
3.1.4 Incremental Authorization or Authorization Revocation.....................................................................................28
3.2 API Account Access...............................................................................................................................................................29
3.2.1 Obtaining an Account...................................................................................................................................................... 30
3.2.2 Authentication API............................................................................................................................................................ 31
3.2.2.1 Login API........................................................................................................................................................................... 31
3.2.2.2 Logout API........................................................................................................................................................................ 35
3.2.3 Calling an API..................................................................................................................................................................... 37
4 Flow Control Description.....................................................................................................40

4.1 Flow Control Policy in OAuth Connect Mode............................................................................................................. 40
4.2 Flow Control Using the API Account.............................................................................................................................. 41
5 API Reference......................................................................................................................... 51
5.1 Basic APIs................................................................................................................................................................................. 51
5.1.1 Basic....................................................................................................................................................................................... 51
5.1.1.1 Plant List API....................................................................................................................................................................51
5.1.1.2 Device List API................................................................................................................................................................. 54
5.1.2 Monitoring........................................................................................................................................................................... 58
5.1.2.1 Real-Time Plant Data API........................................................................................................................................... 58
5.1.2.2 Real-Time Device Data API.........................................................................................................................................62
5.1.2.3 Historical Device Data API.......................................................................................................................................... 95
Issue 01 (2024-07-01) Copyright © Huawei Digital Power Technologies Co., Ltd. ii

SmartPVMS
5.1.3 Alarm................................................................................................................................................................................... 125

5.1.3.1 API for Querying Active Alarms.............................................................................................................................. 125
5.1.4 Report..................................................................................................................................................................................133
5.1.4.1 Hourly Plant Data API................................................................................................................................................ 133
5.1.4.2 Daily Plant Data API................................................................................................................................................... 139
5.1.4.3 Monthly Plant Data API............................................................................................................................................ 144
5.1.4.4 Yearly Plant Data API................................................................................................................................................. 149
5.1.4.5 Daily Device Data API................................................................................................................................................ 154
5.1.4.6 Monthly Device Data API.......................................................................................................................................... 159
5.1.4.7 Yearly Device Data API.............................................................................................................................................. 163
5.2 Control APIs.......................................................................................................................................................................... 167
5.2.1 API for Delivering Battery Charge and Discharge Tasks....................................................................................168
5.2.2 API for Querying Battery Charge and Discharge Tasks..................................................................................... 173
5.2.3 API for Delivering a Task for Setting the Battery Working Mode.................................................................. 176
5.2.4 API for Querying a Task for Setting the Battery Working Mode....................................................................184
5.2.5 API for Delivering a Task for Setting Battery Parameters................................................................................. 189
5.2.6 API for Querying a Task for Setting Battery Parameters...................................................................................194
5.2.7 API for Delivering an Inverter Active Power Setting Task................................................................................. 198
5.2.8 API for Querying Inverter Active Power Setting Tasks....................................................................................... 204
6 References............................................................................................................................. 209
6.1 Error Code List..................................................................................................................................................................... 209
6.2 Old Policy for API Flow Control..................................................................................................................................... 216
6.3 Time Zone Code List.......................................................................................................................................................... 217
6.4 Exception Code List............................................................................................................................................................ 224
7 Best Practices....................................................................................................................... 225

7.1 Obtaining a Token.............................................................................................................................................................. 225
7.2 Querying the Plant List.....................................................................................................................................................226
7.3 Querying the Real-Time Plant Data............................................................................................................................ 227
7.4 Using the Access Token to Query the Real-Time Plant Data..............................................................................228
7.5 Scenario-based Practices of Battery Scheduling...................................................................................................... 229
8 FAQs....................................................................................................................................... 231
8.1 FAQs About the OAuth Connect Mode.......................................................................................................................231
8.1.1 Handling the Exception Returned by Calling the Authorization Request API........................................... 231
8.1.2 Handling the Exception Returned by Calling the Token Obtaining API.......................................................232
8.1.3 Why Does the Northbound API Return Error Code 305?.................................................................................. 232
8.1.5 Why Does the Northbound API Return Error Code 407 or 429?.................................................................... 233
8.1.6 How Do I Obtain O&M Support When Open APIs Are Accessed in OAuth Connect Mode?............... 234
8.2 FAQs About the API Account Mode............................................................................................................................. 235
8.2.1 Why Do I Fail to Create an API Account?............................................................................................................... 235
8.2.2 What Is the New or Old Flow Control Policy for Northbound APIs?............................................................ 235
Issue 01 (2024-07-01) Copyright © Huawei Digital Power Technologies Co., Ltd. iii
SmartPVMS
8.2.3 Why Does the Login Fail After I Enter the Correct Username and Password?..........................................236
8.2.4 Why Do I Need to Log In Again When I Use the Token to Call an API?..................................................... 236
8.2.6 Why Does the Northbound API Return Error Code 407 or 429?.................................................................... 237
8.3 Why Is No Data or Only Part of Data Found When I Call a Northbound API for Data Query?.............237
8.4 How Long Is the Data Collection Time of the API for Real-Time Plant Data?............................................. 241
8.5 Why Do the Hourly/Daily/Monthly/Yearly Data APIs of the Plant or the Daily/Monthly/Yearly Data
APIs of the Device Sometimes Return Small Data Value?.......................................................................................... 241
8.6 Why Do I Fail to Query Historical Alarms by Calling the Alarm Query API?................................................ 241
8.7 Why Does the /thirdData/getStationList API Return Error Code 401 or 402?.............................................. 241
8.8 Why Is the Plant ID Returned by the Plant List Inconsistent with That Displayed on the SmartPVMS?
......................................................................................................................................................................................................... 241
8.9 Why Do the Plant IDs Returned for the Same Plant Vary Depending on Open API Users?.................... 241
8.10 How Do I Compare and Obtain Plants That Are Not Returned by the Plant List API?........................... 242
Issue 01 (2024-07-01) Copyright © Huawei Digital Power Technologies Co., Ltd. iv

SmartPVMS
NBI Reference 1 Change History
1 Change History
24.5.0 Northbound API Changes
03
Optimized 3.1.1 Creating an OAuth 2.0 Client for a Third-Party App.
02
Added 7.5 Scenario-based Practices of Battery Scheduling.
Optimized 4.2 Flow Control Using the API Account and 5.2.1 API for Delivering
Battery Charge and Discharge Tasks.
01
API Name Method and Path Description Re
mar
ks
API for https://Domain name of the This API is used to Ne

Delivering management system/rest/ deliver the task of w
a Task for openapi/pvms/nbi/v1/control/ setting the battery API
Setting the battery/mode/async-task working mode based
Battery on the plant DN. For
Working the same PV plant, do
Mode not call this API
repeatedly before a
task is complete. The
battery working mode
can be set to
Maximum Self-
Consumption or TOU.
Issue 01 (2024-07-01) Copyright © Huawei Digital Power Technologies Co., Ltd. 1

SmartPVMS

mar
ks

Querying a management system/rest/ query the execution w
Task for openapi/pvms/nbi/v1/control/ status of the task for API
Setting the battery/mode/task-info setting the battery
Battery working mode. Do not
Working call this API repeatedly
Mode before a task is
complete.

Delivering management system/rest/ deliver the task of w
a Task for openapi/pvms/nbi/v1/control/ setting the battery API
Setting battery/configuration/async-task parameters based on
Battery the plant DN. For the
Parameters same PV 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).

Querying a management system/rest/ query the execution w
Task for openapi/pvms/nbi/v1/control/ status of the task for API
Setting battery/configuration/task-info setting the battery
Battery parameters. Do not call
Parameters this API repeatedly
before a task is
complete.

Delivering management system/rest/ deliver an inverter w
an Inverter openapi/pvms/nbi/v2/control/ active power setting API
Active active-power-control/async-task task based on the plant
Power DN. For the same
Setting plant, do not call this
Task API repeatedly before a
task is complete. The
active power can be
controlled in two
modes: unlimited and
limited feed-in (kW).

SmartPVMS

mar
ks
API for https://management system Query the execution Ne

Querying domain name/rest/openapi/ status of the inverter w
Inverter pvms/nbi/v2/control/active- active power setting API
Active power-control/task-info task. Do not call this
Power API repeatedly before a
Setting task is complete.
Tasks
Hourly https://Domain name of the The PVYield and Mo

Plant Data management system/thirdData/ inverterYield fields are difie
API getKpiStationHour added to the returned d
packet. API
Daily Plant https://{Domain name of the The PVYield and Mo

Data API management system}/thirdData/ inverterYield fields are difie
getKpiStationDay added to the returned d
packet. API
Monthly https://{Domain name of the The PVYield and Mo

Plant Data management system}/thirdData/ inverterYield fields are difie
API getKpiStationMonth added to the returned d
packet. API
Yearly https://Domain name of the The PVYield and Mo

Plant Data management system/thirdData/ inverterYield fields are difie
API getKpiStationYear added to the returned d
packet. API
API for https://Management system You are not advised to Mo

Delivering domain name/rest/openapi/ use this API. 5.2.7 API difie
an Inverter pvms/nbi/v1/control/active- for Delivering an d
Active power-control/async-task Inverter Active Power API
Power Setting Task is
Setting Task recommended.
API for https://Management system You are not advised to Mo

Querying domain name/rest/openapi/ use this API. 5.2.8 API difie
Inverter pvms/nbi/v1/control/active- for Querying Inverter d
Active power-control/task-info Active Power Setting API
Power Tasks is recommended.
Setting
Tasks
01
None

SmartPVMS
03
Optimized 3.1.2.2 Initiating Authorization to a Third-party App by an Owner,
6.4 Exception Code List, 8.1.1 Handling the Exception Returned by Calling the
Authorization Request API, 8.2.1 Why Do I Fail to Create an API Account?, and
8.3 Why Is No Data or Only Part of Data Found When I Call a Northbound API
for Data Query?
02
Optimized 3.1 OAuth Connect and 4.1 Flow Control Policy in OAuth Connect
Mode.
Added 8.1.6 How Do I Obtain O&M Support When Open APIs Are Accessed in
OAuth Connect Mode?
01
CAUTION
During the evolution of open APIs, the original V6 APIs are incorporated into the
basic APIs. For details, see 5.1 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 3.1 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
5.1.1.1 Plant List API.
/thirdData/ /thirdData/ The new API supports a

getDevFiveMinutes getDevHistoryKpi longer time range and
better query
performance. For details,
see 5.1.2.3 Historical
Device Data API.

SmartPVMS
Old API New API Description
/rest/openapi/ /rest/openapi/ The new API can deliver

pvms/v1/vpp/ pvms/nbi/v2/control/ different parameters to
chargeAndDischarge charge-and-discharge/ each plant. For details,
async-task see 5.2.1 API for
Delivering Battery
Charge and Discharge
Tasks.

SmartPVMS
NBI Reference 2 Overview
2 Overview
NOTICE
Please use the latest northbound API reference document by choosing Company
Management > Northbound Management > Developer Guide.
2.1 Introduction to Northbound Open APIs

Northbound Open APIs
Northbound open APIs are open interfaces based on the Representational State
Transfer (REST) standard and can facilitate integration of third-party systems.
Third-party systems can use RESTful NBIs to access the resources authorized by
the SmartPVMS, such as access authentication, configuration, alarm, and
performance data.
APIs can be used only after authorization and the access is secure. Only HTTPS
access is supported.

SmartPVMS
The JavaScript Object Notation (JSON) data format is used for data interaction.
The data format is simple, easy to read and write, and occupies less network
traffic than XML.
What Is REST?
REST, short for Representational State Transfer, is a design and development mode
for network applications. It simplifies development and improves system
scalability.
REST uses resources as its core, and resources are uniquely identified by a uniform
resource identifier (URI), for example, /rest/openapi/pvms/v1/plants.
REST uses four types of standard operations to access resources: POST, GET, PUT,
and DELETE.
● POST: creates resources.
● GET: queries resources.
● PUT: updates resources.
● DELETE: deletes resources.
The SmartPVMS provides external services using URIs. Users obtain SmartPVMS
resources through URIs and obtain services.
HTTP Status Codes

The first line of all HTTP responses is the status line, which contains the current
HTTP version number, the status code consisting of three digits, and the phrase
that describes the status, which are separated by spaces.
The first digit of the status code indicates the type of the current response.
● 1xx message: The request has been received by the server and continues to be
processed.
● 2xx success: The request has been received, understood, and accepted by the
server.
● 3xx redirection: This request can be completed only after subsequent
operations are performed.
● 4xx request error: The request contains a syntax error or cannot be executed.
● 5xx server error: An error occurs when the server processes a correct request.
2.2 API Architecture

The SmartPVMS provides a set of WebService APIs for third-party systems and
third-party developers, who can construct HTTPS requests to call APIs and obtain
SmartPVMS resources and data.

SmartPVMS
Figure 2-1 WebService NBI architecture
2.3 API Overview

API API API Name Description
Cate Labe
gory l
Basic Basic Plant List Returns the static information about the plants
APIs data on which the current account has permission by
page. Some information, such as the plant ID, is
the prerequisite for querying other API data. The
static information changes only when the plants
change. The third-party system must save the
information.
Device List Returns the device list of a given plant by page.

Some information, such as the plant ID, is the
prerequisite for querying other API data. The
third-party system must save the information.
Moni Real-time Obtains real-time data such as the energy yield,

torin plant data revenue, and health status of the plant on the
g current day. The data is updated every 5 minutes.
data The calling party must save the data.

SmartPVMS

Cate Labe
gory l
Real-time Obtains real-time device data. The real-time data

device data varies depending on the device type. The data is
updated every 5 minutes. The calling party must
save the data.
Historical Obtains the 5-minute data of a device in a given

device data period. The data items vary depending on the
device type. The calling party must save the data.
Alar Querying Queries device active alarms of by plant or query

m active alarms of a specific device.
data alarms
Repo Hourly plant Queries the hourly data of a plant in a day. The
rt data data items include inverter energy yield and feed-
data in energy. The data update is delayed. Generally,
only the current-day data is updated. The calling
party must save the data.
Daily plant Queries the daily data of a plant in a month. The

data data items include inverter energy yield, feed-in
energy, and energy consumption. The data
update is delayed. Generally, only the current-day
data is updated. The calling party must save the
data.
Monthly Queries the monthly data of a plant in a year.

plant data The data items include inverter energy yield,
feed-in energy, and energy consumption. The
data update is delayed. Generally, only the
current-month data is updated. The calling party
must save the data.
Yearly plant Queries the yearly data of a plant in its life cycle.
data The data items include inverter energy yield,
feed-in energy, and energy consumption. The
data update is delayed. Generally, only the
current-year data is updated. The calling party
must save the data.
Daily device Queries the daily data of a device. The data items
data vary depending on the device. The data update is
delayed. Generally, only the current-day data is
updated. The calling party must save the data.
Monthly Queries the monthly data of a device. The data

device data items vary depending on the device. The data
update is delayed. Generally, only the current-
month data is updated. The calling party must
save the data.

SmartPVMS

Cate Labe
gory l
Yearly device Queries the yearly data of a device. The data

data items vary depending on the device. The data
update is delayed. Generally, only the current-
year data is updated. The calling party must save
the data.
Cont ESS Delivering Delivers battery charge/discharge tasks based on

rol charg battery plant codes. For the same plant, do not call this
APIs e/ charge/ API repeatedly before a task is complete. If there
disch discharge are multiple ESSs in the power plant, the task is
arge tasks executed on every ESS.
Querying Queries the delivery result of an asynchronous

battery battery charge/discharge task. Do not call this
charge/ API repeatedly before a task is complete.
discharge
tasks
Inver API for This API is used to deliver an inverter active

ter Delivering power setting task based on the plant DN. For
activ an Inverter the same plant, do not call this API repeatedly
e Active before a task is complete. The active power can
powe Power be controlled in two modes: unlimited and
r Setting Task limited feed-in (kW).
settin
g API for Query the execution status of the inverter active
Querying power setting task. Do not call this API
Inverter repeatedly before the task is complete.
Active
Power
Setting
Tasks
Setti API for This API is used to deliver the task of setting the
ng Delivering a battery working mode based on the plant DN.
the Task for For the same PV plant, do not call this API
batte Setting the repeatedly before a task is complete. The battery
ry Battery working mode can be set to Maximum Self-
worki Working Consumption or TOU.
ng Mode
mode
API for This API is used to query the execution status of
Querying a the task for setting the battery working mode. Do
Task for not call this API repeatedly before a task is
Setting the complete.
Battery
Working
Mode

SmartPVMS

Cate Labe
gory l
Batte API for This API is used to deliver the task of setting the
ry Delivering a battery parameters based on the plant DN. For
para Task for the same PV plant, do not call this API repeatedly
mete Setting before a task is complete. Users can set plant-
r Battery level battery parameters (end-of-charge SOC,
settin Parameters end-of-discharge SOC, maximum charge power,
g and maximum discharge power).
API for This API is used to query the execution status of

Querying a the task for setting the battery parameters. Do
Task for not call this API repeatedly before a task is
Setting complete.
Battery
Parameters

SmartPVMS
NBI Reference 3 API Access
3 API Access
The SmartPVMS northbound open APIs provide two access modes for third-party
systems and third-party developers.
In the scenario where a third-party enterprise platform is interconnected, OAuth

Connect is used to access northbound open APIs. Basic APIs and control APIs can
be used in the OAuth Connect scenario.
The platforms developed by installers can access the open APIs using API
accounts. Basic APIs can be used in the API account access scenario.
NOTICE
The access to open APIs in OAuth Connect mode is for trial use only in Europe.
The policy may change in the future.
3.1 OAuth Connect

In OAuth Connect mode, third-party apps need to adapt to the OAuth 2.0 protocol
to access northbound open APIs.
OAuth 2.0 is an open authorization protocol that allows third-party apps to access
resources authorized by owners without obtaining their usernames and passwords.
A third-party app can apply for creating an OAuth 2.0 client on the FusionSolar.
After the FusionSolar owner authorizes the application, the FusionSolar owner
account is bound to the client. The third-party app then can access the
northbound open APIs to access the resources authorized by the owner.
The following sections describe the process of accessing northbound open APIs in
OAuth Connect mode.
3.1.1 Creating an OAuth 2.0 Client for a Third-Party App

To enable a third-party app to access northbound open APIs in OAuth Connect
mode, you need to apply for and create an OAuth 2.0 client on the FusionSolar.
Use the following template to initiate an application and send it to

SmartPVMS
huaweipartners@huawei.com (available only in Europe). FusionSolar will help

complete the application. The procedure is as follows.
Step 1 A third-party app initiates an application based on the following template.

Applicatio Description Filled by
n Third-Party
Informatio Platform
n
Agreemen By initiating an application, you acknowledge and Agree

t on Use of agree to the Agreement on Use of Huawei APIs.
Huawei
APIs
Company Company name

Name
Registered Registered place of the company

Place
Company Company address

Address
Legal Legal entity

Entity
Employer Employer identification number

Identificati
on
Number
(EIN)
Contact Contact number

Number
Email Email address for registering a third-party app.

After the registration is successful, related
information will be sent to this email address.
Example: Huawei_Tool@huawei.com
App Name Name of a third-party app. The value can contain

letters, digits, hyphens (-), and underscores (_). This
field displays information about apps authorized by
owners.
Example: Huawei_Tool
Descriptio Third-party app description.

n Example: a tool developed by Huawei Digital
Power. It is mainly used in residential PV scenarios
to provide customers with a convenient home
energy management service platform.

SmartPVMS
Applicatio Description Filled by

n Third-Party
Informatio Platform
n
Redirect Callback URL in the OAuth 2.0 authentication

URL process. The redirect URI cannot contain .., redirect,
or #.
After the owner approves the authorization, an
authorization code is generated. The third-party
app can obtain the authorization code through
RedirectUrl.
Example: https://www.huaweitool.com/xxx?
somearg=huaweitool.mainpage
If a third-party app needs to modify RedirectUrl, RedirectUrl used when the

owner initiates authorization and the third-party app obtains the token also needs
to be updated.
Step 2 After completing the application, the FusionSolar returns the following OAuth 2.0
client information to the third-party app.
Parame Dat Description
ter a
Typ
e
client_id Strin Client ID. It is the ID allocated by FusionSolar to a third-party

g app.
client_s Strin Client secret. It is the client secret allocated by FusionSolar to

ecret g a third-party app.
scope Strin Permission set. It is the permission set opened by FusionSolar

g to third-party apps, for example, basic APIs
(pvms.openapi.basic) and control APIs (pvms.openapi.control).
After receiving client_id and client_secret, the third-party app must keep them
secure.
----End
3.1.2 Integrating OAuth 2.0 to Third-Party Apps

Third-party apps can integrate the authorization request link of the FusionSolar to
manage the authorization request function. When an owner clicks the
corresponding function, the authorization request process starts.

SmartPVMS
3.1.2.1 Adaptation Process Overview

Third-party app clients can access northbound open APIs in OAuth Connect mode.
The adaptation process is as follows: An owner accesses the authorization request
function integrated by a third-party app. The FusionSolar displays the login page
and authorization page for the owner to log in and authorize the OAuth 2.0 client
of the third-party app, and returns the authorization code generated after the
owner's authorization to the third-party app through the redirect URL. After
obtaining the authorization code, the third-party app uses it to access the
FusionSolar service and obtain the access token and refresh token. The third-party
app then uses the access token to access open APIs. The following figure shows
the process.
1-2: An owner accesses the FusionSolar through the authorization request link
integrated to a third-party app client and initiates the authorization code
request process.
3: The OAuth service responds to the request (HTTP status code: 302) and returns
the authorization page to the third-party app client. If the owner has not logged
in to FusionSolar, the OAuth service returns to the FusionSolar login page. After
the owner logs in, the authorization page is displayed.
4-5: After the owner confirms the authorization, the third-party app client
accesses the OAuth service to initiate an authorization request to the third-party
app client (OAuth 2.0 client).
6: The OAuth service responds to the request (HTTP status code: 302) and returns
the redirect URL and authorization code to the third-party app client.
7: The third-party app client sends a request carrying the authorization code to
request the redirect URL.
8-9: After obtaining the authorization code, the third-party app server uses the
authorization code to send a request to the OAuth API for obtaining tokens to
obtain the access token and refresh token.

SmartPVMS
10: The third-party app server uses the access token to access the northbound
open APIs for subsequent service processing.
NOTICE
An authorization code is used to generate an access token of a northbound open

API. A refresh token is used for refreshing the access token.
After the owner accesses the OAuth service and initiates authorization to a third-
party app, an authorization code is generated. The third-party app can use the
authorization code to access the OAuth service again to obtain the access token
and refresh token.
An authorization code is valid for 5 minutes. After obtaining the authorization
code, the third-party app needs to obtain the access token and refresh token as
soon as possible. After the authorization code expires, the owner needs to access
the OAuth service again to initiate authorization to the third-party app.
When a third-party app accesses the northbound open APIs in OAuth Connect
mode, the access token is used for authentication. The refresh token is used to
exchange for a new access token. The access token is valid for one hour. After it
expires, a third-party app cannot access the open APIs using the expired access
token and needs to obtain a new access token using the refresh token. If a refresh
token is used to obtain a new access token even when the old access token is still
in its validity period, the old access token will become invalid, and the third-party
app cannot access the open API through the old access token.
The access token and refresh token are sensitive information. Keep them secure.
3.1.2.2 Initiating Authorization to a Third-party App by an Owner

After a third-party app applies for an OAuth 2.0 client on the FusionSolar, an
owner initiates authorization to the client, accesses the OAuth service, calls the
authorization request API provided by the OAuth service, logs in to the
FusionSolar, and selects a permission set. After the authorization is complete and
successful, an authorization code is generated. The third-party app obtains the
authorization code through RedirectUrl.
Description of the Authorization Request API

The authorization request API is provided by the OAuth service for owners to
authorize OAuth 2.0 clients of third-party apps.
URL of the Authorization Request API

https://oauth2.fusionsolar.huawei.com/rest/dp/uidm/oauth2/v1/authorize
HTTP Method of the Authorization Request API

HTTP method: GET

SmartPVMS
Parameters of the Authorization Request API

Parameter Ma Dat Description
nda a
tor Type
y
(Ye
s/N
o)
response_t Yes Strin Response type. The value is fixed at code for the
ype g OAuth 2.0 authentication mode.
client_id Yes Strin Nine-digit client-id returned by the FusionSolar to a

g third-party app when the third-party app applies for
an OAuth 2.0 client.
redirect_uri Yes Strin RedirectUrl provided by the third-party app for the
g FusionSolar when the app applies for an OAuth 2.0
client.
scope No Strin Permission set that a third-party app needs to apply

g for from the owner. If multiple permissions are
required, use spaces to separate them. The space is
encoded as %20 in the URL. For details about all
supported permission sets, see the scope description
returned by the FusionSolar to the third-party app
when the third-party app applies for an OAuth 2.0
client. If the scope parameter is not specified, all
permissions authorized by the owner are used by
default.
locale No Strin Language used by the FusionSolar to display the

g login page and authorization page to the owners.
You are advised to leave this parameter blank. If this
parameter is left blank, the OAuth service
determines the language based on the language
supported by the browser used by the owners.
The following languages are supported: de-de
(German/Germany), en-us (English/United States),
es-es (Spanish/Spain), fr-fr (French/France), hu-hu
(Hungarian/Hungary), it-it (Italian/Italy), ja-jp
(Japanese/Japanese), ko-kr (Korean/Korea), nl-nl
(Dutch/Netherlands), pl-pl (Polish/Poland), pt-br
(Portuguese/Brazil), tr-tr (Turkish/Türkiye), uk-ua
(Ukrainian/Ukraine), vi-vn (Vietnamese/Vietnam),
zh-cn (Simplified Chinese/China), and zh-tw
(Traditional Chinese/Taiwan).

SmartPVMS
Response Packet of the Authorization Request API

Paramete Data Description
r Type
code String Authorization code generated after the owner authorizes

the third-party app. The authorization code is returned to
the third-party app through RedirectUrl registered by the
third-party app. The authorization code can be used to
generate an access token of the northbound open API.
Link Example of the Authorization Request API

Assume that a third-party app creates an OAuth 2.0 client on the FusionSolar.
Assume that the provided RedirectUrl is https://www.example.com/cn/ and the
allocated client_id is 123456789. The link of the authorization request API
combined by the third-party app is as follows:
https://oauth2.fusionsolar.huawei.com/rest/dp/uidm/oauth2/v1/authorize?
response_type=code&client_id=123456789&redirect_uri=https://www.example.com/cn/
Note that if RedirectUrl contains characters such as & and is directly used to
combine the URL of the authorization request API, a parameter exception page
may be returned. As a result, RedirectUrl is unavailable. Therefore, URL encoding
is required for RedirectUrl. For example, when RedirectUrl of the third-party app
is https://www.example1.com/cn/?example2=example3&example4=example5
and the URL code is https%3A%2F%2Fwww.example1.com%2Fcn%2F
%3Fexample2%3Dexample3%26example4%3Dexample5, the URL of the
authorization request API combined by the third-party app is as follows:
https://oauth2.fusionsolar.huawei.com/rest/dp/uidm/oauth2/v1/authorize?
response_type=code&client_id=123456789&redirect_uri=https%3A%2F%2Fwww.example1.com%2Fcn%2F
%3Fexample2%3Dexample3%26example4%3Dexample5
Usage of the Authorization Request API

A third-party app needs to combine the access link (as shown in Link Example of
the Authorization Request API) of the authorization request API and integrate
the link into the third-party app so that the owner can use the link to access the
FusionSolar login page.

SmartPVMS
Assume that the AppName of a third-party app is Third-party application. The

scope of the permission set that needs to be applied for from the owner includes
basic APIs (pvms.openapi.basic) and control APIs (pvms.openapi.control). After
the owner enters the FusionSolar account and password to log in to the
FusionSolar, the following authorization page is displayed.

SmartPVMS
On this page, the owner can select a permission set to authorize the OAuth 2.0
client of the third-party app. After the owner completes the authorization, an
authorization code is generated. The third-party app can obtain the authorization
code based on the RedirectUrl provided for the FusionSolar when applying for an
OAuth 2.0 client. For example, if the authorization code is B******B, the response
example is as follows:
https://www.example.com/cn/?code=B******B
If the owner rejects the authorization, the third-party app can obtain the following
information through RedirectUrl:
https://www.example.com/cn/?error=10002&error_description=access_is_denied
Exception Example of the Authorization Request API

If the scope parameter transferred in the combined request link is incorrect and
the RedirectUrl provided by a third-party app for the FusionSolar when applying
for an OAuth 2.0 client is https://www.example.com/cn/, the third-party app
can obtain the following information based on the RedirectUrl:

SmartPVMS
https://www.example.com/cn/?error=invalid_scope&error_description=OAuth
%202.0%20Parameter:%20scope
For more exception examples and troubleshooting methods, see 8.1.1 Handling
the Exception Returned by Calling the Authorization Request API.
3.1.2.3 Obtaining the Access Token of the Open API by a Third-Party App
After obtaining the authorization code from the RedirectUrl, the third-party app
needs to access the OAuth service again, request the token obtaining API provided
by the OAuth service to obtain the access token and refresh token based on the
authorization code, and select the permission set to be authorized by the owner to
the third-party app.
Description of the API for Obtaining Tokens

The API for obtaining tokens is provided by the OAuth service for third-party apps
to obtain the access token and refresh token. This API provides two usage
methods, which are distinguished by the grant_type parameter transferred in the
request API. When grant_type is set to authorization_code, the API for obtaining
tokens can obtain the access token and refresh token based on the authorization
code and the permission set selected by the owner to authorize the third-party
app. When grant_type is set to refresh_token, the API for obtaining tokens can
use the refresh token to obtain the access token and the permission set selected
by the owner to authorize the third-party app.
Request URL of the API for Obtaining Tokens

https://oauth2.fusionsolar.huawei.com/rest/dp/uidm/oauth2/v1/token
Request Method of the API for Obtaining Tokens

HTTP method: POST
Request Headers of the API for Obtaining Tokens

Content-Type: application/x-www-form-urlencoded
Request Parameters of the API for Obtaining Tokens

The following table lists the request parameters for obtaining the access token
and refresh token using the authorization code.
Parameter Data Description

Type
client_id String Nine-digit client-id returned by the FusionSolar to a

third-party app when the third-party app applies for an
OAuth 2.0 client.

SmartPVMS

Type
code String Authorization Code generated in 3.1.2.2 Initiating

Authorization to a Third-party App by an Owner. The
authorization code is called back to the third-party app
through the RedirectUrl provided for the FusionSolar
when the third-party app applies for an OAuth 2.0
client.
redirect_uri String RedirectUrl provided by the third-party app when it

applies for an OAuth 2.0 client.
client_secre String client-secret returned by the FusionSolar to a third-

t party app when the third-party app applies for an
OAuth 2.0 client.
grant_type String The value is fixed at authorization_code. When

grant_type is set to authorization_code, the current
API can obtain the open API access token and refresh
token based on the authorization code.
The following table describes the request parameters for obtaining the access
token using the refresh token.

Type
client_id String Nine-digit client-id returned by the FusionSolar to a

third-party app when the third-party app applies for
an OAuth 2.0 client.
refresh_toke String Refresh token obtained by a third-party app using an

n authorization code.
client_secret String client-secret returned by the FusionSolar to a third-

party app when the third-party app applies for an
OAuth 2.0 client.
grant_type String The value is fixed at refresh_token, which indicates

that the current API can use the refresh token to
obtain the access token.
Response Packet of the API for Obtaining Tokens

The following table lists the parameters in the response packet for obtaining the
access token and refresh token using the authorization code.

SmartPVMS

Type
access_toke String Access token obtained after the third-party app

n obtains the owner's authorization. It can be used as
the access token for accessing northbound open APIs.
refresh_toke String Refresh token obtained after the third-party app

n obtains the owner's authorization. If the access token
expires, you can obtain a new one using the refresh
token.
expires_in Integer Remaining validity period of the access token, in

seconds.
scope String Permission group of the token. If there are multiple

permission groups, separate them with spaces ('').
token_type String Type of the returned access token. The value is fixed
at Bearer.
The following table describes the parameters in the response packet for obtaining
the access token using the refresh token.

Type
access_toke String New access token obtained by the third-party app

n using the refresh token. It can be used as the access
token for accessing northbound open APIs.
refresh_toke String Refresh token obtained after the third-party app

n obtains the owner's authorization. If the access token
expires, you can obtain a new one using the refresh
token.
expires_in Integer Remaining validity period of the access token, in

seconds.
scope String Permission group of the token. If there are multiple

permission groups, separate them with spaces ('').
token_type String Type of the returned access token. The value is fixed
at Bearer.
Example Request and Response for Obtaining the Access Token and Refresh
Token Using the Authorization Code
Example Request
Assume that the parameters of the OAuth 2.0 client created by a third-party app
on the FusionSolar are as follows: RedirectUrl = https://www.example.com/cn/,

SmartPVMS
client_id = 123456789, client_secret = A******A, scope = pvms.openapi.basic and

pvms.openapi.control. The request example for obtaining the access token and
refresh token using the authorization codes is as follows:
POST /rest/dp/uidm/oauth2/v1/token HTTP/1.1
Host: oauth2.fusionsolar.huawei.com
grant_type=authorization_code&
code=B******B&
client_id=123456789&
client_secret=A******A&
redirect_uri=https://www.example.com/cn/
Response Example
After the owner authorizes a third-party app, assume that the parameters
obtained by the third-party app using the authorization code are as follows: AT =
a******t, RT = r******t, scope = pvms.openapi.basic and pvms.openapi.control.
The response example for obtaining the access token and refresh token using the
authorization code is as follows:
HTTP/1.1 200 OK
{
"access_token": "a******t",
"refresh_token":"r******t",
"expires_in": 3600,
"scope": "pvms.openapi.basic pvms.openapi.control",
"token_type": "Bearer"
}
Example Request and Response for Using a Refresh Token to Obtain an

Access Token
Example Request
Assume that the refresh token obtained by the third-party app using the
authorization code in the preceding procedure is r******t. An example request for
obtaining the access token using the refresh token is as follows:
POST /rest/dp/uidm/oauth2/v1/token HTTP/1.1
Host: oauth2.fusionsolar.huawei.com
grant_type=refresh_token&
refresh_token=r******t&
client_id=123456789&
client_secret=A******A
Response Example
If the third-party app uses the refresh token r******t to obtain a new access token
and the obtained new access token is b******b, an example response for obtaining
the access token using the refresh token is as follows:
HTTP/1.1 200 OK
{
"access_token": "b******b",
"refresh_token":"r******t",
"expires_in": 3600,
"scope": "pvms.openapi.basic pvms.openapi.control",
"token_type": "Bearer"
}

SmartPVMS
Handling Request Exceptions of the API for Obtaining Tokens

The following is an example of an exception when the grant_type parameter that
is not supported is used to access the API for obtaining tokens:
HTTP/1.1 400
{
"error_description": "unsupported_grant_type",
"error": "1111"
}
For more exception examples and troubleshooting methods, see 8.1.2 Handling
the Exception Returned by Calling the Token Obtaining API.
CAUTION
After the owner initiates authorization on the third-party app client, the third-
party app obtains the authorization tokens (access token and refresh token)
through the OAuth 2.0 authorization process. When an owner initiates
incremental authorization through a third-party app client, the old authorization
tokens automatically become invalid after the third-party app successfully obtains
new authorization tokens. It is recommended that an owner performs
incremental authorization on third-party apps through the FusionSolar app.
3.1.3 Calling Open APIs by Third-Party Apps

API Access
https://Domain name of the management system/specific API name+access
request parameters
Access Process
After adapting to the OAuth Connect mode, the third-party app obtains the
owner's authorization and the access token. The access token must be carried
when the app accesses specific data. The third-party app calls APIs to access the
specific data as required in the following process.

SmartPVMS
Access Example
The following uses the Plant List API as an example to describe how to access
FusionSolar open APIs in OAuth Connect mode. After obtaining the access token,
the third-party app carries it to access the plant list API.
Request example:
POST https://Domain name of the management system/thirdData/stations
Authorization: access token obtained by the bearer
Content-Type: application/json
Body:
{
"pageNo": 1,
"gridConnectedStartTime":1664718569000,
"gridConnectedEndTime":1667396969000
}
Response examples:
Example 1: An error code is returned.

SmartPVMS
{
"success": false,
"data": null,
"failCode": 20605,
"message": "The time cannot be a negative number."
}
Example 2: The plant list data is returned.

{
"success": true,
"data": {
"list": [
{
"plantCode": "NE=12345678",
"plantName": "NMplant1",
"plantAddress": null,
"longitude": null,
"latitude": null,
"capacity": 146.5,
"contactPerson": "",
"contactMethod": "",
"gridConnectionDate": "2022-11-21T16:23:00+08:00"
},
{
"plantName": "plant2",
"longitude": null,
"latitude": null,
"capacity": 123.3,
"gridConnectionDate": "2022-11-21T16:30:28-12:00"
}
],
"pageCount": 1,
"pageNo": 1,
"pageSize": 100,
"total": 2
},
"failCode": 0,
"message": "get plant list success"
}
Example 3: The access token is invalid and cannot be used to parse the
authorization information. The following error information is displayed.
{
"success": false,
"failCode": 305,
"message": "INVALID_CREDENTIAL"
}
Example 4: If the access token permission is insufficient, the following error

information is displayed.
{
"data": null,
"failCode": 401,
"message": "Invalid access to current interface!",
"params": {
},
"success": false
}
Examples 1 and 2 show access to the Plant List API in OAuth Connect mode. The
returned information varies according to the API internal services. Examples 3 and
4 indicate that the access token is invalid and the access token permission is

SmartPVMS
insufficient, respectively. For details about how to handle these exceptions, see
8.1.3 Why Does the Northbound API Return Error Code 305? and 8.1.4 Why
Does the Northbound API Return Error Code 401?
NOTICE
The following figure shows an example of the access token carried in the request
header of a northbound open API. (The value of the Authorization field consists
of Bearer and Access Token. The Plant List API is used as an example.)
In addition to the exception information in Access Example, for details about

other response information, see the response packet and response example of
each open API.
3.1.4 Incremental Authorization or Authorization Revocation

Log in to the FusionSolar app as an owner, choose Me > Settings > Account
security > Authorization Management, and select the third-party app that
requires incremental authorization or authorization revocation. Then tap the
button on the right of Basic APIs or Control APIs in the Authorization Content
area for incremental authorization or tap Revoke Authorization for authorization
revocation, as shown in the following figure.

SmartPVMS
3.2 API Account Access

To use an API account to access northbound open APIs, the company
administrator needs to create an API account, obtain the owner's authorization,
bind the API account to the plants of the company, and use the API account to call
APIs described in 3.2.2.1 Login API to obtain a token for identity authentication of
accessing other APIs.

SmartPVMS
Communication Between a Third-party System and the SmartPVMS
Figure 3-1 Communication between a third-party system and the SmartPVMS
NOTE
1. After the third-party system information is configured on the management system, use
the API account name and password to log in to the management system from the
third-party system.
2. After successful login, send requests to obtain data.
3. XSRF-TOKEN is a cross-site request token. After a user logs in to the system using the
API account name and password, the system returns this token to the user. If the user
adds the token to a subsequent request, the request is initiated by a logged-in API
account.
3.2.1 Obtaining an Account

The permission to access northbound APIs is created by the company
administrator. The procedure is as follows:
Step 1 Choose System > Company Management > Northbound Management from the
main menu.

SmartPVMS
Step 2 Click Add. In the dialog box that is displayed, set basic information, such as
Associated account, Username, and Password.
Step 3 If you enable Basic APIs in the APIs area, the API account has the permission to
access basic API data of northbound open APIs.
NOTE
To select all plants of a company, select the company.
Step 4 Optional: Select the company or plant for which you want to grant permission.
After the binding, the API account has permissions of the selected company or
plant.
Step 5 Click OK to save the settings.
----End
3.2.2 Authentication API

An account is used to call the login API to obtain a token for identity
authentication when accessing other data query APIs and control APIs.
3.2.2.1 Login API
API Description
● Before obtaining data, the login API must be called to obtain the XSRF-
TOKEN. The validity period of XSRF-TOKEN is 30 minutes.
● If the XSRF-TOKEN does not expire, it can be reused. If the XSRF-TOKEN has
expired, the login API needs to be called again to obtain a new XSRF-TOKEN.
● After this API is called to log in to the system, XSRF-TOKEN is returned in the
response header.

SmartPVMS
● A new token is generated each time this API is called, and the previously
obtained token becomes invalid.
Request URL
https://Domain name of the management system/thirdData/login
Request Mode
HTTP method: POST
Access Restrictions
If an API account enters incorrect passwords for five consecutive times within 10
minutes, the API account will be locked out for 30 minutes.
Maximum number of API calls for each API account: five times every 10 minutes.
If the access frequency exceeds the limit, the API returns error code 407.
Request Parameters
Parameter Description Data Type Mandatory/
Optional
userName API account name String Mandatory
systemCode Password String Mandatory
Response Packet
Parameter Description Data Remark
Type s
success Request success or failure Boolean Request

flag success
true: The request succeeded. or
failure
false: The request failed. flag
failCode Error code Integer -

Value 0 indicates that the
status is normal. For other
error codes, see 6.1 Error
Code List.
param Parameters - - -
s
currentTime Current system time, in Long -
milliseconds

SmartPVMS

Type s
message Optional message String If the

login is
successf
ul, the
docume
nt link
of the
current
version
is
returned
.
data Returned data Object -
Example
Request example:
{
"userName":"*******",
"systemCode":"*******"
}
Response example:
Example 1: successful login
{
"success":true,
"data":null,
"failCode":0,
"params":null,
"message":null
}
Example 2: failed login

{
"data":null,
"failCode":20001,
"message":"",
"params":{
"currentTime":1593777870514
},
"success":false
}

SmartPVMS
NOTICE
The header of the login success response contains the XSRF-TOKEN that must be
retained. In subsequent data API requests, this parameter and its value must be
added to the request header and sent to the management system.
Login example:
The following are examples of the XSRF-TOKEN returned after a successful login.
You can obtain the XSRF-TOKEN using either of the following methods. The first
one is recommended.
The following is an example compatible with earlier versions.
The following figure shows an example of the XSRF-TOKEN carried in the request
header of the data API.

SmartPVMS
3.2.2.2 Logout API
API Description
If you want the XSRF-TOKEN to expire immediately, you can call this API.
Request URL
https://Domain name of the management system/thirdData/logout
Request Mode
HTTP method: POST
Access Restrictions
Maximum number of API calls for each API account: five times every 10 minutes.
You are advised to call this API only when necessary.
If the access frequency exceeds the limit, the API returns error code 407.

SmartPVMS
Request Parameters
Parameter Description Data Mandato
Type ry/
Optional
xsrfToken XSRF-TOKEN returned in the response String Mandato

header after a successful login through ry
the login API.
Response Packet
Type s

flag success
failure

Code List.
s
milliseconds
message Optional message String -
data Returned data Object -
Example
Request example:
{
"xsrfToken":"x-
apepjy1fpd2ptete1f7zuqimep7wuqen9hkb3xaourelbyrx9jio7s09hgk6ca2mdlksjdglasdhjaklsdfhhdsahwedyuio
qwehjkd"
}
Response example:
Example 1: successful logout
{
"success":true,
"data":null,
"failCode":0,
"params":{

SmartPVMS
},
"message":null
}
Example 2: failed logout

{
"data":null,
"success":false,
"failCode":20004,
"params":{
},
"message":null
}
NOTE
Logout example:
3.2.3 Calling an API

API Access
https://Domain name of the management system/specific API name+access
request parameters
Access Process
Log in to the API on the third-party system and obtain the xsrf-token used for
identity authentication. The xsrf-token must be carried when specific data is
accessed. The third-party app calls APIs to access the specific data as required in
the following process.

SmartPVMS
Access Example
Step 1 Create an API account on the management system and bind the account to a PV
plant. For details, see 3.2.1 Obtaining an Account.
Step 2 Obtain the login credential xsrf-token by referring to 3.2.2.1 Login API. The xsrf-
token can be reused if it is valid. For details about the validity period of the xsrf-
token, see API Description.
Step 3 Content-Type: application/json
Enter the login credential xsrf-token in the request header to access the
corresponding API to obtain data.

SmartPVMS
----End

SmartPVMS
NBI Reference 4 Flow Control Description
4 Flow Control Description
The system provides the API flow control mechanism to prevent system
performance deterioration caused by improper API invoking. If the maximum flow
volume is exceeded, this API cannot be called and the error code 407 is returned.
NOTICE
The flow control mechanism may be modified with the system evolution in the
future without notice. Obtain the latest API document to view the API flow control
mechanism.
When the API flow is limited, the system displays the reason for the flow control
through the error code (failCode). Wait until the API returns a normal response
and call the API again.
● Error code 407: The number of API calls of a single user exceeds the upper
limit. For details about the limits on API calls, see "Access Restrictions" in the
corresponding API description. When this error code is returned by an API,
lower your frequency of calls to this API until the frequency drops to the
allowed range.
● Error code 403/429: When a large number of users initiate calls to the same
API, the total number of calls to the API exceeds the upper limit at the system
level. If this error message is received, wait for 1 minute and try again. If the
error persists, wait for a longer time and try again. You can also minimize the
number of calls.
Northbound open APIs support the following access modes. For details about flow
control in OAuth Connect mode, see 4.1 Flow Control Policy in OAuth Connect
Mode. For details about flow control using an API account, see 4.2 Flow Control
Using the API Account.
4.1 Flow Control Policy in OAuth Connect Mode

The API flow control is accumulated based on the API category. Call APIs properly
based on the flow control description.

SmartPVMS
API Flow Control Description

Categor
y
Basic 1000 times/day/owner. The number of flow control times is counted

APIs independently for each owner.
Example:
● If an owner authorizes a third-party app, the third-party app can
access the owner's resources through the API for up to 1000 times
a day.
● If 100 owners authorize a third-party app, the third-party app can
access the resources of each owner through the API for up to 1000
times a day.
Control 100 times/day/owner. The number of flow control times is counted

APIs independently for each owner.
Example:
● If an owner authorizes a third-party app, the third-party app can
access the owner's resources through the API for up to 100 times
a day.
● If 100 owners authorize a third-party app, the third-party app can
access the resources of each owner through the API for up to 100
times a day.
4.2 Flow Control Using the API Account

The following table describes the flow control of unrestricted northbound APIs.
Call APIs properly based on the flow control description.
API API API Name Flow Control Description

Cat Label
ego
ry
Bas Basic Plant list Maximum number of API calls for each API
ic data account per day = Roundup (Number of plants/
API 100) x 10 + 24
s Example:
● If an API account manages 20 plants, the
maximum number of API calls per day =
Roundup (20/100) x 10 + 24 = 1 x 10 + 24 = 34.
Roundup (120/100) x 10 + 24 = 2 x 10 + 24 =
44.

SmartPVMS

Cat Label
ego
ry
Device list Flow control is performed based on the number of

plants managed by API accounts. Maximum
number of API calls for each API account per day =
Roundup (Number of plants/100) + 24
Example:
Roundup (20/100) + 24 = 1 + 24 = 25.
Roundup (120/100) + 24 = 2 + 24 = 26.
Moni Real-time Flow control is performed based on the number of

torin plant data plants managed by API accounts. Maximum
g number of API calls for each API account every 5
data minutes = Roundup (Number of plants/100)
Example:
● If an API account manages 20 plants: Maximum
number of API calls every 5 minutes = Roundup
(20/100) = 1
● If an API account manages 120 plants:
Maximum number of API calls for each API
account every five minutes = Roundup
(120/100) = 2

SmartPVMS

Cat Label
ego
ry
Real-time Flow control is performed based on the number of

device data devices of each type managed by an API account.
account every 5 minutes = ∑ Roundup (Number of
devices of each type/100).
Example:
● If an API account manages 20 inverters and 20
meters, the maximum number of API calls every
5 minutes is calculated as follows:
Inverters: Roundup (20/100) = 1
Meters: Roundup (20/100) = 1
Total: Maximum number of API calls for
inverters + Maximum number of API calls for
meters = 1 + 1 = 2
● If an API account manages 120 inverters and
120 meters, the maximum number of API calls
every 5 minutes is calculated as follows:
meters = 2 + 2 = 4

SmartPVMS

Cat Label
ego
ry
Historical Flow control is performed based on the number of

account per day = ∑ Roundup (Number of devices
of each type/10) + 24.
Example:
meters, the maximum number of API calls per
day is calculated as follows:
meters = 2 + 2 + 24 = 28
per day is calculated as follows:
meters = 12 + 12 + 24 = 48

SmartPVMS

Cat Label
ego
ry
Alar Querying Flow control is performed based on the number of

m active plants managed by API accounts and the number
data alarms of devices of each type.
account every 30 minutes = MAX (Roundup
(Number of plants/100), ∑ Roundup (Number of
devices of each type/100))
Example:
● If an API account manages 20 plants, 20
inverters, and 20 meters, the maximum number
of API calls every 30 minutes is calculated as
follows:
Roundup (Number of plants/100) = Roundup
(20/100) = 1
∑ Roundup (Number of devices of each type/100)
= Number of inverters + Number of meters =
Roundup (20/100) + Roundup (20/100) = 1 + 1 = 2
Total: MAX (1,2) = 2
● If an API account manages 120 plants, 120
inverters, and 120 meters, the maximum
number of API calls every 30 minutes is
calculated as follows:
Roundup (Number of plants/100) = Roundup
(120/100) = 2
∑Roundup (Number of devices of each type/100) =
Number of inverters + Number of meters =
Roundup (120/100) + Roundup (120/100) = 2 + 2
=4
Total: MAX (2,4) = 4
Repo Hourly plant Flow control is performed based on the number of

rt data plants managed by API accounts. Maximum
data number of API calls for each API account per day =
Example:
Roundup (20/100) + 24 = 1 + 24 = 25.
Roundup (120/100) + 24 = 2 + 24 = 26.

SmartPVMS

Cat Label
ego
ry
Daily plant Flow control is performed based on the number of

data plants managed by API accounts. Maximum
Example:
Roundup (20/100) + 24 = 1 + 24 = 25.
Roundup (120/100) + 24 = 2 + 24 = 26.
Monthly Flow control is performed based on the number of

plant data plants managed by API accounts. Maximum
Example:
Roundup (20/100) + 24 = 1 + 24 = 25.
Roundup (120/100) + 24 = 2 + 24 = 26.
Yearly plant Flow control is performed based on the number of

data plants managed by API accounts. Maximum
Example:
Roundup (20/100) + 24 = 1 + 24 = 25.
Roundup (120/100) + 24 = 2 + 24 = 26.

SmartPVMS

Cat Label
ego
ry
Daily device Flow control is performed based on the number of

data devices of each type managed by an API account.
Example:
meters = 1 + 1 + 24 = 26
meters = 2 + 2 + 24 = 28

SmartPVMS

Cat Label
ego
ry
Monthly Flow control is performed based on the number of

Example:
meters = 1 + 1 + 24 = 26
meters = 2 + 2 + 24 = 28

SmartPVMS

Cat Label
ego
ry
Yearly Flow control is performed based on the number of

Example:
meters = 1 + 1 + 24 = 26
meters = 2 + 2 + 24 = 28
Con Batte Delivering Call the API only when necessary to reduce the
trol ry battery access frequency.
API confi charge/ For the same plant, do not call this API repeatedly
s gurat discharge before a task is complete.
ion tasks
account: once per minute.
Querying Call the API only when necessary to reduce the

battery access frequency.
charge/ For the same plant, do not call this API repeatedly
discharge before a task is complete.
tasks
Invert API for Call the API only when necessary to reduce the
er delivering access frequency.
activ an inverter For the same plant, do not call this API repeatedly
e active power before a task is complete.
powe setting task
r Maximum number of API calls for each API
contr account: once per minute.
ol

SmartPVMS

Cat Label
ego
ry
API for Call the API only when necessary to reduce the
querying an access frequency.
inverter For the same plant, do not call this API repeatedly
active power before a task is complete.
setting task
Settin API for Call the API only when necessary to reduce the
g the Delivering a access frequency.
batte Task for For the same plant, do not call this API repeatedly
ry Setting the before a task is complete.
worki Battery
ng Working Maximum number of API calls for each API
mode Mode account: once per minute.
Querying a access frequency.
Task for For the same plant, do not call this API repeatedly
Setting the before a task is complete.
Battery
Working Maximum number of API calls for each API
Mode account: once per minute.
Batte API for Call the API only when necessary to reduce the
ry Delivering a access frequency.
para Task for For the same plant, do not call this API repeatedly
mete Setting before a task is complete.
r Battery
settin Parameters Maximum number of API calls for each API
g account: once per minute.
Querying a access frequency.
Task for For the same plant, do not call this API repeatedly
Setting before a task is complete.
Battery
Parameters Maximum number of API calls for each API

SmartPVMS
NBI Reference 5 API Reference
5 API Reference
5.1 Basic APIs

Allow you to obtain the real-time monitoring, report, and alarm data of plants
and devices for system monitoring, O&M, and data analysis.
5.1.1 Basic
5.1.1.1 Plant List API
API Description
This API is used to query the plant list. When the pagination parameters (a
maximum of 100 records can be displayed on each page) and grid connection
time are transferred (if only the grid connection start time is transferred, the grid
connection end time is the current time by default; if only the grid connection end
time is transferred, the default grid connection start time is 1970-01-01 08:00:00),
the plant list is queried in pages based on the grid connection time. When only
the pagination parameter is transferred, the plant list is queried in pages.
CAUTION
If no data is queried or only some data is returned when the plant list API is used,
rectify the fault by referring to 8.3 Why Is No Data or Only Part of Data Found
When I Call a Northbound API for Data Query?
If the returned plant ID is inconsistent with that displayed on the SmartPVMS,
rectify the fault by referring to 8.8 Why Is the Plant ID Returned by the Plant
List Inconsistent with That Displayed on the SmartPVMS?
If the plant IDs returned vary depending on open API users, rectify the fault by
referring to 8.9 Why Do the Plant IDs Returned for the Same Plant Vary
Depending on Open API Users?

SmartPVMS
Request URL
https://Domain name of the management system/thirdData/stations
Request Mode
HTTP method: POST
Request Parameters
Type ry/
Optional
pageNo Page No. of the results Integer Mandato

ry
gridConnect Grid connection start time (ms) Long Optional

edStartTime
gridConnect Grid connection end time (ms) Long Optional

edEndTime
Response Packet
Parameter Description Data Remarks
Type
success Request success or failure Boolean Request success or

flag failure flag
true: The request
succeeded.
false: The request failed.

Code List.
message Optional response - -

message
data Returned data, which Map -

contains the following
information:
> total Total number of results Long -
> pageCount Total number of pages Long -
> pageNo Page No. of the results Integer -

SmartPVMS
Parameter Description Data Remarks

Type
> pageSize Number of query results Integer -

displayed on each page
> list Plant information list. The List Plant information

plant information is as
follows:
>> plantCode Plant ID, which uniquely String -

identifies a plant.
>> plantName Plant name String -
>> plantAddress Detailed address of the String -

plant
>> longitude Plant longitude Double -
>> latitude Plant latitude Double -
>> capacity Total string capacity Double kWp
>> contactPerson Plant contact String -
>> Contact information of String -

contactMethod the plant contact, such as
the mobile phone number
or email address
>> Grid connection time of String 2020-02-06T00:00:0

gridConnectionD the plant, including the 0+08:00
ate time zone
Examples
Request example:
{
"pageNo": 1,
"gridConnectedStartTime":1664718569000,
"gridConnectedEndTime":1667396969000
}
Response examples:
{
"success": false,
"data": null,
"failCode": 20605,
"message": "The time cannot be a negative number."
}
Example 2: The plant list data is returned.

{
"success": true,

SmartPVMS
"data": {
"list": [
{
"plantName": "NMplant1",
"longitude": null,
"latitude": null,
"capacity": 146.5,
"gridConnectionDate": "2022-11-21T16:23:00+08:00"
},
{
"plantName": "plant2",
"longitude": null,
"latitude": null,
"capacity": 123.3,
"gridConnectionDate": "2022-11-21T16:30:28-12:00"
}
],
"pageCount": 1,
"pageNo": 1,
"pageSize": 100,
"total": 2
},
"failCode": 0,
"message": "get plant list success"
}
5.1.1.2 Device List API
API Description
This API is used to obtain basic device information. Before invoking other APIs to
obtain device data, you need to call this API to obtain the device ID.
When you query devices by plant ID set, devices of a maximum of 100 plants can
be queried at a time.
CAUTION
If no data is queried or only some data is returned when the device list API is
used, rectify the fault by referring to 8.3 Why Is No Data or Only Part of Data
Found When I Call a Northbound API for Data Query?
Request URL
https://Domain name of the management system/thirdData/getDevList
Request Mode
HTTP method: POST

SmartPVMS
Request Parameters
Type ry/
Optional
stationCode Plant ID list. Multiple plant IDs are String Mandato

s separated by commas (,). The plant IDs ry
are obtained from plantCode in 5.1.1.1
Plant List API.
Response Packet
Type s

flag success
true: The request or
succeeded. failure
flag

status is normal. For
definitions of other error
codes, see 6.1 Error Code
List.
s
stationCodes Plant ID list in the request String -
parameter

milliseconds
data Parameters Returned data. The data List -

contains the object
parameter list of each
device.
id Device ID Long -
devDn Unique device ID in the String

system
devName Device name String -
stationCode Plant ID String -

SmartPVMS

Type s
esnCode Device SN String -
devTypeId Device type ID Integer -

The following device types
are supported:
1: string inverter
2: SmartLogger
8: STS
10: EMI
13: protocol converter
16: general device
17: grid meter
22: PID
37: Pinnet data logger
38: residential inverter
39: battery
40: backup box
41: ESS
45: PLC
46: optimizer
47: power sensor
62: Dongle
63: distributed SmartLogger
70: safety box
60001: mains
60003: genset
60043: SSU group
60044: SSU
60092: power converter
60014: lithium battery rack
60010: AC output power
distribution
23070: EMMA
softwareVersion Software version String -
optimizerNumber Quantity of optimizers Integer
invType Inverter model (only String -

applicable to inverters)
longitude Longitude Double -

SmartPVMS

Type s
latitude Latitude Double -
Examples
Request example:
{
"stationCodes":"BA4372D08E014822AB065017416F254C,5D02E8B40AD342159AC8D8A2BCD4FAB5"
}
Response examples:

{
"success":false,
"data":null,
"failCode":20009,
"params":{
"stationCodes":"BA4372D08E014822AB065017416F254C,5D02E8B40AD342159AC8D8A2BCD4FAB5",
},
"message":null
}
Example 2: The device list is returned.

{
"success":true,
"data":[
{
"id":-214543629611879,
"devDn":"NE=45112560",
"devName":"5fbfk4",
"stationCode":"5D02E8B40AD342159AC8D8A2BCD4FAB5",
"esnCode":"5fbfk4",
"devTypeId":1,
"softwareVersion":"V100R001PC666",
"invType":"SUN2000-17KTL",
"longitude":null,
"latitude":null
},
{
"id":-214091680973855,
"devDn":"NE=4511256",
"devName":"6fbfk11",
"esnCode":"6fbfk11",
"devTypeId":1,
"softwareVersion":"V100R001PC666",
"invType":"SUN2000-17KTL",
"longitude":null,
"latitude":null
}
],
"failCode":0,
"params":{
},
"message":null
}

SmartPVMS
NOTE
Prerequisites for obtaining data: The API account has the permission to access this API.
Request example:
5.1.2 Monitoring
5.1.2.1 Real-Time Plant Data API
API Description
This API is used to obtain real-time plant data by plant ID set. Data of a maximum
of 100 plants can be queried at a time.
For details about the data list that can be queried through this API, see the real-
time plant data list below.
Request URL
https://Domain name of the management system/thirdData/getStationRealKpi
Request Mode
HTTP method: POST

SmartPVMS
Request Parameters
Type ry/
Optional

Plant List API.
Response Packet
Parameter Description Type Remark
s

flag success
failure

Code List.
s
parameter

milliseconds

contains the real-time data
object list of each plant.
dataItemMap Content of each data item, Map -

which is returned in the key-
value format. For details
about the data item list, see
the real-time plant data list
below.
Real-Time Plant Data List

SmartPVMS
Key Name Unit Return

Value
Type
day_power Yield today kWh Double
month_power Yield this month kWh Double
total_power Total yield kWh Double
day_income Revenue today The currency Double

specified in the
management
system
total_income Total revenue The currency Double

specified in the
management
system
real_health_state Plant health status None Integer

The following plant
health states are
supported:
1: disconnected
2: faulty
3: healthy
Example
Request example:
{
"stationCodes":"BA4372D08E014822AB065017416F254C,5D02E8B40AD342159AC8D8A2BCD4FAB5"
}
Response example:
{
"success":false,
"data":null,
"failCode":20009,
"params":{
},
"message":null
}
Example 2: Real-time plant data is returned.

{
"success":true,
"data":[
{
"dataItemMap":{

SmartPVMS
"real_health_state":"3",
"day_power":"10000",
"total_power":"900.000",
"day_income":"0.000",
"month_power":"900.000",
"total_income":"2088.000"
},
"stationCode":"BA4372D08E014822AB065017416F254C"
},
{
"dataItemMap":{
"real_health_state":"1",
"day_power":"16770.000",
"total_power":"35100.000",
"day_income":"26832.000",
"month_power":"35100.000",
"total_income":"61152.000"
},
"stationCode":"5D02E8B40AD342159AC8D8A2BCD4FAB5"
}
],
"failCode":0,
"params":{
},
"message":null
}
NOTE
Request example:

SmartPVMS
5.1.2.2 Real-Time Device Data API
API Description
This API is used to obtain real-time device data by device type and device ID set.
The data varies depending on device types. Data of a maximum of 100 devices of
the same type can be queried at a time.
For details about the data list that can be queried through this API, see the real-
time device data list below.
Request URL
https://Domain name of the management system/thirdData/getDevRealKpi
Request Mode
HTTP method: POST
Request Parameters
Type ry/
Optional
devIds List of device IDs. The device IDs are String Optional
obtained from id in 5.1.1.2 Device List
API. Use commas (,) to separate multiple
device IDs. Either sns or devIds must be
set.
sns Device SN list. Multiple device SNs are String Optional

separated by commas (,). Either sns or
devIds must be set.

SmartPVMS

Type ry/
Optional
devTypeId Device type ID. The values of devTypeId Integer Mandato

obtained in 5.1.1.2 Device List API are ry
used.
The following device types are supported:
1: string inverter
10: EMI
17: grid meter
39: battery
41: ESS
47: power sensor
60001: mains
60003: genset
60043: SSU group
60044: SSU
60010: AC output power distribution
Response Packet
Type s

flag success
failure

Code List.
s
devIds Device ID list in the request String -
parameter
sns Device SN list in the request String -

parameter

SmartPVMS

Type s
devTypeId Device type ID in the Integer -

request parameter

milliseconds

contains the real-time data
object list of each device.
devId Device ID Long -
sn Device SN String
dataItemMap Content of data items, Map Real-

which are returned in the time
key-value format. Content device
of each data item, which is data
returned in the key-value
format. The data item
content varies depending on
the device type. For details
the real-time device data
list below.
Real-Time Device Data List
Device Type Key Name Unit Ret Remarks

urn
Val
ue
Typ
e
ID: 1 inverter_state Inverter state. None Do

String For details, see ubl
inverter Table 5-1. e
ab_u A-B line voltage V Do

of grid ubl
e
bc_u B-C line voltage V Do

of grid ubl
e

SmartPVMS

urn
Val
ue
Typ
e
ca_u C-A line voltage V Do

of grid ubl
e
a_u Phase A voltage V Do

ubl
e
b_u Phase B voltage V Do

ubl
e
c_u Phase C voltage V Do

ubl
e
a_i Phase A current A Do

of grid ubl
e
b_i Phase B current A Do

of grid ubl
e
c_i Phase C current A Do

of grid ubl
e
efficiency Inverter % Do
conversion ubl
efficiency e
(manufacturer)
temperature Internal °C Do
temperature ubl
e
power_factor Power factor None Do

ubl
e
elec_freq Grid frequency Hz Do

ubl
e
active_power Active power kW Do

ubl
e

SmartPVMS

urn
Val
ue
Typ
e
reactive_power Output reactive kVar Do

power ubl
e
day_cap Yield today kWh Do

ubl
e
mppt_power MPPT total input kW Do

power ubl
e
pv1_u PV1 input V Do

voltage ubl
e

voltage ubl
e

voltage ubl
e

voltage ubl
e

voltage ubl
e

voltage ubl
e

voltage ubl
e

voltage ubl
e

voltage ubl
e

SmartPVMS

urn
Val
ue
Typ
e

voltage ubl
e

voltage ubl
e

voltage ubl
e

voltage ubl
e

voltage ubl
e

voltage ubl
e

voltage ubl
e

voltage ubl
e

voltage ubl
e

voltage ubl
e

voltage ubl
e

voltage ubl
e

SmartPVMS

urn
Val
ue
Typ
e

voltage ubl
e

voltage ubl
e

voltage ubl
e

voltage ubl
e

voltage ubl
e

voltage ubl
e

voltage ubl
e
pv1_i PV1 input A Do

current ubl
e

current ubl
e

current ubl
e

current ubl
e

current ubl
e

SmartPVMS

urn
Val
ue
Typ
e

current ubl
e

current ubl
e

current ubl
e

current ubl
e

current ubl
e

current ubl
e

current ubl
e

current ubl
e

current ubl
e

current ubl
e

current ubl
e

current ubl
e

SmartPVMS

urn
Val
ue
Typ
e

current ubl
e

current ubl
e

current ubl
e

current ubl
e

current ubl
e

current ubl
e

current ubl
e

current ubl
e

current ubl
e

current ubl
e

current ubl
e
total_cap Total yield kWh Do

ubl
e

SmartPVMS

urn
Val
ue
Typ
e
open_time Inverter startup ms Do

time ubl
e
close_time Inverter ms Do
shutdown time ubl
e
mppt_total_cap Total DC input kWh Do

energy ubl
e
mppt_1_cap MPPT 1 DC total kWh Do

yield ubl
e

yield ubl
e

yield ubl
e

yield ubl
e

yield ubl
e

yield ubl
e

yield ubl
e

yield ubl
e

yield ubl
e

SmartPVMS

urn
Val
ue
Typ
e
mppt_10_cap MPPT 10 DC kWh Do

total yield ubl
e
run_state State (0: None Lon

Disconnected 1: g
Connected)

Residential For details, see ubl

of grid ubl
e

of grid ubl
e

of grid ubl
e

ubl
e

ubl
e

ubl
e

of grid ubl
e

of grid ubl
e

of grid ubl
e

SmartPVMS

urn
Val
ue
Typ
e
conversion ubl
efficiency e
(manufacturer)
temperature ubl
e

ubl
e

ubl
e

ubl
e

power ubl
e

ubl
e

power ubl
e

voltage ubl
e

voltage ubl
e

voltage ubl
e

voltage ubl
e

SmartPVMS

urn
Val
ue
Typ
e

voltage ubl
e

voltage ubl
e

voltage ubl
e

voltage ubl
e

current ubl
e

current ubl
e

current ubl
e

current ubl
e

current ubl
e

current ubl
e

current ubl
e

current ubl
e

SmartPVMS

urn
Val
ue
Typ
e

ubl
e

time ubl
e
shutdown time ubl
e

yield ubl
e

yield ubl
e

yield ubl
e

yield ubl
e

Disconnected 1: g
Connected)
ID: 10 temperature Temperature °C Do

Environment ubl
al e
monitoring pv_temperature PV temperature °C Do
instrument ubl
(EMI) e
wind_speed Wind speed m/s Do

ubl
e
wind_direction Wind direction Degree Do

ubl
e

SmartPVMS

urn
Val
ue
Typ
e
radiant_total Daily irradiation MJ/m2 Do

ubl
e
radiant_line Irradiance W/m2 Do

ubl
e
horiz_radiant_lin Horizontal W/m2 Do Invalid

e irradiance ubl field. The
e default
value is
null.
horiz_radiant_tot Horizontal MJ/m2 Do Invalid

al irradiation ubl field. The
e default
value is
null.

Disconnected 1: g
Connected)
ID: 17 ab_u A-B line voltage V Do

Grid meter of grid ubl
e

of grid ubl
e

of grid ubl
e

(AC output) ubl
e

(AC output) ubl
e

(AC output) ubl
e

SmartPVMS

urn
Val
ue
Typ
e

of grid (IA) ubl
e

of grid (IB) ubl
e

of grid (IC) ubl
e

ubl
e

ubl
e
active_cap Active energy kWh Do

(positive active ubl
energy) e
reactive_power Reactive power kVar Do

ubl
e
reverse_active_c Negative active kWh Do

ap energy ubl
e
forward_reactive Positive reactive kWh Do

_cap energy ubl
e
reverse_reactive_ Negative reactive kWh Do

cap energy ubl
e
active_power_a Active power PA kW Do

ubl
e
active_power_b Active power PB kW Do

ubl
e

SmartPVMS

urn
Val
ue
Typ
e
active_power_c Active power PC kW Do

ubl
e
reactive_power_ Reactive power kVar Do Invalid

a QA ubl field. The
e default
value is
null.

b QB ubl field. The
e default
value is
null.

c QC ubl field. The
e default
value is
null.
total_apparent_p Total apparent kVA Do

ower power ubl
e
grid_frequency Grid frequency Hz Do Invalid

ubl field. The
e default
value is
null.
reverse_active_p Negative active kWh Do Invalid

eak energy (peak) ubl field. The
e default
value is
null.

ower energy ubl field. The
(shoulder) e default
value is
null.

SmartPVMS

urn
Val
ue
Typ
e
reverse_active_v Negative active kWh Do Invalid

alley energy (off- ubl field. The
peak) e default
value is
null.
reverse_active_t Negative active kWh Do Invalid

op energy (sharp) ubl field. The
e default
value is
null.
positive_active_p Positive active kWh Do Invalid

e default
value is
null.

value is
null.
positive_active_v Positive active kWh Do Invalid

peak) e default
value is
null.
positive_active_t Positive active kWh Do Invalid

e default
value is
null.
reverse_reactive_ Negative reactive kVar Do Invalid

peak energy (peak) ubl field. The
e default
value is
null.

power energy ubl field. The
value is
null.

SmartPVMS

urn
Val
ue
Typ
e

valley energy (off- ubl field. The
peak) e default
value is
null.

top energy (sharp) ubl field. The
e default
value is
null.
positive_reactive Positive reactive kVar Do Invalid

_peak energy (peak) ubl field. The
e default
value is
null.

_power energy ubl field. The
value is
null.

_valley energy (off- ubl field. The
peak) e default
value is
null.

_top energy (sharp) ubl field. The
e default
value is
null.
ID: 47 meter_status Meter state (0: None Do

Power offline; 1: ubl
sensor normal) e
meter_u Phase A voltage V Do

(AC output) ubl
e
meter_i Phase A current A Do

of grid (IA) ubl
e

SmartPVMS

urn
Val
ue
Typ
e
active_power Active power W Do

ubl
e
reactive_power Reactive power Var Do

ubl
e

ubl
e
grid_frequency Grid frequency Hz Do

ubl
e

energy) e

ap energy ubl
e

Disconnected 1: g
Connected)

of grid ubl
e

of grid ubl
e

of grid ubl
e

(AC output) ubl
e

(AC output) ubl
e

SmartPVMS

urn
Val
ue
Typ
e

of grid (IB) ubl
e

of grid (IC) ubl
e
forward_reactive Positive reactive kWh Do Invalid

_cap energy ubl field. The
e default
value is
null.
reverse_reactive_ Negative reactive kWh Do Invalid

cap energy ubl field. The
e default
value is
null.

ubl
e

ubl
e

ubl
e

a QA ubl field. The
e default
value is
null.

b QB ubl field. The
e default
value is
null.

SmartPVMS

urn
Val
ue
Typ
e

c QC ubl field. The
e default
value is
null.
total_apparent_p Total apparent kVA Do Invalid

ower power ubl field. The
e default
value is
null.

e default
value is
null.

value is
null.

peak) e default
value is
null.

e default
value is
null.

e default
value is
null.

value is
null.

SmartPVMS

urn
Val
ue
Typ
e

peak) e default
value is
null.

e default
value is
null.

e default
value is
null.

value is
null.

peak) e default
value is
null.

e default
value is
null.

e default
value is
null.

value is
null.

SmartPVMS

urn
Val
ue
Typ
e

peak) e default
value is
null.

e default
value is
null.
ID: 39 battery_status Battery running None Do

Residential state (0: offline; ubl
battery 1: standby; 2: e
running; 3:
faulty; 4:
hibernating)
max_charge_po Maximum W Do
wer charge power ubl
e
max_discharge_ Maximum W Do
power discharge power ubl
e
ch_discharge_po Charge/ W Do
wer Discharge power ubl
e
busbar_u Battery voltage V Do

ubl
e
battery_soc Battery SOC % Do

ubl
e
battery_soh Battery SOH None Do

(supported only ubl
by LG batteries) e

SmartPVMS

urn
Val
ue
Typ
e
ch_discharge_m Charge/ None Do

odel Discharge mode ubl
(0: none; 1: e
forced charge/
discharge; 2:
time-of-use
price; 3: fixed
charge/
discharge; 4:
automatic
charge/
discharge; 5:
fully fed to grid;
6: TOU; 7:
remote
scheduling–max.
self-
consumption; 8:
remote
scheduling–fully
fed to grid; 9:
remote
scheduling–TOU;
10: EMMA)
charge_cap Charged energy kWh Do

ubl
e
discharge_cap Discharged kWh Do

energy ubl
e

Disconnected 1: g
Connected)
ID: 41 ch_discharge_po Charge/ W Do

C&I and wer Discharge power ubl
utility ESS e

ubl
e

SmartPVMS

urn
Val
ue
Typ
e

ubl
e

ubl
e

energy ubl
e

Disconnected 1: g
Connected)
ID: 60001 mains_state Mains status (0: None Do

Mains mains ubl
(supported unavailable; 1: e
only in the mains available)
Power-M ac_voltage AC voltage V Do
scenario) ubl
e
ac_current AC current A Do
ubl
e

ubl
e
ac_frequency AC frequency Hz Do
ubl
e
grid_quality_gra Power grid None Do

de quality level (0: ubl
Unknown; 1: e
Class 1; 2: Class
2; 3: Class 3; 4:
Class 4)
total_energy_co Total energy kWh Do

nsumption consumption ubl
e

SmartPVMS

urn
Val
ue
Typ
e
supply_duration_ Total power h Do

per_total supply duration ubl
e
ID: 60003 running_state Running status None Do

Genset (0: unknown; 1: ubl
(supported stopped; 2: e
only in the running)
Power-M output_power Output power kW Do
scenario) ubl
e
load_rate Load rate % Do

ubl
e
ID: 60043 total_output_cur Total output A Do

SSU group rent current ubl
(supported e
only in the total_output_po Total output kW Do
Power-M wer power ubl
scenario) e
D: 60044 input_voltage Input voltage V Do

SSU ubl
(supported e
only in the output_voltage Output voltage V Do
Power-M ubl
scenario) e
output_current Output current A Do

ubl
e
on_off_state Power-on/off None Do

status (0: on; 1: ubl
off) e
ID: 60092 total_runtime Total runtime h Do

Power ubl
converter e
(supported
pv_input_voltage PV input voltage V Do
only in the
ubl
Power-M
e
scenario)

SmartPVMS

urn
Val
ue
Typ
e
pv_input_current PV input current A Do

ubl
e
pv_input_power PV input power kW Do

ubl
e
inverter_voltage Inverter voltage V Do

ubl
e
inverter_frequen Inverter Hz Do
cy frequency ubl
e
ac_output_volta AC output V Do
ge voltage ubl
e
ac_output_curre AC output A Do
nt current ubl
e
ac_output_frequ AC output kW Do
ency frequency ubl
e
ac_output_appar AC output kVA Do

ent_power apparent power ubl
e
ID: 60014 battery_state Battery status (0: None Do

Lithium initial power-on; ubl
battery rack 1: power-off; 2: e
(supported float charging; 3:
only in the boost charging;
Power-M 4: discharging; 5:
scenario) charging; 6:
testing; 7:
hibernation; 8:
standby)
soc SOC % Do
ubl
e

SmartPVMS

urn
Val
ue
Typ
e
charge_discharg Charge/ kW Do
e_power Discharge power ubl
e
total_discharge Total energy kWh Do

discharged ubl
e
voltage Voltage V Do
ubl
e
current Current A Do
ubl
e
remaining_back Remaining h Do
up_time power reserve ubl
duration e
total_discharge_ Total discharge times Do

times times ubl
e
total_capacity Total capacity kWh Do

ubl
e
ID: 60010 ac_voltage AC voltage V Do

AC output ubl
power e
distribution ac_current AC current A Do
(supported ubl
only in the e
Power-M
scenario) ac_frequency AC frequency Hz Do
ubl
e

ubl
e

SmartPVMS
Table 5-1 Inverter state (inverter_state) description
State Value Description
0 Standby: initializing
1 Standby: insulation resistance detecting
2 Standby: irradiation detecting
3 Standby: grid detecting
256 Start
512 Grid-connected
513 Grid-connected: power limited
514 Grid-connected: self-derating
768 Shutdown: on fault
769 Shutdown: on command
770 Shutdown: OVGR
771 Shutdown: communication interrupted
772 Shutdown: power limited
773 Shutdown: manual startup required
774 Shutdown: DC switch disconnected
1025 Grid scheduling: cosψ-P curve
1026 Grid scheduling: Q-U curve
1280 Ready for terminal test
1281 Terminal testing...
1536 Inspection in progress
1792 AFCI self-check
2048 I-V scanning
2304 DC input detection
40960 Standby: no irradiation
45056 Communication interrupted (written by SmartLogger)
49152 Loading... (written by SmartLogger)
Examples
Request example:

SmartPVMS
{
"devIds":"214060404588862,213472461631079",
"devTypeId":"1"
}

{
"success":false,
"data":null,
"failCode":20006,
"params":{
"devIds":"214233501711677,214060404588862",
"devTypeId":"1",
},
"message":null
}
Example 2: Real-time data of devices is returned.

{
"success":true,
"data":[
{
"dataItemMap":{
"pv7_u":0,
"pv1_u":0,
"b_u":0,
"c_u":0,
"pv6_u":0,
"temperature":0,
"open_time":0,
"b_i":0,
"bc_u":0,
"pv9_u":0,
"pv8_u":0,
"c_i":0,
"mppt_total_cap":0,
"pv9_i":0,
"mppt_3_cap":0,
"run_state":0,
"mppt_2_cap":0,
"inverter_state":0,
"pv8_i":0,
"mppt_1_cap":0,
"pv6_i":0,
"mppt_power":0,
"pv1_i":0,
"total_cap":0,
"ab_u":0,
"pv7_i":0,
"pv13_u":0,
"reactive_power":0,
"pv10_u":0,
"pv12_i":0,
"pv11_i":0,
"pv3_i":0,
"pv11_u":0,
"pv2_i":0,
"pv13_i":0,
"power_factor":0,
"pv12_u":0,
"pv5_i":0,
"active_power":0,
"elec_freq":0,
"pv10_i":0,
"pv4_i":0,
"mppt_4_cap":0,
"mppt_5_cap":0,
"mppt_6_cap":0,

SmartPVMS
"mppt_7_cap":0,
"mppt_8_cap":0,
"mppt_9_cap":0,
"mppt_10_cap":0,
"pv4_u":0,
"close_time":0,
"day_cap":0,
"ca_u":0,
"a_i":0,
"pv5_u":0,
"a_u":0,
"pv3_u":0,
"pv14_u":0,
"pv14_i":0,
"pv15_u":0,
"pv15_i":0,
"pv16_u":0,
"pv16_i":0,
"pv17_u":0,
"pv17_i":0,
"pv18_u":0,
"pv18_i":0,
"pv19_u":0,
"pv19_i":0,
"pv20_u":0,
"pv20_i":0,
"pv21_u":0,
"pv21_i":0,
"pv22_u":0,
"pv22_i":0,
"pv23_u":0,
"pv23_i":0,
"pv24_u":0,
"pv24_i":0,
"pv25_u":0,
"pv25_i":0,
"pv26_u":0,
"pv26_i":0,
"pv27_u":0,
"pv27_i":0,
"pv28_u":0,
"pv28_i":0,
"efficiency":0,
"pv2_u":0
},
"devId":213472461631079
},
{
"dataItemMap":{
"pv7_u":0,
"pv1_u":0,
"b_u":0,
"c_u":0,
"pv6_u":0,
"temperature":0,
"open_time":0,
"b_i":0,
"bc_u":0,
"pv9_u":0,
"pv8_u":0,
"c_i":0,
"mppt_total_cap":0,
"pv9_i":0,
"mppt_3_cap":0,
"run_state":0,
"mppt_2_cap":0,
"inverter_state":0,
"pv8_i":0,
"mppt_1_cap":0,

SmartPVMS
"pv6_i":0,
"mppt_power":0,
"pv1_i":0,
"total_cap":0,
"ab_u":0,
"pv7_i":0,
"pv13_u":0,
"reactive_power":0,
"pv10_u":0,
"pv12_i":0,
"pv11_i":0,
"pv3_i":0,
"pv11_u":0,
"pv2_i":0,
"pv13_i":0,
"power_factor":0,
"pv12_u":0,
"pv5_i":0,
"active_power":0,
"elec_freq":0,
"pv10_i":0,
"pv4_i":0,
"mppt_4_cap":0,
"mppt_5_cap":0,
"mppt_6_cap":0,
"mppt_7_cap":0,
"mppt_8_cap":0,
"mppt_9_cap":0,
"mppt_10_cap":0,
"pv4_u":0,
"close_time":0,
"day_cap":0,
"ca_u":0,
"a_i":0,
"pv5_u":0,
"a_u":0,
"pv3_u":0,
"pv14_u":0,
"pv14_i":0,
"pv15_u":0,
"pv15_i":0,
"pv16_u":0,
"pv16_i":0,
"pv17_u":0,
"pv17_i":0,
"pv18_u":0,
"pv18_i":0,
"pv19_u":0,
"pv19_i":0,
"pv20_u":0,
"pv20_i":0,
"pv21_u":0,
"pv21_i":0,
"pv22_u":0,
"pv22_i":0,
"pv23_u":0,
"pv23_i":0,
"pv24_u":0,
"pv24_i":0,
"pv25_u":0,
"pv25_i":0,
"pv26_u":0,
"pv26_i":0,
"pv27_u":0,
"pv27_i":0,
"pv28_u":0,
"pv28_i":0,
"efficiency":0,
"pv2_u":0

SmartPVMS
},
"devId":214060404588862
}
],
"failCode":0,
"params":{
"devIds":"214060404588862,213472461631079",
"devTypeId":"1",
},
"message":null
}
NOTE
Request example:
5.1.2.3 Historical Device Data API
API Description
This API is used to obtain 5-minute device data in a specified time period. The 5-
minute data of a maximum of 10 devices of the same type in three days can be
queried at a time.
For details about the data list that can be queried through this API, see the
historical device data list below.
Request URL
https://Domain name of the management system/thirdData/getDevHistoryKpi

SmartPVMS
Request Mode
HTTP method: POST
Request Parameters
Type ry/
Optional
set.

devIds must be set.
devTypeId Device type ID. Use the device type ID Integer Mandato
obtained in 5.1.1.2 Device List API. ry
1: string inverter
10: EMI
17: grid meter
39: battery
41: ESS
47: power sensor
60001: mains
60003: genset
60043: SSU group
startTime Start time, in milliseconds Long Mandato

ry
endTime End time, in milliseconds Long Mandato

ry

SmartPVMS
Response Packet
Type s

flag success
failure

Code List.
s
parameter

parameter

request parameter
startTime Start time, in milliseconds Long -
endTime End time, in milliseconds Long -

milliseconds
data Parameters Returned data. The data List 5-

contains the 5-minute data minute
object list of each device. data of
a device
in a day
sn Device SN String
collectTime Collection time in Long -

milliseconds in the request
parameter

SmartPVMS

Type s
dataItemMap Content of each data item, Map 5-

which is returned in the key- minute
value format. The data item device
content varies depending on data
the historical device data list
below.
Historical Device Data List

urn
Val
ue
Typ
e

String For details, see ubl
inverter the following: e
Table 5-2

of grid ubl
e

of grid ubl
e

of grid ubl
e

ubl
e

ubl
e

ubl
e

SmartPVMS

urn
Val
ue
Typ
e

of grid ubl
e

of grid ubl
e

of grid ubl
e
conversion ubl
efficiency e
(manufacturer)
temperature ubl
e

ubl
e

ubl
e

ubl
e

power ubl
e

ubl
e

power ubl
e

voltage ubl
e

SmartPVMS

urn
Val
ue
Typ
e

voltage ubl
e

voltage ubl
e

voltage ubl
e

voltage ubl
e

voltage ubl
e

voltage ubl
e

voltage ubl
e

voltage ubl
e

voltage ubl
e

voltage ubl
e

voltage ubl
e

voltage ubl
e
SmartPVMS

urn
Val
ue
Typ
e

voltage ubl
e

voltage ubl
e

voltage ubl
e

voltage ubl
e

voltage ubl
e

voltage ubl
e

voltage ubl
e

voltage ubl
e

voltage ubl
e

voltage ubl
e

voltage ubl
e

voltage ubl
e
SmartPVMS

urn
Val
ue
Typ
e

voltage ubl
e

voltage ubl
e

voltage ubl
e

current ubl
e

current ubl
e

current ubl
e

current ubl
e

current ubl
e

current ubl
e

current ubl
e

current ubl
e

current ubl
e
SmartPVMS

urn
Val
ue
Typ
e

current ubl
e

current ubl
e

current ubl
e

current ubl
e

current ubl
e

current ubl
e

current ubl
e

current ubl
e

current ubl
e

current ubl
e

current ubl
e

current ubl
e
SmartPVMS

urn
Val
ue
Typ
e

current ubl
e

current ubl
e

current ubl
e

current ubl
e

current ubl
e

current ubl
e

current ubl
e

ubl
e

time ubl
e
shutdown time ubl
e
mppt_total_cap Total DC input kWh Do

energy ubl
e

yield ubl
e
SmartPVMS

urn
Val
ue
Typ
e

yield ubl
e

yield ubl
e

yield ubl
e

yield ubl
e

yield ubl
e

yield ubl
e

yield ubl
e

yield ubl
e
mppt_10_cap MPPT 10 DC kWh Do

total yield ubl
e

Residential For details, see ubl

of grid ubl
e

of grid ubl
e
SmartPVMS

urn
Val
ue
Typ
e

of grid ubl
e

ubl
e

ubl
e

ubl
e

of grid ubl
e

of grid ubl
e

of grid ubl
e
conversion ubl
efficiency e
(manufacturer)
temperature ubl
e

ubl
e

ubl
e

ubl
e
SmartPVMS

urn
Val
ue
Typ
e

power ubl
e

ubl
e

power ubl
e

voltage ubl
e

voltage ubl
e

voltage ubl
e

voltage ubl
e

voltage ubl
e

voltage ubl
e

voltage ubl
e

voltage ubl
e

current ubl
e
SmartPVMS

urn
Val
ue
Typ
e

current ubl
e

current ubl
e

current ubl
e

current ubl
e

current ubl
e

current ubl
e

current ubl
e

ubl
e

time ubl
e
shutdown time ubl
e

yield ubl
e

yield ubl
e
SmartPVMS

urn
Val
ue
Typ
e

yield ubl
e

yield ubl
e
ID: 10 temperature Temperature °C Do

EMI ubl
e
pv_temperature PV temperature °C Do
ubl
e
wind_speed Wind speed m/s Do

ubl
e
wind_direction Wind direction Degree Do

ubl
e
radiant_total Daily irradiation MJ/m2 Do

ubl
e
radiant_line Irradiance W/m2 Do

ubl
e
horiz_radiant_lin Horizontal W/m2 Do Invalid

e irradiance ubl field. The
e default
value is
null.
horiz_radiant_tot Horizontal MJ/m2 Do Invalid

al irradiation ubl field. The
e default
value is
null.
ID: 17 ab_u A-B line voltage V Do

Grid meter of grid ubl
e
SmartPVMS

urn
Val
ue
Typ
e

of grid ubl
e

of grid ubl
e

(AC output) ubl
e

(AC output) ubl
e

(AC output) ubl
e

of grid (IA) ubl
e

of grid (IB) ubl
e

of grid (IC) ubl
e

ubl
e

ubl
e

energy) e
reactive_power Reactive power kVar Do

ubl
e
SmartPVMS

urn
Val
ue
Typ
e

ap energy ubl
e
forward_reactive Positive reactive kWh Do

_cap energy ubl
e
reverse_reactive_ Negative reactive kWh Do

cap energy ubl
e

ubl
e

ubl
e

ubl
e

a QA ubl field. The
e default
value is
null.

b QB ubl field. The
e default
value is
null.

c QC ubl field. The
e default
value is
null.
total_apparent_p Total apparent kVA Do

ower power ubl
e
SmartPVMS

urn
Val
ue
Typ
e
grid_frequency Grid frequency Hz Do Invalid

ubl field. The
e default
value is
null.

e default
value is
null.

value is
null.

peak) e default
value is
null.

e default
value is
null.

e default
value is
null.

value is
null.

peak) e default
value is
null.
SmartPVMS

urn
Val
ue
Typ
e

e default
value is
null.

e default
value is
null.

value is
null.

peak) e default
value is
null.

e default
value is
null.

e default
value is
null.

value is
null.

peak) e default
value is
null.
SmartPVMS

urn
Val
ue
Typ
e

e default
value is
null.
ID: 47 meter_status Meter state (0: None Do

Power offline; 1: ubl
sensor normal) e
meter_u Grid voltage V Do

ubl
e
meter_i Grid current A Do

ubl
e
active_power Active power W Do

ubl
e
reactive_power Reactive power Var Do

ubl
e

ubl
e
grid_frequency Grid frequency Hz Do

ubl
e

energy) e

ap energy ubl
e

of grid ubl
e

of grid ubl
e
SmartPVMS

urn
Val
ue
Typ
e

of grid ubl
e

(AC output) ubl
e

(AC output) ubl
e

of grid (IB) ubl
e

of grid (IC) ubl
e
forward_reactive Positive reactive kWh Do Invalid

_cap energy ubl field. The
e default
value is
null.
reverse_reactive_ Negative reactive kWh Do Invalid

cap energy ubl field. The
e default
value is
null.

ubl
e

ubl
e

ubl
e
SmartPVMS

urn
Val
ue
Typ
e

a QA ubl field. The
e default
value is
null.

b QB ubl field. The
e default
value is
null.

c QC ubl field. The
e default
value is
null.
total_apparent_p Total apparent kVA Do Invalid

ower power ubl field. The
e default
value is
null.

e default
value is
null.

value is
null.

peak) e default
value is
null.

e default
value is
null.
SmartPVMS

urn
Val
ue
Typ
e

e default
value is
null.

value is
null.

peak) e default
value is
null.

e default
value is
null.

e default
value is
null.

value is
null.

peak) e default
value is
null.

e default
value is
null.
SmartPVMS

urn
Val
ue
Typ
e

e default
value is
null.

value is
null.

peak) e default
value is
null.

e default
value is
null.
ID: 39 battery_status Battery running None Do

Residential state (0: offline; ubl
battery 1: standby; 2: e
running; 3:
faulty; 4:
hibernating)
max_charge_po Maximum W Do
wer charge power ubl
e
max_discharge_ Maximum W Do
power discharge power ubl
e
ch_discharge_po Charge/ W Do
wer Discharge power ubl
e
busbar_u Battery voltage V Do

ubl
e
SmartPVMS

urn
Val
ue
Typ
e

ubl
e

ubl
e
ch_discharge_m Charge/ None Do

odel Discharge mode ubl
(0: none; 1: e
forced charge/
discharge; 2:
time-of-use
price; 3: fixed
charge/
discharge; 4:
automatic
charge/
discharge)

ubl
e

energy ubl
e
ID: 41 ch_discharge_po Charge/ W Do

C&I and wer Discharge power ubl
utility ESS e

ubl
e

ubl
e

energy ubl
e
SmartPVMS

urn
Val
ue
Typ
e
ID: 60001 mains_state Mains status (0: None Do

Mains mains ubl
(supported unavailable; 1: e
only in the mains available)
Power-M ac_voltage AC voltage V Do
scenario) ubl
e
ac_current AC current A Do
ubl
e

ubl
e
ac_frequency AC frequency Hz Do
ubl
e
ID: 60003 load_rate Load rate % Do

Genset ubl
(supported e
only in the running_state Running status None Do
Power-M (0: unknown; 1: ubl
scenario) stopped; 2: e
running)
ID: 60043 total_output_cur Total output A Do

SSU group rent current ubl
(supported e
only in the total_output_en Total output kWh Do
Power-M ergy energy ubl
scenario) e
ID: 60014 soc SOC % Do

Lithium ubl
battery rack e
(supported voltage Voltage V Do
only in the ubl
Power-M e
scenario)
average_temper Average °C Do
ature temperature ubl
e
SmartPVMS

urn
Val
ue
Typ
e
ID: 60010 ac_frequency AC frequency Hz Do

AC output ubl
power e
distribution total_load_active Total load active kW Do
(supported _power power ubl
only in the e
Power-M
scenario)
Table 5-2 Inverter state (inverter_state) description

0 Standby: initializing
1 Standby: insulation resistance detecting
2 Standby: irradiation detecting
3 Standby: grid detecting
256 Start
512 Grid-connected
513 Grid-connected: power limited
514 Grid-connected: self-derating
768 Shutdown: on fault
769 Shutdown: on command
770 Shutdown: OVGR
771 Shutdown: communication interrupted
772 Shutdown: power limited
773 Shutdown: manual startup required
774 Shutdown: DC switch disconnected
1025 Grid scheduling: cosφ-P curve
1026 Grid scheduling: Q-U curve
1280 Ready for terminal test
SmartPVMS
1281 Terminal testing...
1536 Inspection in progress
1792 AFCI self-check
2048 I-V scanning
2304 DC input detection
40960 Standby: no irradiation
45056 Communication interrupted (written by SmartLogger)
49152 Loading... (written by SmartLogger)
Examples
Request example:
{
"devIds":"214060404588862,213472461631079",
"devTypeId":1,
"startTime":1501862400000,
"endTime":1501872400000
}
Response examples:
{
"success":false,
"data":null,
"failCode":20009,
"params":{
"devIds":"214060404588862,213472461631079",
"devTypeId":1,
"startTime":1501862400000,
"endTime":1501872400000,
},
"message":null
}
Example 2: 5-minute device data is returned.

{
"success":true,
"data":[
{
"dataItemMap":{
"pv7_u":null,
"pv1_u":575.3,
"b_u":286.1,
"c_u":286.9,
"pv6_u":576.1,
"temperature":44.6,
"open_time":null,
"b_i":24.9,
"bc_u":495.6,
"pv9_u":null,
SmartPVMS
"pv8_u":null,
"c_i":25,
"mppt_total_cap":null,
"pv9_i":null,
"mppt_3_cap":null,
"mppt_2_cap":null,
"inverter_state":512,
"pv8_i":null,
"mppt_1_cap":null,
"pv6_i":7.1,
"mppt_power":21.962,
"pv1_i":7.1,
"total_cap":655.37,
"ab_u":495.4,
"pv7_i":null,
"pv13_u":null,
"reactive_power":20.95,
"pv10_u":null,
"pv12_i":null,
"pv11_i":null,
"pv3_i":7.1,
"pv11_u":null,
"pv2_i":7.1,
"pv13_i":null,
"power_factor":0,
"pv12_u":null,
"pv5_i":7.2,
"active_power":21.05,
"elec_freq":50.05,
"pv10_i":null,
"pv4_i":7,
"mppt_4_cap":null,
"mppt_5_cap":0,
"mppt_6_cap":0,
"mppt_7_cap":0,
"mppt_8_cap":0,
"mppt_9_cap":0,
"mppt_10_cap":0,
"pv4_u":577.8,
"close_time":null,
"day_cap":159.26,
"ca_u":496.9,
"a_i":24.9,
"pv5_u":576.1,
"a_u":286,
"pv3_u":577.8,
"pv14_u":null,
"pv14_i":null,
"pv15_u":0,
"pv15_i":0,
"pv16_u":0,
"pv16_i":0,
"pv17_u":0,
"pv17_i":0,
"pv18_u":0,
"pv18_i":0,
"pv19_u":0,
"pv19_i":0,
"pv20_u":0,
"pv20_i":0,
"pv21_u":0,
"pv21_i":0,
"pv22_u":0,
"pv22_i":0,
"pv23_u":0,
"pv23_i":0,
"pv24_u":0,
"pv24_i":0,
"pv25_u":0,
SmartPVMS
"pv25_i":0,
"pv26_u":0,
"pv26_i":0,
"pv27_u":0,
"pv27_i":0,
"pv28_u":0,
"pv28_i":0,
"efficiency":null,
"pv2_u":575.3
},
"devId":213472461631079,
"collectTime":1501862400000
},
{
"dataItemMap":{
"pv7_u":null,
"pv1_u":575.3,
"b_u":286.1,
"c_u":286.9,
"pv6_u":576.1,
"temperature":44.6,
"open_time":null,
"b_i":24.9,
"bc_u":495.6,
"pv9_u":null,
"pv8_u":null,
"c_i":25,
"mppt_total_cap":null,
"pv9_i":null,
"mppt_3_cap":null,
"mppt_2_cap":null,
"inverter_state":512,
"pv8_i":null,
"mppt_1_cap":null,
"pv6_i":7.1,
"mppt_power":21.962,
"pv1_i":7.1,
"total_cap":655.37,
"ab_u":495.4,
"pv7_i":null,
"pv13_u":null,
"reactive_power":20.95,
"pv10_u":null,
"pv12_i":null,
"pv11_i":null,
"pv3_i":7.1,
"pv11_u":null,
"pv2_i":7.1,
"pv13_i":null,
"power_factor":0,
"pv12_u":null,
"pv5_i":7.2,
"active_power":21.05,
"elec_freq":50.05,
"pv10_i":null,
"pv4_i":7,
"mppt_4_cap":null,
"mppt_5_cap":0,
"mppt_6_cap":0,
"mppt_7_cap":0,
"mppt_8_cap":0,
"mppt_9_cap":0,
"mppt_10_cap":0,
"pv4_u":577.8,
"close_time":null,
"day_cap":159.26,
"ca_u":496.9,
"a_i":24.9,
"pv5_u":576.1,
SmartPVMS
"a_u":286,
"pv3_u":577.8,
"pv14_u":null,
"pv14_i":null,
"pv15_u":0,
"pv15_i":0,
"pv16_u":0,
"pv16_i":0,
"pv17_u":0,
"pv17_i":0,
"pv18_u":0,
"pv18_i":0,
"pv19_u":0,
"pv19_i":0,
"pv20_u":0,
"pv20_i":0,
"pv21_u":0,
"pv21_i":0,
"pv22_u":0,
"pv22_i":0,
"pv23_u":0,
"pv23_i":0,
"pv24_u":0,
"pv24_i":0,
"pv25_u":0,
"pv25_i":0,
"pv26_u":0,
"pv26_i":0,
"pv27_u":0,
"pv27_i":0,
"pv28_u":0,
"pv28_i":0,
"efficiency":null,
"pv2_u":575.3
},
"devId":213472461631079,
}
],
"failCode":0,
"params":{
"devIds":"214060404588862,213472461631079",
"devTypeId":1,
"startTime":1501862400000,
"endTime":1501872400000,
},
"message":null
}
NOTE
5.1.3 Alarm
5.1.3.1 API for Querying Active Alarms
API Description
This API is used to query the current (active) alarm information of a device. If the
query is based on plants, a maximum of 100 plants can be queried at a time. If
the query is based on device SNs, a maximum of 100 devices can be queried at a
time. If the transferred plant ID list is not empty, device alarm information is
SmartPVMS
queried based on the plant ID list. If the plant ID list is empty and the device SN
list is not empty, device alarm information is queried based on the device SN list.
Request URL
https://Domain name of the management system/thirdData/getAlarmList
Request Mode
HTTP method: POST
Request Parameters
Type ry/
Optional
stationCode Plant ID list. Multiple plant IDs are String Optional

s separated by commas (,). The plant IDs
Plant List API.
At least one of the stationCodes and sns
parameters must be set. If both
parameters are set, alarms are queried by
stationCodes.

separated by commas (,). At least one of
the stationCodes and sns parameters
must be set. If both parameters are set,
alarms are queried by stationCodes.
beginTime Query start time, in milliseconds Long Mandato

ry
endTime Query end time, in milliseconds Long Mandato

ry
SmartPVMS

Type ry/
Optional
language Language. The value must be zh_CN, String Mandato

en_US, ja_JP, it_IT, nl_NL, pt_BR, de_DE, ry
fr_FR, es_ES, or pl_PL.
zh_CN: Chinese
en_US: English
ja_JP: Japanese
it_IT: Italian
nl_NL: Dutch
pt_BR: Portuguese
de_DE: German
fr_FR: French
es_ES: Spanish
pl_PL: Polish
levels Alarm severity. Multiple alarm severities String Optional

are separated by commas (,), for example,
1,2. If this parameter is not transferred or
is left empty, alarms of all severities are
queried by default.
The following alarm severities are
supported:
1: critical
2: major
3: minor
4: warning
SmartPVMS

Type ry/
Optional
devTypes Device type. Multiple device types are String Optional

separated by commas (,), for example,
1,38. If this parameter is not transferred
or is left empty, alarms of all device types
are queried by default.
1: string inverter
2: SmartLogger
8: STS
10: EMI
16: general device
17: grid meter
22: PID
39: battery
40: backup box
45: PLC
46: optimizer
47: power sensor
62: Dongle
70: safety box
60001: mains
60003: genset
60043: SSU group
60044: SSU
SmartPVMS
Response Packet
Type s

flag. Value: success
succeeded. failure
flag.
false: The request failed. Value:

Code List.
s
parameter.

parameter.
beginTime Start time in the request Long -

parameter, in milliseconds.
endTime End time in the request Long -

parameter, in milliseconds.
language Language in the request String -

parameter.
levels Alarm severity in the String -

request parameter.
devTypes Device type in the request String -

parameter.

milliseconds.
message Optional message. String -

contains the alarm
information list.
stationCode Plant ID, which uniquely String -

identifies a plant.
alarmName Alarm name. String -
devName Device name. String -
SmartPVMS

Type s
repairSuggestion Suggestions. String -
esnCode Device SN. String -
devTypeId Device type ID. Integer -

The following device types
are supported:
1: string inverter
2: SmartLogger
8: STS
10: EMI
16: general device
17: grid meter
22: PID
39: battery
40: backup box
45: PLC
46: optimizer
47: power sensor
62: Dongle
70: safety box
60001: mains
60003: genset
60043: SSU group
60044: SSU
60010: AC output power
distribution
causeId Cause ID. Integer -
alarmCause Alarm cause. String -
SmartPVMS

Type s
alarmType Alarm type. Integer -

The following alarm types
are supported:
0: other alarms
1: transposition signal
2: exception alarm
3: protection event
4: notification status
5: alarm information
raiseTime Alarm generation time in Long -

milliseconds
alarmId Alarm ID Integer -
stationName Plant name String -
lev Alarm severity Integer -

The following alarm
severities are supported:
1: critical
2: major
3: minor
4: warning
status Alarm status. Integer -

The following alarm states
are supported:
1: not processed (active)
Example
Request example:
{
"stationCodes":"NE=33554785,NE=33554792",
"sns":"Inverter01",
"beginTime":"1664553600000",
"endTime":"1667231999000",
"language":"zh_CN",
"levels":"1,2,3,4",
"devTypes":"1,2,38,46,62"
}
Response examples:
{
"data": null,
SmartPVMS
"failCode": 20055,
"message": null,
"params": {
"currentTime": 1667399781133,
"sns": "",
"language": "zh_CN",
"beginTime": 1664553600000,
"devTypes": "1,2,38,46,62",
"endTime": 1667231999000,
"levels": "1,2,3,4",
"stationCodes": ""
},
"success": false
}
Example 2: Alarm data of the device is returned.

{
"data": [
{
"alarmCause": "An unrecoverable fault has occurred in the internal circuit of the device.",
"alarmId": 2064,
"alarmName": "The device is abnormal.",
"alarmType": 2,
"causeId": 5,
"devName": "Inverter-1",
"devTypeId": 38,
"esnCode": "Inverter05",
"lev": 2,
"raiseTime": 1667179861000,
"repairSuggestion": "Turn off the AC and DC switches, wait for 5 minutes, and then turn on the AC
and DC switches. If the fault persists, contact your dealer or technical support.",
"stationCode": "NE=33554792",
"stationName": "hzhStation02",
"status": 1
},
{
"alarmCause": "1. The voltage of a battery expansion module is low.",
"alarmId": 3011,
"alarmName": "Battery expansion module undervoltage",
"alarmType": 2,
"causeId": 2,
"devName": "Inverter-2",
"devTypeId": 38,
"esnCode": "Inverter01",
"lev": 4,
"raiseTime": 1665264943000,
"repairSuggestion": "1. If the sunlight is sufficient or AC reverse charging is allowed, the Battery
[CNo] battery expansion module [SNo] (in the fault location information) can be charged when the
inverter is running.",
"stationCode": "NE=33554785",
"stationName": "hzhStation01",
"status": 1
}
],
"failCode": 0,
"message": null,
"params": {
"currentTime": 1667399432812,
"sns": "Inverter01",
"language": "zh_CN",
"beginTime": 1664553600000,
"devTypes": "1,2,38,46,62",
"endTime": 1667231999000,
"levels": "1,2,3,4",
"stationCodes": "NE=33554785,NE=33554792"
},
"success": true
}
SmartPVMS
NOTE
Request example:
5.1.4 Report
5.1.4.1 Hourly Plant Data API
API Description
This API is used to obtain hourly plant data. Data of a maximum of 100 plants can
The backend calculates the date of the collection time based on the request
parameter collectTime (collection time in milliseconds) and the time zone where
SmartPVMS
the plant is located. Then, you can query the hourly data of the plant by plant ID
in the current day. If data is generated for n (0 ≤ n ≤ 24) hours of the day, n (0 ≤ n
≤ 24) results are returned.
For details about the data list that can be queried through this API, see the hourly
plant data list below.
Request URL
https://Domain name of the management system/thirdData/getKpiStationHour
Request Mode
HTTP method: POST
Request Parameters
Type ry/
Optional

Plant List API.
collectTime Collection time, in milliseconds Long Mandato

ry
Response Packet
Type s
success Request success or failure boolean Request

flag success
failure

Code List.
s
parameter
SmartPVMS

Type s

parameter

milliseconds
data Parameters Returned data. The data List List of

contains the hourly data hourly
object list of each plant. plant
data in
a day
collectTime Collection time, in Long -

milliseconds

which is returned in key-
the hourly plant data list
below.
Hourly Plant Data List
Key Name Unit Return Remarks

Value
Type
radiation_intens Global kWh/m² Double

ity irradiatio
n
theory_power Theoretic kWh Double

al yield
inverter_power Inverter kWh Double The calculation of

yield this indicator is
inaccurate. The
inverterYield is
preferred.
ongrid_power Feed-in kWh Double

energy
SmartPVMS

Value
Type
power_profit Revenue The currency Double

specified in the
management
system
chargeCap Charged kWh Double

energy
dischargeCap Discharg kWh Double

ed
energy
selfProvide Energy kWh Double

consume
d from
PV
PVYield PV yield kWh Double
inverterYield Inverter kWh Double

yield
Example
Request example:
{
}
Response example:
{
"success":false,
"data":null,
"failCode":20009,
"params":{
"collectTime":1501862400000,
},
"message":null
}
Example 2: Hourly plant data is returned.

{
"success":true,
"data":[
{
"dataItemMap":{
"radiation_intensity":null,
"theory_power":null,
"inverter_power":0,
SmartPVMS
"ongrid_power":null,
"power_profit":0,
"chargeCap":null,
"dischargeCap":null,
"selfProvide":null,
},
},
{
"dataItemMap":{
"inverter_power":0,
"power_profit":0,
"chargeCap":null,
"selfProvide":null,
},
},
{
"dataItemMap":{
"inverter_power":0,
"power_profit":0,
"chargeCap":null,
"selfProvide":null,
},
"stationCode":"BA4372D08E014822AB065017416F254C",
},
{
"dataItemMap":{
"inverter_power":0,
"power_profit":0,
"chargeCap":null,
"selfProvide":null,
},
},
{
"dataItemMap":{
"inverter_power":0,
"power_profit":0,
"chargeCap":null,
"selfProvide":null,
},
},
{
"dataItemMap":{
SmartPVMS
"inverter_power":0,
"power_profit":0,
"chargeCap":null,
"selfProvide":null,
},
},
{
"dataItemMap":{
"inverter_power":0,
"power_profit":0,
"chargeCap":null,
"selfProvide":null,
},
},
{
"dataItemMap":{
"inverter_power":0,
"power_profit":0,
"chargeCap":null,
"selfProvide":null,
},
}
],
"failCode":0,
"params":{
"collectTime":1501862400000,
},
"message":null
}
SmartPVMS
NOTE
Request example:
5.1.4.2 Daily Plant Data API
API Description
This API is used to obtain daily plant data. Data of a maximum of 100 plants can
The backend calculates the month of the collection time based on the request
the plant is located. Then, you can query the daily data of the plant by plant ID in
the current month. If data is generated for n (0 ≤ n ≤ 31) days of the month, n (0
≤ n ≤ 31) results are returned.
For details about the data list that can be queried through this API, see the daily
Request URL
https://{Domain name of the management system}/thirdData/getKpiStationDay
Request Mode
HTTP method: POST
SmartPVMS
Request Parameters
Type ry/
Optional

Plant List API.

ry
Response Packet
Type s

flag. success
succeeded. failure
flag
failCode Error code. Integer -

Code List.
s
parameter.

parameter.

milliseconds.
data Parameters Returned data. The data List Daily

contains the daily data data list
object list of each plant. of a
plant in
a month
stationCode Plant ID. String -
SmartPVMS

Type s

milliseconds.

the daily plant data list
below.
Daily Plant Data List

Value
Type
installed_capacit Installed kW Double

y capacity
radiation_intensi Global kWh/m² Double

ty irradiation
theory_power Theoretical kWh Double

yield
performance_rat Performance %
io ratio
inverter_power Inverter yield kWh Double The calculation

of this indicator
is inaccurate. The
inverterYield is
preferred.
ongrid_power Feed-in kWh Double

energy
use_power Consumption kWh Double
power_profit Revenue The Double

currency
specified in
the
manageme
nt system
perpower_ratio Specific h Double

energy (kWh/
kWp)
SmartPVMS

Value
Type
reduction_total_ CO2 emission Ton Double

co2 reduction
reduction_total_ Standard coal Ton Double

coal saved
reduction_total_ Equivalent N/A Double The indicator is

tree trees planted reserved and the
value cannot be
obtained.
buyPower Energy from kWh Double

grid
chargeCap Charged kWh Double

energy
dischargeCap Discharged kWh Double

energy
selfUsePower Consumed PV kWh Double

energy
selfProvide Energy kWh Double

consumed
from PV
inverterYield Inverter yield kWh Double
Example
Request example:
{
}
Response examples:
{
"data": null,
"failCode": 20012,
"message": null,
"params": {
"currentTime": 1687788735543,
"collectTime": -1677051223000,
"stationCodes": "BA4372D08E014822AB065017416F254C,5D02E8B40AD342159AC8D8A2BCD4FAB5"
},
SmartPVMS
"success": false
}
Example 2: Daily plant data is returned.

{
"success":true,
"data":[
{
"dataItemMap":{
"use_power":288760,
"radiation_intensity":0.6968,
"reduction_total_co2":18.275,
"reduction_total_coal":7.332,
"theory_power":17559.36,
"ongrid_power":18330,
"power_profit":34320,
"installed_capacity":25200,
"perpower_ratio":0.727,
"inverter_power":18330,
"reduction_total_tree":999,
"performance_ratio":89
},
},
{
"dataItemMap":{
"use_power":null,
"installed_capacity":467.04,
"inverter_power":18330,
},
}
],
"failCode":0,
"params":{
"collectTime":1501862400000,
},
"message":null
}
SmartPVMS
NOTE
Request example:
5.1.4.3 Monthly Plant Data API
API Description
This API is used to obtain monthly plant data. Data of a maximum of 100 plants
can be queried at a time.
The backend calculates the year of the collection time based on the request
the plant is located. Then, you can query the monthly data of the plant by plant
ID in the current year. If data is generated for n (0 ≤ n ≤ 12) months of the year, n
(0 ≤ n ≤ 12) results are returned.
monthly plant data list below.
Request URL
https://{Domain name of the management system}/thirdData/getKpiStationMonth
SmartPVMS
Request Mode
HTTP method: POST
Request Parameters
Type ry/
Optional

Plant List API.

ry
Response Packet
Type s

flag. success
succeeded. failure
flag

Code List.
s
parameter.

parameter.

milliseconds.
SmartPVMS

Type s
data Parameters Returned data. The data List Monthly

contains the monthly data data list
object list of each plant. of a
plant in
a year
stationCode Plant ID. String -

milliseconds.

the monthly plant data list
below.
Monthly Plant Data List

Value
Type
installed_capacit Installed capacity kW Double

y
radiation_intensi Global irradiation kWh/m² Double

ty
theory_power Theoretical yield kWh Double
performance_rat Performance %
io ratio
inverter_power Inverter yield kWh Double The calculation

of this indicator
is inaccurate.
The
inverterYield is
preferred.
ongrid_power Feed-in energy kWh Double
use_power Consumption kWh Double
SmartPVMS

Value
Type
power_profit Revenue The Double

currency
specified
in the
managem
ent
system
perpower_ratio Specific energy h Double

(kWh/kWp)
reduction_total_ CO2 emission Ton Double

co2 reduction
reduction_total_ Standard coal Ton Double

coal saved
reduction_total_ Equivalent trees N/A Double The indicator is

tree planted reserved and the
value cannot be
obtained.
buyPower Energy from grid kWh Double
chargeCap Charged energy kWh Double
dischargeCap Discharged kWh Double

energy
selfUsePower Consumed PV kWh Double

energy
selfProvide Energy consumed kWh Double

from PV
inverterYield Inverter yield kWh Double
Example
Request example:
{
}
Response examples:
{
"data": null,
SmartPVMS
"failCode": 20012,
"message": null,
"params": {
"currentTime": 1687788735543,
"collectTime": -1677051223000,
"stationCodes": "BA4372D08E014822AB065017416F254C,5D02E8B40AD342159AC8D8A2BCD4FAB5"
},
"success": false
}
Example 2: Monthly plant data is returned.

{
"success":true,
"data":[
{
"dataItemMap":{
"use_power":288760,
"inverter_power":null,
},
},
{
"dataItemMap":{
"use_power":null,
},
}
],
"failCode":0,
"params":{
"collectTime":1501862400000,
},
"message":null
}
SmartPVMS
NOTE
Request example:
5.1.4.4 Yearly Plant Data API
API Description
This API is used to obtain yearly plant data. Data of a maximum of 100 plants can
Based on the plant ID, the backend queries the data of each year since the plant
was constructed (including the current year).
For details about the data list that can be queried through this API, see the yearly
Request URL
https://Domain name of the management system/thirdData/getKpiStationYear
Request Mode
HTTP method: POST
SmartPVMS
Request Parameters
Type ry/
Optional

Plant List API.

ry
Response Packet
Type s

flag success
failure

Code List.
s
parameter

parameter

milliseconds
data Parameters Returned data. The data List Yearly

contains the yearly data data list
object list of each plant. of the
plant
since its
construc
tion
SmartPVMS

Type s

milliseconds

the yearly plant data list
below.
Yearly Plant Data List
Key Name Unit Retur Remarks

n
Value
Type
installed_capacit Installed capacity kW Doubl

y e
radiation_intensi Global irradiation kWh/m² Doubl

ty e
theory_power Theoretical yield kWh Doubl

e
performance_rat Performance ratio %

io
inverter_power Inverter yield kWh Doubl The

e calculation of
this indicator
is inaccurate.
The
inverterYield
is preferred.
ongrid_power Feed-in energy kWh Doubl

e
use_power Consumption kWh Doubl

e
power_profit Revenue The currency Doubl

specified in e
the
management
system
SmartPVMS
Key Name Unit Retur Remarks

n
Value
Type
perpower_ratio Specific energy h Doubl

(kWh/kWp) e
reduction_total_ CO2 emission Ton Doubl

co2 reduction e
reduction_total_ Standard coal Ton Doubl

coal saved e
reduction_total_ Equivalent trees N/A Doubl

tree planted e
buyPower Energy from grid kWh Doubl

e
chargeCap Charged energy kWh Doubl

e
dischargeCap Discharged energy kWh Doubl

e
selfUsePower Consumed PV kWh Doubl

energy e
selfProvide Energy consumed kWh Doubl

from PV e
PVYield PV yield kWh Doubl

e
inverterYield Inverter yield kWh Doubl

e
Example
Request example:
{
}
Response examples:
{
"success":false,
"data":null,
"failCode":20009,
"params":{
"collectTime":1501862400000,
SmartPVMS
},
"message":null
}
Example 2: Yearly plant data is returned.

{
"success":true,
"data":[
{
"dataItemMap":{
"use_power":288760,
},
},
{
"dataItemMap":{
"use_power":null,
},
}
],
"failCode":0,
"params":{
"collectTime":1501862400000,
},
"message":null
}
SmartPVMS
NOTE
Request example:
5.1.4.5 Daily Device Data API
API Description
This API is used to obtain daily device data. The daily data of a maximum of 100
devices of the same type can be queried at a time.
The backend calculates the month of the collection time based on the request
the device is located. Then, you can query the daily data of the device by device ID
in the current month. If data is generated for n (0 ≤ n ≤ 31) days of the month, n
(0 ≤ n ≤ 31) results are returned.
For details about the data list that can be queried through this API, see the daily
device data list below.
Request URL
https://Domain name of the management system/thirdData/getDevKpiDay
SmartPVMS
Request Mode
HTTP method: POST
Request Parameters
Type ry/
Optional
set.

devIds must be set.

used.
1: string inverter
39: battery
41: ESS

ry
Response Packet
Type s

flag success
failure

Code List.
s
SmartPVMS

Type s

parameter

parameter

request parameter

parameter

milliseconds

contains the daily data daily
object list of each device. device
data in
a month
sn Device SN String

milliseconds
dataItemMap Content of each data item, Map Data of

which is returned in the key- a device
value format. The data item in a day
content varies depending on
the daily device data list
below.
Daily Device Data List
Device Type Key Name Unit Return

Value
Type
ID: 39 charge_cap Charged energy kWh Double

Residential discharge_cap Discharged energy kWh Double
battery
charge_time Charging duration h Double
SmartPVMS

Value
Type
discharge_time Discharging h Double

duration
ID: 1 installed_capacity Installed capacity kW Double

String product_power Yield kWh Double
inverter
(kWh/kWp)

Residential product_power Yield kWh Double
inverter
(kWh/kWp)

C&I and discharge_cap Discharged energy kWh Double
utility ESS
Examples
Request example:
{
"devIds":"214060404588862,213472461631079",
"devTypeId":1,
}
Response example:
{
"success":false,
"data":null,
"failCode":20009,
"params":{
"devIds":"214060404588862,213472461631079",
"devTypeId":1,
"collectTime":1501862400000,
},
"message":null
}
Example 2: Daily device data is returned.

{
"success":true,
"data":[
{
"dataItemMap":{
SmartPVMS
"product_power":300
},
"devId":213472461631079,
},
{
"dataItemMap":{
"product_power":16.43
},
"devId":214060404588862,
}
],
"failCode":0,
"params":{
"devIds":"214060404588862,213472461631079",
"devTypeId":1,
"collectTime":1501862400000,
},
"message":null
}
NOTE
Request example:
SmartPVMS
5.1.4.6 Monthly Device Data API
API Description
This API is used to obtain monthly device data. The monthly data of a maximum
of 100 devices of the same type can be queried at a time.
The backend calculates the year of the collection time based on the request
the device is located. Then, you can query the monthly data of the device by
device ID in the current year. If data is generated for n (0 ≤ n ≤ 12) months of the
year, n (0 ≤ n ≤ 12) results are returned.
monthly device data list below.
Request URL
https://Domain name of the management system/thirdData/getDevKpiMonth
Request Mode
HTTP method: POST
Request Parameters
Type ry/
Optional
set.

devIds must be set.

used.
1: string inverter
39: battery
41: ESS

ry
SmartPVMS
Response Packet
Type s

flag success
failure

Code List.
s
parameter

parameter

request parameter

parameter

milliseconds

contains the monthly data monthly
object list of each device. device
data in
a year
sn Device SN String

milliseconds
SmartPVMS

Type s
dataItemMap Content of each data item, Map Data of

which is returned in the key- a device
value format. The data item in a
content varies depending on month
the monthly device data list
below.
Monthly Device Data List

Value
Type

battery

duration

String product_power Yield kWh Double
inverter
(kWh/kWp)

Residential product_power Yield kWh Double
inverter
(kWh/kWp)

utility ESS
Examples
Request example:
{
"devIds":"214060404588862,213472461631079",
"devTypeId":1,
}
SmartPVMS
Response example:
{
"success":false,
"data":null,
"failCode":20009,
"params":{
"devIds":"214060404588862,213472461631079",
"devTypeId":1,
"collectTime":1501862400000,
},
"message":null
}
Example 2: Monthly device data is returned.

{
"success":true,
"data":[
{
"dataItemMap":{
"perpower_ratio":null,
"product_power":300
},
"devId":213472461631079,
},
{
"dataItemMap":{
"product_power":16.43
},
"devId":214060404588862,
}
],
"failCode":0,
"params":{
"devIds":"214060404588862,213472461631079",
"devTypeId":1,
"collectTime":1501862400000,
},
"message":null
}
SmartPVMS
NOTE
Request example:
5.1.4.7 Yearly Device Data API
API Description
This API is used to obtain yearly device data. The yearly data of a maximum of
100 devices of the same type can be queried at a time.
The backend queries the data of each year since the device was connected based
on the device ID.
For details about the data list that can be queried using this API, see #EN-
US_TOPIC_0000001701648221/p2057810145254.
Request URL
https://Domain name of the management system/thirdData/getDevKpiYear
Request Mode
HTTP method: POST
SmartPVMS
Request Parameters
Type ry/
Optional
set.

devIds must be set.
devTypeId Device type ID Integer Mandato

The following device types are supported: ry
1: string inverter
39: battery
41: ESS

ry
NOTE
Before obtaining data, you must configure related counters.
Response Packet
Type s

flag success
failure

definitions of other error
List.
s
SmartPVMS

Type s

parameter

parameter

request parameter

parameter

milliseconds
messa - Optional message String -

ge
data Parameters Returned data. The data List Data list

contains the yearly data of each
object list of each device. year
since
the
device is
connect
ed
sn Device SN String

milliseconds
dataItemMap Content of data items, Map Data of

which are returned in the a device
key-value format. The in a
content of data items varies year
according to device types.
For details about the data
item list, see #EN-
US_TOPIC_0000001701648
221/p2057810145254.
Yearly Device Data List
SmartPVMS

Value
Type

battery

duration

String product_power Energy yield kWh Double
inverter
(kWh/kWp)

Residential product_power Energy yield kWh Double
inverter
(kWh/kWp)

utility ESS
Examples
Request example:
{
"devIds":"214060404588862,213472461631079",
"devTypeId":1,
}
Response example:
{
"success":false,
"data":null,
"failCode":20009,
"params":{
"devIds":"214060404588862,213472461631079",
"devTypeId":1,
"collectTime":1501862400000,
},
"message":null
}
Example 2: Yearly device data is returned.

{
"success":true,
SmartPVMS
"data":[
{
"dataItemMap":{
"product_power":300
},
"devId":213472461631079,
}
],
"failCode":0,
"params":{
"devIds":"214060404588862,213472461631079",
"devTypeId":1,
"collectTime":1501862400000,
},
"message":null
}
NOTE
Request example:
5.2 Control APIs

Plants and devices can be remotely controlled through open APIs. This function is
available only in OAuth Connect mode.
SmartPVMS
5.2.1 API for Delivering Battery Charge and Discharge Tasks

API Description
This API is used to deliver battery charge and discharge tasks based on plant
codes. A task can be delivered to a maximum of 100 plants at a time. If there are
multiple ESSs in the power plant, the task is executed on every ESS.
The battery charge and discharge task does not change the original working mode
of the battery. After the task is complete, the battery continues to work in the
original working mode.
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.
For details about the scenario-based practices of this API, see 7.5 Scenario-based
Practices of Battery Scheduling.
Request URL
https://Domain name of the management system/rest/openapi/pvms/nbi/v2/
control/charge-and-discharge/async-task
Request Mode
HTTP method: POST
Request Parameters
Optional
tasks List of battery List M

charge and
discharge tasks. A
maximum of 100
plants can be
delivered at a
time.
> plantCode Plant code, which String M

is obtained from
plantCode in
5.1.1.1 Plant List
API.
SmartPVMS

Optional
> dispatchSwitch Charge/Discharge Integer M

switch.
0: stop forced
charge and
discharge
1: forced charge
2: forced
discharge
> controlType 1: SOC control. Integer Optional for

The target SOC is stopping forced
set in the forced charge/discharge.
charge/discharge
command. Legacy
versions may
need an update to
support SOC
control.
2: duration
control. The
duration is set in
the forced charge/
discharge
command.
> targetSOC Target SOC for Double Optional. This

charge/discharge, parameter is
in percentage. mandatory for
SOC control.
> dispatchTime Charge/Discharge Integer Optional. This

duration in parameter is
minutes. Value mandatory for
range: [0,1440] time control.
> powerDispatch Power of forced Integer Optional. If this

charge and parameter is left
discharge in watt. blank, the default
If the value power is used for
exceeds the charge and
range, the discharge.
maximum value is Range of
used. The value powerDispatch: [–
should be greater maximum
than 0 during discharge power,
forced charge and maximum charge
smaller than 0 power]
during forced
discharge.
SmartPVMS
NOTICE
● This API will change the device running parameters. Exercise caution when
invoking this API.
● The LG battery does not support SOC control.
● When a task is not complete (that is, the status bit is 1), the same signals
cannot be sent to the device corresponding to the task.
● This API can only be used to control the residential ESS.
● When the battery is disconnected, charge and discharge tasks cannot be
delivered to the battery.
Response Packet
Parameter Description Data Type Remarks
success Request success or failure Boolean Request success

flag or failure flag
true: The request
succeeded.

0: successful; 1: partially
successful; 2: failed
message Description of the API String -

returned content
data Returned data for each - -

request.
> requestID Unique ID of a requested Long -

task, which can be used to
query the task delivery
result.
> result Task result List -
>> plantCode Plant ID String -
>> sn Inverter SN String -
>> dispatchResult Charge/Discharge task Integer 0: The task is

delivery result received
successfully.
1: The task fails to
be received.
>> subTaskId Unique subtask ID String -
SmartPVMS
>> description Delivery result description String -
API Error Code List

No. Error Description
Code
1 305 You are not online and need to log in again.
2 401 You do not have the related data API permission.
3 407 The API access frequency is too high.
4 1 The task is partially successful.
5 2 The task fails.
Examples
Request example (the first task is time control and the second task is SOC
control.)
{
"tasks": [
{
"dispatchSwitch": 1,
"controlType": 2,
"dispatchTime": 600,
"powerDispatch": 5000
},
{
"dispatchSwitch": 1,
"controlType": 1,
"targetSOC": 100,
"powerDispatch": 5000
}
]
}
Response examples:
Example 1: The task fails.
{
"data": null,
"failCode": 2,
"message": "Battery charge and discharge task list is empty.",
"success": false
}

{
"data": {
"requestID": null,
SmartPVMS
"result": [
{
"sn": null,
"dispatchResult": 1,
"subTaskId": null,
"description": "PowerDispatch is illegal. The value should be greater than 0 during forced charge
(dispatchSwitch = 1) and smaller than 0 during forced discharge (dispatchSwitch = 2)."
},
{
"sn": null,
"subTaskId": null,
"description": "DispatchSwitch is illegal, valid value: 0 or 1 or 2"
}
]
},
"failCode": 2,
"message": "Failed to deliver the battery charge/discharge task.",
"success": false
}
Example 3: The task is partially successful.

{
"data": {
"requestID": 1107541629693466,
"result": [
{
"sn": null,
"subTaskId": null,
"description": "PowerDispatch is illegal. The value should be greater than 0 during forced charge
(dispatchSwitch = 1) and smaller than 0 during forced discharge (dispatchSwitch = 2)."
},
{
"sn": "6fbfk11",
"subTaskId": "2004882110006589",
"description": null
}
]
},
"failCode": 1,
"message": "The battery charge/discharge task is partially delivered successfully.",
"success": true
}
Example 4: The task is successful.

{
"data": {
"requestID": 9694030627470695,
"result": [
{
"sn": "5fbfk4",
"subTaskId": "4203991658344402",
"description": null
},
{
"sn": "6fbfk11",
"subTaskId": "1828180425476906",
"description": null
SmartPVMS
}
]
},
"failCode": 0,
"message": "The battery charge/discharge task is delivered successfully.",
"success": true
}
5.2.2 API for Querying Battery Charge and Discharge Tasks

API Description
This API is used to query the execution status of battery charge and discharge
tasks based on requestID. One task can be queried at a time.
Request URL
https://Domain name of the management system/rest/openapi/pvms/v1/vpp/
chargeAndDischargeStatus
Request Mode
HTTP method: POST
Request Parameters
Optional
requestID Unique ID of the Long M

requested task. The value
can be obtained from
requestID in 5.2.1 API
for Delivering Battery
Charge and Discharge
Tasks.
NOTICE
● If the charging and discharging task information of the battery in the plant
changes, the task is processed as an exception (status is 0). The exception
information is described in message.
SmartPVMS
Response Packet
success Request success or failure Boolean Request success or

flag failure flag
true: The request
succeeded.

other error codes, see API
Error Code List.
data Returned data for each Map -

request.
> plantCode Plant ID String -
> sn Inverter SN String -
> remoteID Unique subtask ID String -
> status Event status. The Integer 0: complete

execution status is 1: in progress
updated every 3 minutes.
If the task is not 2: timeout or
completed within 24 failure
hours, the task times out.
> chargedCapacity Amount of power that Double kWh

has been forcibly charged
into batteries. If
dispatchSwitch is not 1,
null is returned.
> Amount of power that Double kWh

dischargedCapaci- has been forcibly
ty discharged from
batteries. If
dispatchSwitch is not 2,
null is returned.
> execStartTime Time when a task is String 2020-02-06T00:00:

received, including the 00+08:00
time zone information
SmartPVMS
> execEndTime Time when a task is String 2020-02-06T00:00:

completed, including the 00+08:00
time zone information. If
a task is not completed,
null is returned.
> message Task result description String -
API Error Code List

Code
4 20044 The unique ID of a charge/discharge task cannot be empty.
5 20050 The charge/discharge task query parameter does not exist.
Examples
Request example:
{
"requestID": 432523532523
}
Response examples:
{
"success": false,
"data": null,
"failCode": 20008,
"message": null
}
Example 2: The task status data is returned.

{
"success":true,
"failCode":0,
"message":null,
"data":[
{
"plantCode":"NE=12345678",
"sn":"5fbfk4",
"remoteID":"12345678",
"status":0,
"chargedCapacity":1000,
SmartPVMS
"message":null,
"execStartTime":"2020-02-06T00:00:10+08:00",
"execEndTime":"2020-02-06T00:01:10+08:00"
},
{
"sn":"6fbfk11",
"remoteID":"23456789",
"status":0,
"chargedCapacity":2000,
"message":null,
"startTime":"2020-02-06T00:00:00+08:00",
"endTime":"2020-02-06T00:01:00+08:00"
}
]
}
5.2.3 API for Delivering a Task for Setting the Battery Working
Mode
API Description
This API is used to set the working mode of plant-level batteries based on the
plant DN. A task supports a maximum of 10 plants. Different parameters can be
delivered to each plant.
The networking of a single controller (Dongle, EMMA, distributed SmartLogger,

and direction connection of inverters) in a plant is supported. The battery working
mode can be set to maximumSelfConsumption or TOU.
Request URL
control/battery/mode/async-task
Request Mode
HTTP method: POST
Request Parameters
Optional
tasks List of the tasks for List M

setting the battery
working mode. A task
can be delivered to a
maximum of 10 plants
at a time.
> plantCode Plant DN. String M
SmartPVMS

Optional
> operationMode Working mode. String M

TOU: time of use
maximumSelfConsum
ption: maximum self-
consumption
If this parameter is set
to TOU, you can
manually set the
charge and discharge
time segments. This
mode applies to the
PV+ESS system and
ESS-only system
where electricity prices
at peak and off-peak
hours are different
and power meters are
available.
to
maximumSelfConsu
mption, PV power is
preferentially supplied
to loads and the
surplus power is used
to charge batteries. If
the ESS is fully
charged or is being
charged at full power,
the surplus PV energy
is fed to the power
grid. When PV power
is insufficient or no PV
power can be
generated at night,
the ESS discharges
power to loads. This
improves the self-
consumption rate and
energy self-sufficiency
rate, and reduces
electricity costs. The
grid cannot charge the
ESS but can supply
power to loads. This
mode applies to areas
where the electricity
price is high, or areas
SmartPVMS

Optional
where the FIT subsidy

is low or unavailable.
The PV+ESS system
generates sufficient PV
power for loads and
uses the surplus PV
power to charge the
ESS (if the PV power is
insufficient for loads,
the TOU mode is
recommended).
SmartPVMS

Optional
> Preferred use of String Optional (This

redundantPVEner- surplus PV power. parameter is
gyPriority fedToGridPreference: available when
The power is fed to operationMode
the grid preferentially. is set to TOU.)
chargePreference:
Charging is preferred.
fedToGridPreference:
When the PV power is
greater than the load
power, the surplus PV
energy is preferentially
fed to the grid. When
the maximum output
power of the device is
reached, the surplus
energy is used to
charge the batteries.
This setting is
applicable to the
scenario where the FIT
is higher than the
electricity price and
the grid cannot charge
the ESS.
chargePreference:
When the PV power is
greater than the load
power, the surplus PV
energy is used to
charge the batteries.
After the maximum
charge power is
reached or the
batteries are fully
charged, the surplus
PV energy is fed to the
grid.
SmartPVMS

Optional
> Maximum power for Double Optional (This

allowedAcCharge- charging batteries parameter is
Power from grid (kW). available when
The value range of operationMode
this parameter is is set to TOU.)
related to the
controller in the plant.
The value ranges are
as follows:
Dongle: [0.000,
30.000]
EMMA: [0.000, 50.000]
SmartLogger: [0.000,
50000.000]
Inverter: [0.000, upper
limit for the maximum
power for charging
batteries from grid]
This parameter is used
to set the maximum
power for charging
batteries from the
power grid.
> Charge/Discharge time List Optional (This

chargingAndDisch window. parameter must
argingTimeWindo Set the start time and be set when
w end time of charge operationMode
and discharge. A is set to TOU.)
maximum of 14 time
segments can be set.
For the same plant,
multiple overlapped
time segments cannot
be set on the same
day.
>> startTime Start time, in HH:MM String M

format.
Value range: 00:00–
23:59
>> endTime End time, in HH:MM String M

format.
Value range: 00:00–
23:59
SmartPVMS

Optional
>> Charge/Discharge String M

chargeOrDischarg Charge
e
Discharge
>> repeat Repeat date. A List M

maximum of seven
dates can be set for
each plant.
1: Monday
2: Tuesday
3: Wednesday
4: Thursday
5: Friday
6: Saturday
7: Sunday
NOTICE
calling this API.
● Do not send a new task to the same plant when the task is not complete (that
is, the status is RUNNING).
● For the same plant, multiple overlapped time segments cannot be set on the
same day.
● The battery working mode cannot be set for LG batteries.
● For a PV plant, if operationMode is set to TOU, the
chargingAndDischargingTimeWindow parameter must be set.
● When the controller in the plant is disconnected, the task of setting the battery
working mode cannot be delivered to the plant.
Response Packet
success Request success or failure boolean Request success

flag. or failure flag
true: The request
succeeded.
SmartPVMS


returned content.

request, including the
following information:
> taskId Unique ID of a requested String -

result.
> result Task delivery result. List -
>> plantCode Plant DN. String -
>> status Status of the task String RUNNING: The

delivered to the plant. task delivered to
the plant is
running.
FAIL: The task
fails to deliver to
the plant.
>> message Delivery result description. String -
Example
Request example (The first task is set to maximumSelfConsumption and the
second task is set to TOU.):
{
"tasks":[
{
"operationMode":"maximumSelfConsumption"
},
{
"operationMode":"TOU",
"redundantPVEnergyPriority":"fedToGridPreference",
"allowedAcChargePower":10,
"chargingAndDischargingTimeWindow":[
{
"startTime":"00:00",
"endTime":"02:00",
"chargeOrDischarge":"charge",
"repeat":[
2,
3
]
},
SmartPVMS
{
"endTime":"05:00",
"repeat":[
5,
6
]
}
]
}
]
}
Response example:
{
"failCode": 2,
"success": false,
"message": "Exist no permission resources. plantCodes: [NE=123456789, NE=234567891]",
"data": null
}

{
"failCode": 2,
"success": false,
"message": "Failed to deliver the battery mode control task.",
"data": {
"taskId": null,
"result": [
{
"plantCode": "NE=123456789",
"status": "FAIL",
"message": "The input parameter is out of the valid range, operationMode in:
[maximumSelfConsumption, TOU]"
},
{
"plantCode": "NE=234567891",
"status": "FAIL",
"message": "The startTime and endTime of multiple days overlap."
}
]
}
}

{
"exceptionId":"framwork.remote.Paramerror",
"exceptionType":"ROA_EXFRAME_EXCEPTION",
"descArgs":null,
"reasonArgs":[
"tasks"
],
"detailArgs":[
"tasks size must be between 1 and 10"
],
"adviceArgs":null
}

{
"failCode": 1,
"success": true,
SmartPVMS
"message": "The battery mode task is partially delivered successfully.",

"data": {
"taskId": "5882491459219785",
"result": [
{
"plantCode": "NE=123456789",
"status": "FAIL",
"message": "The configured value is the same as the current value."
},
{
"plantCode": "NE=234567891",
"status": "RUNNING",
"message": null
}
]
}
}

{
"failCode": 0,
"success": true,
"message": "The battery mode task is delivered successfully.",
"data": {
"taskId": "2839011389499814",
"result": [
{
"plantCode": "NE=123456789",
"message": null
},
{
"plantCode": "NE=234567891",
"message": null
}
]
}
}
5.2.4 API for Querying a Task for Setting the Battery Working
Mode
API Description
This API is used to query the execution status of the task for setting the battery
working mode based on the task ID. Only one task can be queried at a time.
Request URL
control/battery/mode/task-info
Request Mode
HTTP method: POST
SmartPVMS
Request Parameters
Optional
taskId Unique ID of the String M

requested task, which
taskId in 5.2.3 API for
Delivering a Task for
Setting the Battery
Working Mode. The
value contains 16
characters.
Response Packet

flag. The value true or failure flag
indicates that the request
is successful, and the
value false indicates that
the request fails.
failCode Error code. Value 0 Integer -

indicates that the status
is normal. For other error
List.
message Request description. String -

When the value of
failCode is 0, the request
failure description is
returned. In other cases,
null is returned.
data Returned data for each Object -

> dispatchResult dispatchResult contains List -

the list of returned
information about
request execution,
including the following
information:
SmartPVMS

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. String FAILURE: The

When the value of status delivery fails.
is FAIL, the description of TIMEOUT: A
the plant delivery failure timeout occurs.
is returned. In other
cases, no description is BUSY: The device
returned. is busy.
INVALID: The
device is invalid.
EXCEPTION: An
exception occurs.
>> Working mode. String TOU: time of use

operationMode maximumSelfCon
sumption:
maximum self-
consumption
>> Preferred use of surplus String fedToGridPrefer-

redundantPVEner- PV power. ence: The power
gyPriority is fed to the grid
preferentially.
chargePreference:
Charging is
preferred.
>> Maximum power for Double -

allowedAcCharge- charging batteries from
Power grid (kW).
>> Charge/Discharge time List -

chargingAndDisch window.
argingTimeWindo
w
>>> startTime Start time. String Format: HH:MM
>>> endTime End time. String Format: HH:MM
SmartPVMS
>>> Charge/Discharge String Charge

chargeOrDischarg Discharge
e
>>> repeat Repeated date. List 1: Monday

2: Tuesday
3: Wednesday
4: Thursday
5: Friday
6: Saturday
7: Sunday
> startTime Time when a task is String 2020-02-06T00:00

received, including the :00+08:00
time zone information.
> endTime Time when a task is String 2020-02-06T00:00

completed, including the :00+08:00
null is returned.
Example
Request example:
{
"taskId": "3051190140256431"
}
Response examples:
{
"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
}
SmartPVMS
Example 3: The returned task status is RUNNING.

{
"failCode": 0,
"success": true,
"message": "The battery mode task status queried successfully.",
"data": {
"dispatchResult": [
{
"plantCode": "NE=234567891",
"message": null,
"operationMode": "TOU",
"redundantPVEnergyPriority": "fedToGridPreference",
"allowedAcChargePower": 10,
"chargingAndDischargingTimeWindow": [
{
"chargeOrDischarge": "charge",
"repeat": [
2,
3
],
"startTime": "00:00",
"endTime": "02:00"
},
{
"repeat": [
5,
6
],
"endTime": "05:00"
}
]
}
],
"startTime": "2024-02-29T23:02:49+08:00",
"endTime": null
}
}
Example 4: The returned task status is FAIL.

{
"failCode": 0,
"success": true,
"data": {
"dispatchResult": [
{
"plantCode": "NE=234567891",
"status": "FAIL",
"message": "TIMEOUT",
{
"repeat": [
2,
3
],
"endTime": "02:00"
},
{
"repeat": [
SmartPVMS
5,
6
],
"endTime": "05:00"
}
]
}
],
"startTime": "2024-02-29T23:02:49+08:00",
"endTime": "2024-02-29T23:02:55+08:00"
}
}
Example 5: The returned task status is SUCCESS.

{
"failCode": 0,
"success": true,
"data": {
"dispatchResult": [
{
"plantCode": "NE=234567891",
"status": "SUCCESS",
"message": null,
{
"repeat": [
2,
3
],
"endTime": "02:00"
},
{
"repeat": [
5,
6
],
"endTime": "05:00"
}
]
}
],
"startTime": "2024-02-29T23:02:49+08:00",
"endTime": "2024-02-29T23:02:55+08:00"
}
}
5.2.5 API for Delivering a Task for Setting Battery Parameters

API Description
This API is used to deliver the task for setting plant-level energy battery
parameters (end-of-charge SOC, end-of-discharge SOC, maximum charge power,
and maximum discharge power) based on plant DNs. A task supports a maximum
of 10 plants. Different parameters can be delivered to each plant.
SmartPVMS
Request URL
control/battery/configuration/async-task
Request Mode
HTTP method: POST
Request Parameters
Optional
tasks List of battery List M

parameter setting
tasks. A task can be
delivered to a
at a time.
> batteryConfigur- Valid parameters for Object M

ationInfo setting battery
parameters.
>> End-of-charge SOC Double Optional (At least

endOfChargeSoc (unit: %). one of the four
Value range: [90.0, parameters must
100.0] be set.)
>> End-of-discharge SOC Double

endOfDischargeSo (unit: %).
c Value range: [0.0,
20.0]
>> Maximum charge Integer

maximumChargeP power (unit: W).
ower Value range: [0, upper
limit of maximum
charge power]
If the delivered
maximum charge
power is greater than
the upper limit of the
maximum charge
power, the upper limit
is used by default.
SmartPVMS

Optional
>> Maximum discharge Integer

maximumDischar power (unit: W).
gePower Value range: [0, upper
limit of maximum
discharge power]
If the delivered
maximum discharge
power is greater than
the upper limit of the
maximum discharge
power, the upper limit
is used by default.
NOTICE
calling this API.
● Battery parameters cannot be set for LG batteries.
● When the battery is disconnected, the parameter setting task cannot be
delivered to the battery.
Response Packet

true: The request
succeeded.


returned content.

SmartPVMS

result.

the plant is
running.
FAIL: The task
fails to deliver to
the plant.
Example
Request example:
{
"tasks": [
{
"batteryConfigurationInfo": {
"endOfDischargeSoc" : 18,
"endOfChargeSoc": 98,
"maximumDischargePower": 48,
"maximumChargePower": 22
}
},
{
"endOfDischargeSoc" : 18
}
},
{
"endOfChargeSoc": 98
}
},
{
"maximumDischargePower": 48,
"maximumChargePower": 22
}
}
]
}
Response examples:
SmartPVMS
{
"failCode": 2,
"success": false,
"message": "Exist no permission plants, plantCodes: [NE=45111870, NE=56433603]"
}

{
"failCode": 2,
"success": false,
"message": "Failed to deliver the battery configuration task.",
"data": {
"result": [
{
"status": "FAIL",
"message": "Signal dispensing happened error."
}
]
}
}

{
"descArgs": null,
"reasonArgs": [
"tasks"
],
"detailArgs": [
],
"adviceArgs": null
}

{
"failCode": 1,
"success": true,
"message": "The battery configuration task is partially delivered successfully.",
"data": {
"taskId": "1276820029354826",
"result": [
{
"status": "FAIL",
"message": "No resource permission."
},
{
"status": "RUNNING"
}
]
}
}

{
"failCode": 0,
"success": true,
"message": "The battery configuration task is delivered successfully.",
"data": {
"taskId": "6033150147370043",
"result": [
{
SmartPVMS
"status": "RUNNING"
}
]
}
}
5.2.6 API for Querying a Task for Setting Battery Parameters
API Description
This API is used to query the execution status of the task for setting the battery
parameters based on the task ID. Only one task can be queried at a time.
Request URL
control/battery/configuration/task-info
Request Mode
HTTP method: POST
Request Parameters
Optional

Delivering a Task for
Setting Battery
Parameters. The value
contains 16 characters.
Response Packet

the request fails.
SmartPVMS

List.

When the value of
null is returned.


information about
request execution,
information:

the plant is
running.
SUCCESS: The
task is
successfully
delivered to the
plant.
FAIL: The task
fails to deliver to
the plant.

returned. is busy.
INVALID: The
device is invalid.
EXCEPTION: An
exception occurs.
SmartPVMS
>> Valid parameters for Object -

batteryConfigura- setting battery
tionInfo parameters.
>>> End-of-charge SOC. Double -

endOfChargeSoc
>>> End-of-discharge SOC. Double -

endOfDischargeS
oc
>>> Maximum charge power. Integer -

maximumChargeP
ower
>>> Maximum discharge Integer -

maximumDischar power.
gePower


null is returned.
Example
Request example:
{
"taskId": "3051190140256431"
}
Response examples:
{
"failCode": 20620,
"success": false,
"data": null
}

{
"descArgs": null,
"reasonArgs": [
"taskId"
SmartPVMS
],
"detailArgs": [
],
"adviceArgs": null
}

{
"failCode": 0,
"success": true,
"message": "The battery configuration task status queried successfully.",
"data": {
"dispatchResult": [
{
"message": null,
"endOfChargeSoc": 91.2,
"endOfDischargeSoc": 11.0,
"maximumChargePower": 59,
"maximumDischargePower": 48
}
}
],
"startTime": "2024-02-29T18:49:42+08:00",
"endTime": null
}
}

{
"failCode": 0,
"success": true,
"data": {
"dispatchResult": [
{
"status": "FAIL",
"message": "TIMEOUT",
}
}
],
"startTime": "2024-02-29T15:49:45+08:00",
"endTime": "2024-02-29T17:17:18+08:00"
}
}

{
"failCode": 0,
"success": true,
"data": {
"dispatchResult": [
{
"message": null,
SmartPVMS
}
}
],
"startTime": "2024-02-29T18:01:06+08:00",
"endTime": "2024-02-29T18:06:18+08:00"
}
}
5.2.7 API for Delivering an Inverter Active Power Setting Task

API Description
This API is used to deliver the inverter active power setting tasks at the plant level.
A task supports a maximum of 10 plants. Different parameters can be delivered to
each plant.
The networking of a single controller (Dongle, EMMA, distributed SmartLogger,
and direction connection of inverters) in a plant is supported. The active power
can be controlled in two modes: unlimited and limited feed-in (kW).
Request URL
control/active-power-control/async-task
Request Mode
HTTP method: POST
Request Parameters
Optional
tasks List of the tasks for List M

setting the battery
working mode. A task
can be delivered to a
at a time.
SmartPVMS

Optional
> controlMode Active power control String M

mode.
0: unlimited
6: limited feed-in (kW)
to Unlimited, the
output power of the
inverter is not limited
and the inverter can
connect to the grid at
the rated power.
> controlInfo Parameter for setting Object O

the active power. If controlMode is
set to 6, you can
set this parameter
to set the active
power.
If controlMode is
set to 0, ignore
this parameter.
SmartPVMS

Optional
>> Maximum grid feed-in Double O

maxGridFeedInPo power (kW).
wer 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]
It specifies the
maximum active
power transmitted
from the grid-
connection point to
the power grid.
>> Limitation mode. String O

limitationMode 0: total power
1: single-phase power
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.
SmartPVMS
NOTICE
calling this API.
● For a PV plant, if controlMode is set to 0, controlInfo will be ignored during
task delivery.
● When the SmartLogger is used, SmartLogger (devTypeId = 2) and the
distributed SmartLogger (devTypeId = 63) are distinguished. The devTypeId
can be queried in 5.1.1.2 Device List API. The maximum grid feed-in power of
the SmartLogger falls in the range of [-1000.000, 5000.000], and that of the
distributed SmartLogger falls in the range of [-1000.000, 50000.000].
● For a plant where SmartLogger is used, if controlMode is set to 6, Start
control is set to Yes by default after a task is delivered.
● When the controller in the plant is disconnected, the active power setting task
cannot be delivered to the plant.
Response Packet

true: The request
succeeded.


returned content.


result.
SmartPVMS

the plant is
running.
FAIL: The task
fails to deliver to
the plant.
Example
Example request (The active power control mode of the first task is Unlimited,
and that of the second task is Limited feed-in (kW).):
{
"tasks":[
{
"controlMode":"0"
},
{
"controlMode":"6",
"controlInfo":{
"maxGridFeedInPower":53,
"limitationMode":"1"
}
}
]
}
Response examples:
{
"failCode": 2,
"success": false,
"message": "Exist no permission resources. plantCodes: [NE=123456789, NE=234567891]",
"data": null
}

{
"failCode": 2,
"success": false,
"message": "Failed to deliver the active power control task.",
"data": {
"taskId": null,
"result": [
{
"plantCode": "NE=123456789",
"status": "FAIL",
"message": "The input parameter is out of the valid range, limitationMode in: [0, 1]"
},
{
"plantCode": "NE=234567891",
"status": "FAIL",
SmartPVMS

}
]
}
}

{
"descArgs": null,
"reasonArgs": [
"tasks"
],
"detailArgs": [
],
"adviceArgs": null
}

{
"failCode": 1,
"success": true,
"message": "The active power control task is partially delivered successfully.",
"data": {
"taskId": "1556481834749924",
"result": [
{
"plantCode": "NE=123456789",
"status": "FAIL",
},
{
"plantCode": "NE=234567891",
"message": null
}
]
}
}

{
"failCode": 0,
"success": true,
"message": "The active power control task is delivered successfully.",
"data": {
"taskId": "8193701385705709",
"result": [
{
"plantCode": "NE=123456789",
"message": null
},
{
"plantCode": "NE=234567891",
"message": null
}
]
}
}
SmartPVMS
5.2.8 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.
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
Optional

Delivering an Inverter
Active Power Setting
Task. The value contains
16 characters.
Response Packet

the request fails.

List.
SmartPVMS

When the value of
null is returned.


information about
request execution,
information:

the plant is
running.
SUCCESS: The
task is
successfully
delivered to the
plant.
FAIL: The task
fails to deliver to
the plant.

returned. is busy.
INVALID: The
device is invalid.
EXCEPTION: An
exception occurs.
>> controlMode Active power control String 0: unlimited

mode. 6: limited feed-in
(kW)
SmartPVMS
>> controlInfo Parameter for setting the Object This parameter is

active power. returned when
controlMode is
set to 6.
>>> Maximum grid feed-in Double The value range

maxGridFeedInPo power (kW). of this parameter
wer It specifies the maximum is related to the
active power transmitted controller in the
from the grid-connection plant. The value
point to the power grid. 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]
>>> Limitation mode. String 0: total power

limitationMode Total power: controls the 1: single-phase
total power at the grid- power
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.

SmartPVMS

null is returned.
Example
Request example:
{
"taskId": "3051190140256431"
}
Response examples:
{
"failCode": 20620,
"success": false,
"data": null
}

{
"descArgs": null,
"reasonArgs": [
"taskId"
],
"detailArgs": [
],
"adviceArgs": null
}

{
"failCode": 0,
"success": true,
"message": "The active power control task status queried successfully.",
"data": {
"dispatchResult": [
{
"plantCode": "NE=234567891",
"controlMode": "6",
"message": null,
"controlInfo": {
"maxGridFeedInPower": 53,
"limitationMode": "1"
}
}
],
"startTime": "2024-03-07T09:36:13+08:00",
"endTime": null
SmartPVMS
}
}

{
"failCode": 0,
"success": true,
"data": {
"dispatchResult": [
{
"plantCode": "NE=234567891",
"controlMode": "6",
"status": "FAIL",
"message": "FAILURE",
"controlInfo": {
}
}
],
"startTime": "2024-03-07T09:36:13+08:00",
"endTime": "2024-03-07T09:36:23+08:00"
}
}

{
"failCode": 0,
"success": true,
"data": {
"dispatchResult": [
{
"plantCode": "NE=234567891",
"controlMode": "6",
"message": null,
"controlInfo": {
}
}
],
"startTime": "2024-03-07T09:38:58+08:00",
"endTime": "2024-03-07T09:38:58+08:00"
}
}
SmartPVMS
NBI Reference 6 References
6 References
6.1 Error Code List

Code
1 20001 The third-party system ID does not exist.
2 20002 The third-party system is forbidden.
3 20003 The third-party system has expired.
4 20004 The server is abnormal.
5 20005 The device ID cannot be empty.
6 20006 Some devices do not match the device type.
7 20007 The system does not have the desired power plant
resources.
8 20008 The system does not have the desired device resources.
9 20009 Queried KPIs are not configured in the system.
10 20010 The plant list cannot be empty.
11 20011 The device list cannot be empty.
12 20012 The query time cannot be empty.
13 20013 The device type is incorrect. The API does not support
operations on some devices.
14 20014 A maximum of 100 plants can be queried at a time.
15 20015 A maximum of 100 plants can be queried at a time.
16 20016 A maximum of 100 devices can be queried at a time.
SmartPVMS

Code
18 20018 A maximum of 10 devices can be operated at a time.
19 20019 The switch type is incorrect. 1 and 2 indicate switch-on and

switch-off respectively.
20 20020 The upgrade package corresponding to the device version

cannot be found.
21 20021 The upgrade file does not exist.
22 20022 The upgrade records of the devices in the system are not
found.

● For details about how to locate the fault in the OAuth
Connect scenario, see 8.1.4 Why Does the Northbound
API Return Error Code 401?
● For details about how to check the API account access
scenario, see 8.2.5 Why Does the Northbound API
Return Error Code 401?
26 20023 The query start time cannot be later than the query end
time.
27 20024 The language cannot be empty.
28 20025 The language parameter value is incorrect.
29 20026 Only data of the latest 365 days can be queried.
30 20027 The query time period cannot span more than 31 days.
31 20028 The system does not have related user information.
32 20029 Invalid user information.
33 20030 Failed to create the I-V curve diagnosis task.
34 20034 The task does not exist.
35 20035 MPPT devices do not support backfeed current.
36 20036 The backfeed current duration of the MPPT device exceeds

the maximum limit.
37 20037 The backfeed current of the MPPT device is out of range.

The allowed value is (0, 15].
38 20038 In the input parameters, the authorization code list is

empty (null), or the number of authorization codes is out
of range. The allowed range is [0, 1000].
SmartPVMS

Code
39 20039 In the input parameters, the DOD value is out of range.

The allowed range is [0, 100].
40 20040 The charge/discharge switch parameter value is invalid.
41 20041 The control type cannot be empty for forced charge and
discharge.
42 20042 The target SOC for charge/discharge is empty or invalid.
43 20043 The charge/discharge duration is empty or invalid.
44 20044 The unique ID of a charge/discharge task cannot be empty.
45 20045 Unauthorized PV plants exist in the input parameters.
46 20046 Unauthorized PV plants exist in the input parameters.
47 20047 The forced charge/discharge power in the input parameters

is invalid.
48 20048 Duplicate charge and discharge task ID.
49 20049 Failed to deliver the charging and discharging task.
50 20050 The charging and discharging task query parameter does

not exist.
51 20051 Failed to set the battery DOD.
52 20055 The plant list and device list parameters cannot be empty
at the same time.
53 20056 Resources that are not authorized by the owner exist.
54 20116 The inverter control parameter is incorrect. (The number of

PV plants is greater than 100 or equal to 0, or the total
number of inverters in the PV plants is greater than 200 or
equal to 0.)
55 20200 The system is busy. Try again later.
56 20400 ● The API account name or password is incorrect.

● The API account is locked.
● The password has expired.
● The number of online sessions reaches the upper limit.
● The third-party system ID does not exist.
57 20403 The API account login is restricted.
58 20604 The time parameter is incorrect. The start time cannot be

later than or equal to the end time.
SmartPVMS

Code
59 20605 The time parameter is incorrect. The time parameter

contains a negative value.
60 20606 If only the start time is entered and the end time is empty,
the start time cannot be later than or equal to the current
time.
61 20607 The task list is empty.
62 20608 Duplicate plant IDs exist in the input parameters.
63 20609 The plant networking is abnormal.
64 20610 The plant does not support default configuration.
65 20611 The values of input parameters exceed the valid range.
66 20612 The value of an input parameter is empty.
67 20613 The default setting task fails to be sent for all plants.
68 20614 The network communication is abnormal.
69 20615 The same task is being executed in the current plant.
70 20616 The task ID is empty.
71 20617 The query result of the default plant setting task is empty.
72 20618 The number of API calls has reached the maximum

number per API account per day.
73 20619 The number of task IDs exceeds 100.
74 20620 The task ID does not exist.
75 20621 The resource is not authorized by the owner.
76 20622 The plant DN is invalid or the account does not have

permission on the plant.
77 20623 The plant DN does not belong to the company or

subsidiary of the owner.
78 20624 The owner has been bound to the plant.
79 20625 It is not allowed to bind a plant whose sharing request has

been accepted by the owner.
80 20626 Failed to bind the plant due to an internal error.
81 21000 The basic information for the plant creation is empty.
82 21001 The plant name is empty or in an incorrect format.
83 21002 The plant type is empty or incorrect.
SmartPVMS

Code
84 21003 The grid connection time must be a positive number.
85 21004 The format of the contact name is incorrect.
86 21005 The format of the contact information is incorrect.
87 21006 The C&I plant and utility plant cannot be EV-charger-only

plants.
88 21007 The grid connection time cannot be set for an EV-charger-

only plant.
89 21008 The string capacity cannot be set for an EV-charger-only

plant.
90 21009 The electricity price cannot be set for an EV-charger-only

plant.
91 21010 >pureChange can only be set to 0 or 1.
92 21011 The plant name already exists.
93 22000 No related data of connected devices was found.
94 22001 The device registration code is empty.
95 22002 The device is an unauthorized device.
96 22003 The device registration code is incorrect.
97 22004 You will be locked out for 5 minutes due to five

consecutive incorrect registration codes.
98 22005 Devices other than chargers are connected to an EV-

charger-only plant.
99 22006 The device SN is empty.
100 22007 The device has been bound to another plant.
101 22008 The parameters of connected devices are empty.
102 22009 iSitePower-M cannot be connected.
103 22010 The plant with the iSitePower-M cannot connect to other
devices.
104 23000 The plant-level string capacity and PV-level string capacity
cannot be empty at the same time.
105 23001 The format of the plant string capacity is incorrect.
106 23002 The inverter SN does not exist.
107 23003 The number of inverter SNs is incorrect.
108 23005 The inverter PV string capacity is incorrectly set.
SmartPVMS

Code
109 23006 The inverter SN or PV string capacity is empty.
110 23007 The quantity in the inverter PV string capacity setting is

incorrect.
111 24000 The electricity price must be a positive number.
112 24001 The electricity price date settings must cover a complete
year and without overlapping.
113 24002 The electricity price time segments must cover 24 hours of
the day without overlapping.
114 24003 The date range is invalid.
115 24004 The time range is invalid.
116 24005 The company electricity price is empty.
117 24006 >useCompanyPrice can only be set to 0 or 1.
118 25000 Additional information configuration is empty.
119 25001 The area code is empty or in an incorrect format.
120 25002 The plant address is empty.
121 25003 The longitude and latitude are empty or in incorrect

format.
122 25004 The safe running time of the plant must be a positive
number.
123 25005 The time zone is empty or the format is incorrect.
124 25006 loadStatus can only be set to 0 or 1.
125 25007 The plant introduction can contain a maximum of 128

characters.
126 26000 Failed to create plants.
127 26001 A maximum of 1000 plants can be created in a day.
128 26002 The company authorized by the API account does not exist.
129 26003 Failed to bind the API account to the device.
130 26004 Failed to unbind the API account from the device.
131 30001 The device ESN list cannot be empty.
132 30002 The ESNs queried at a time cannot exceed 50.
133 30003 The account cannot be empty in the input parameter.
134 30004 The value of pageNo cannot be empty.
SmartPVMS

Code
135 30005 The value of pageSize cannot be empty.
136 30006 The value of pageSize is out of range. The allowed range
is {10, 20, 30, 50, 100}.
137 30007 The values of startTime and endTime must be both

provided or empty.
138 30008 Failed to call the internal API.
139 30009 The value of taskName is empty.
140 30010 The value of dns is empty.
141 30011 The value of cleanStatus is empty or invalid.
142 30012 The value of environmentalParameters is empty or

invalid.
143 30013 The value of modulePlaneIrradiance or

moduleBackSurfaceTemperature is empty when
environmentalParameters is set to 1.
144 30014 The value of scanPointNum must be set to 128.
145 30015 The value of taskId is empty.
146 30016 The value of dn is empty.
147 30017 The value of dns is invalid. The number of devices exceeds
100 or devices on which the API account does not have
permission exist.
148 30018 The value of taskName is invalid (for example, null field).
149 30019 The value of moduleBackSurfaceTemperature is out of

range. The allowed range is [0.0, 100.0].
150 30020 The value of modulePlaneIrradiance is out of range. The

allowed range is [600.0, 1500.0].
151 30021 The value of pageNo is smaller than 0.
152 30022 The value of timestamp is empty.
153 30023 The command type is invalid (for example, null).
154 30024 The power supply duration is invalid.
155 30025 The MPPT list is empty.
156 30026 The value of mppts is empty.
157 30027 The number of MPPTs connected to a single inverter

exceeds the maximum limit (3), or the total number of
MPPTs in a single task exceeds the maximum limit (32).
SmartPVMS

Code
158 30028 The backfeed current input value is invalid.
159 30029 Authentication failed. The entered plant or device

parameter is invalid.
160 30030 The input parameter is incorrect.
162 30032 The time parameter is invalid. The query time segment
cannot be longer than three days.
163 30033 The task is in progress.
164 30034 The returned list is empty.
165 30035 The task is to be executed.
166 30036 The task has been canceled.
167 30037 The number of reservation tasks exceeds the maximum

(10).
168 30040 The PV string is not configured.
169 1 The task is partially successful.
170 2 The task fails.
6.2 Old Policy for API Flow Control

The following table describes the flow control of unrestricted northbound APIs.
Call APIs properly based on the flow control description.
API API Name Flow Control Description

Label
Basic Plant list Maximum number of API calls for each API account:
data 10/minute
Device list Maximum number of API calls for each API account:
10/minute
Monit Real-time Maximum number of API calls for each API account:
oring plant data 30/minute
data
Real-time Maximum number of API calls for each API account:
device data 10/minute
Historical Maximum number of API calls for each API account:

device data 1/minute
SmartPVMS
API API Name Flow Control Description

Label
Alarm Querying Maximum number of API calls for each API account:
data active alarms 10/minute
Repor Hourly plant Maximum number of API calls for each API account:
t data data 10/minute
Daily plant Maximum number of API calls for each API account:
data 10/minute
Monthly plant Maximum number of API calls for each API account:
data 10/minute
Yearly plant Maximum number of API calls for each API account:
data 10/minute
Daily device Maximum number of API calls for each API account:
data 10/minute
Monthly device Maximum number of API calls for each API account:
data 10/minute
Yearly device Maximum number of API calls for each API account:
data 10/minute
Contr Delivering Maximum number of API calls for each API account:
ol API battery charge/ 10/minute
discharge tasks
Querying Maximum number of API calls for each API account:

battery charge/ 10/minute
discharge tasks
6.3 Time Zone Code List

Time Details Time Details Time Details Time Details
Zone Zone Zone Zone
54 (UTC-1 102 (UTC-0 13 (UTC 36 (UTC

2:00) 3:00) +03:00) +08:00)
Internat Araguaí Minsk Singapo
ional na re
Date
Line
West
SmartPVMS

Zone Zone Zone Zone
85 (UTC-1 103 (UTC-0 77 (UTC 37 (UTC

1:00) 3:00) +03:00) +08:00)
Coordin Greenla Ankara Perth
ated nd
Univers
al
Time-1
1
55 (UTC-1 104 (UTC-0 17 (UTC 38 (UTC

0:00) 3:00) +03:00) +08:00)
Hawaii Punta Baghda Taipei
Arenas d
86 (UTC-1 105 (UTC-0 19 (UTC 39 (UTC

0:00) 3:00) +03:00) +08:00)
Aleutia Salvado Kuwait, Irkutsk
n r Riyadh
Islands
87 (UTC-0 106 (UTC-0 20 (UTC 78 (UTC

9:30) 3:00) +03:00) +08:00)
Marque Saint Mosco Kuala
sas Pierre w, Saint Lumpur
Islands and Petersb
Miquel urg
on
56 (UTC-0 107 (UTC-0 21 (UTC 134 (UTC

9:00) 2:00) +03:00) +08:00)
Alaska Coordin Nairobi Ulaanb
ated aatar
Univers
al
Time-2
88 (UTC-0 84 (UTC-0 79 (UTC 135 (UTC

9:00) 1:00) +03:00) +08:45)
Coordin Azores Riyadh Eucla
ated
Univers
al
Time-9
57 (UTC-0 108 (UTC-0 119 (UTC 40 (UTC

8:00) 1:00) +03:00) +09:00)
Tijuana Cape Istanbul Osaka,
Verde Sappor
o,
Tokyo
SmartPVMS

Zone Zone Zone Zone
58 (UTC-0 4 (UTC) 22 (UTC 41 (UTC

8:00) Coordin +03:30) +09:00)
Pacific ated Tehran Seoul
Time Univers
(United al Time
States
and
Canada
)
89 (UTC-0 1 (UTC 18 (UTC 42 (UTC

8:00) +00:00) +04:00) +09:00)
Baja Dublin, Tbilisi Yakutsk
Californ Edinbur
ia gh,
Lisbon
90 (UTC-0 3 (UTC 23 (UTC 136 (UTC

8:00) +00:00) +04:00) +09:00)
Coordin Monrov Muscat Chita
ated ia,
Univers Reykjav
al ik
Time-8
59 (UTC-0 82 (UTC 24 (UTC 137 (UTC

7:00) +00:00) +04:00) +09:00)
Chihua London Yerevan Pyongy
hua, La ang
Paz,
Mazatla
n
60 (UTC-0 109 (UTC 25 (UTC 43 (UTC

7:00) +00:00) +04:00) +09:30)
Mounta São Baku Adelaid
in Time Tomé e
(United
States
and
Canada
)
61 (UTC-0 2 (UTC 83 (UTC 44 (UTC

7:00) +01:00) +04:00) +09:30)
Arizona Casabla Abu Darwin
nca Dhabi
SmartPVMS

Zone Zone Zone Zone
62 (UTC-0 5 (UTC 120 (UTC 45 (UTC

6:00) +01:00) +04:00) +10:00)
Central Berlin Astrakh Brisban
Standar an, e
d Time Ulyanov
(United sk
States
and
Canada
)
63 (UTC-0 6 (UTC 121 (UTC 46 (UTC

6:00) +01:00) +04:00) +10:00)
Central Belgrad Volgogr Guam,
Americ e, ad Port
a Bratisla Moresb
va, y
Budape
st,
Ljubljan
a,
Prague
91 (UTC-0 7 (UTC 122 (UTC 47 (UTC

6:00) +01:00) +04:00) +10:00)
Easter Brussels Port Hobart
Island , Louis
Copenh
agen,
Madrid
92 (UTC-0 8 (UTC 123 (UTC 48 (UTC

6:00) +01:00) +04:00) +10:00)
Guadal Sarajev Saratov Canberr
ajara, o, a,
Mexico Skopje, Melbou
City, Warsaw rne,
Monter , Sydney
rey Zagreb
93 (UTC-0 74 (UTC 124 (UTC 138 (UTC

6:00) +01:00) +04:00) +10:00)
Saskatc Paris Izhevsk, Vladivo
hewan Samara stok
SmartPVMS

Zone Zone Zone Zone
64 (UTC-0 80 (UTC 26 (UTC 139 (UTC

5:00) +01:00) +04:30) +10:30)
Bogotá, Amster Kabul Lord
Lima, dam, Howe
Quito, Bern, Island
Rio Stockho
Branco lm,
Vienna
65 (UTC-0 81 (UTC 27 (UTC 49 (UTC

5:00) +01:00) +05:00) +11:00)
Eastern Rome Ashgab Magad
Time at, an
(United Tashken
States t
and
Canada
)
94 (UTC-0 110 (UTC 28 (UTC 140 (UTC

5:00) +01:00) +05:00) +11:00)
Havana West Islamab Bougai
Africa ad, nville
Time Karachi Island
95 (UTC-0 9 (UTC 125 (UTC 141 (UTC

5:00) +02:00) +05:00) +11:00)
Haiti Amman Kyzylor Norfolk
da Island
96 (UTC-0 10 (UTC 126 (UTC 142 (UTC

5:00) +02:00) +05:00) +11:00)
Chetum Harare Yekateri Chokur
al nburg dakh
97 (UTC-0 11 (UTC 29 (UTC 143 (UTC

5:00) +02:00) +05:30) +11:00)
Turks Helsinki Chennai Sakhali
and , Kyiv, , n
Caicos Riga, Kolkata,
Islands Sofia, Mumba
Tallinn, i, New
Vilnius Delhi
SmartPVMS

Zone Zone Zone Zone
98 (UTC-0 12 (UTC 127 (UTC 144 (UTC

5:00) +02:00) +05:30) +11:00)
Indiana Cairo Sri Solomo
(Easter Jayawar n
n Time) denepu Islands,
ra Kotte New
Caledon
ia
66 (UTC-0 14 (UTC 30 (UTC 50 (UTC

4:00) +02:00) +05:45) +12:00)
Caracas Windho Kathma Aucklan
ek ndu d,
Welling
ton
67 (UTC-0 15 (UTC 32 (UTC 51 (UTC

4:00) +02:00) +06:00) +12:00)
Atlantic Athens, Dhaka Anadyr,
Time Buchare Petropa
(Canad st vlovsk-
a) Kamcha
tsky
68 (UTC-0 16 (UTC 128 (UTC 52 (UTC

4:00) +02:00) +06:00) +12:00)
Guyana Jerusale Astana Fiji
m
69 (UTC-0 75 (UTC 129 (UTC 145 (UTC

4:00) +02:00) +06:00) +12:00)
Santiag Cape Omsk Coordin
o Town ated
Univers
al Time
+12
99 (UTC-0 111 (UTC 33 (UTC 146 (UTC

4:00) +02:00) +06:30) +12:45)
Cuiabá Beirut Yangon Chatha
m
Islands
100 (UTC-0 112 (UTC 31 (UTC 53 (UTC

4:00) +02:00) +07:00) +13:00)
Georget Damasc Novosib Tongata
own, La us irsk pu
Paz,
Manaus
, San
Juan
SmartPVMS

Zone Zone Zone Zone
101 (UTC-0 113 (UTC 34 (UTC 147 (UTC

4:00) +02:00) +07:00) +13:00)
Asunció Tripoli Bangko Nukual
n k, ofa
Hanoi,
Jakarta
70 (UTC-0 114 (UTC 130 (UTC 148 (UTC

3:30) +02:00) +07:00) +13:00)
Newfou Harare, Barnaul Samoa
ndland Pretoria ,
Gorno-
Altaysk
71 (UTC-0 115 (UTC 131 (UTC 149 (UTC

3:00) +02:00) +07:00) +13:00)
Brasilia Chisina Khovd Coordin
u ated
Univers
al Time
+13
72 (UTC-0 116 (UTC 132 (UTC 150 (UTC

3:00) +02:00) +07:00) +14:00)
Cayenn Kalining Krasnoy Kiritima
e, rad arsk ti Island
Fortalez
a
73 (UTC-0 117 (UTC 133 (UTC

3:00) +02:00) +07:00)
Montev Gasha, Tomsk
ideo Hebron
76 (UTC-0 118 (UTC 35 (UTC

3:00) +02:00) +08:00)
Buenos Khartou Beijing
Aires m
SmartPVMS
6.4 Exception Code List

No. Status Description Example
Code
1 400 Parameter
verification
failed.
2 500 System
error.
SmartPVMS
NBI Reference 7 Best Practices
7 Best Practices
7.1 Obtaining a Token

A token is required for the API account created by the administrator to access
northbound data. This section describes how to obtain a valid token.
The method and precautions for calling a northbound login API in HTTPS mode
are as follows:
1. Method: POST
2. URL: https://xxx.fusionsolar.huawei.com/thirdData/login (Enter the actual
URL of the NMS.)
3. Request body: API account name and password (Use systemCode instead of
password as the password parameter.)
4. HTTP status code: The response status code 200 indicates that the API is
successfully called.
5. Response body: If failCode is 0, the API login is successful.
6. Header: After successful login, find the xsrf-token field in the response header
and its value is the credential information required for accessing northbound APIs.
NOTICE
1. The validity period of a token is 30 minutes. If you continuously call a token

within 30 minutes, the validity period will be automatically extended. Therefore,
you must keep the token secure carefully to prevent disclosure.
2. An account can have only one online session. Repeated login will invalidate the
generated token. If a token is invalid, check to eliminate the repeated login issue.
SmartPVMS
7.2 Querying the Plant List

Before querying the plant information, you need to query the plants on which the
current API account has the permission as follows:
1. Method: POST
2. URL: https://xxx.fusionsolar.huawei.com/thirdData/stations (Enter the actual
URL of the NMS.)
3. Request body: Enter the page No. of the plant list API. The following example
queries page No. 1. By default, a maximum of 100 records can be returned for
each page.
4. XSRF-TOKEN: Enter the token information obtained through the /thirdData/
login API.
6. Response body: If failCode is 0, the query is successful.
7. Response body: The data field indicates the information about the plants that
you have permission to query.
SmartPVMS
NOTE
Expand the details in the data field to obtain the basic information about a plant, including
plantCode, the unique identifier for data query. You can save the information for future
use.
7.3 Querying the Real-Time Plant Data

You can query the real-time and historical data and reports of plants. The method
to obtain real-time plant data is as follows:
1. Method: POST
2. URL: https://xxx.fusionsolar.huawei.com/thirdData/getStationRealKpi (Enter

the actual URL of the NMS.)
3. Request body: Enter the value in plantCode obtained from the plant list API. If
multiple values are used, separate them using commas (,). A maximum of 100
values are supported.
4. XSRF-TOKEN: Enter the token information obtained through the /thirdData/

login API.
7. Response body: The queried real-time plant data is shown in the data field.
SmartPVMS
7.4 Using the Access Token to Query the Real-Time

Plant Data
The method for querying real-time plant data in OAuth Connect mode is the same
as that using an API account. The OAuth Connect mode is used as an example.
1. Method: POST
2. URL: https://xxx.fusionsolar.huawei.com/thirdData/getStationRealKpi (Enter
the actual URL of the NMS.)
3. Request body: Enter the value in plantCode obtained from the plant list API. If
multiple values are used, separate them using commas (,). A maximum of 100
values are supported.
4. Authorization: The value of Authorization consists of Bearer and an access
token.
7. Response body: The queried real-time plant data is shown in the data field.
SmartPVMS
7.5 Scenario-based Practices of Battery Scheduling

The following APIs are provided for setting battery charge and discharge:
● API 1: 5.2.1 API for Delivering Battery Charge and Discharge Tasks, which
is used to set forcible battery charge and discharge, including the charge and
discharge power, duration, and target SOC.
● API 2:. 5.2.3 API for Delivering a Task for Setting the Battery Working
Mode, which can be used to set the battery working mode to TOU or
maximumSelfConsumption.
Through these APIs, the following practices can be completed.
Practice 1: Scenarios Where Temporary Charge and Discharge Are Required

API 1 is used to deliver a single forcible charge and discharge task. This method is
easy to use.
Step 1 Use API 1 for forcible battery charge and discharge. The charge and discharge
power, duration, and target SOC can be set.
----End
1. The API allows users to set the target SOC and charge/discharge duration for
residential batteries.
2. API 1 does not change the original working mode of the battery. After the
task is complete, the battery continues to work in the original working mode.
Practice 2: Scenarios Where Battery Charge and Discharge Need to Be

Controlled Independently Without the Impact of Working Modes
APIs 1 and 2 are used to deliver forcible charge and discharge tasks. API 2 needs
to be called only once for setting, and only API 1 needs to be used later.
This mode is applicable to the scenario where the charge and discharge of the
battery need to be controlled independently and the working mode does not
affect charge and discharge.
SmartPVMS
Step 1 Use API 2 to set operationMode to TOU, redundantPVEnergyPriority to

fedToGridPreference (to avoid charging batteries using surplus PV energy), and
allowedAcChargePower to any valid value. Set the charge and discharge time
range to 1 minute. For example, set only one time window, set startTime to 00:05
and endTime to 00:06, set chargeOrDischarge to charge, and set the repeat date
to Monday. In this way, the working mode does not affect charge and discharge.
For example, for NE=123456789, you can deliver the setting according to the
following parameters:
{
"tasks":[
{
"operationMode":"TOU",
"redundantPVEnergyPriority":"fedToGridPreference",
"allowedAcChargePower":10,
"chargingAndDischargingTimeWindow":[
{
"endTime":"00:06",
"repeat":[
1
]
}
]
}
]
}
Step 2 Use API 1 for forcible battery charge and discharge. The charge and discharge
power, duration, and target SOC can be set.
----End
SmartPVMS
NBI Reference 8 FAQs
8 FAQs
8.1 FAQs About the OAuth Connect Mode
8.1.1 Handling the Exception Returned by Calling the

Authorization Request API
● If the following page is returned after an owner calls the authorization
request API described in Link Example of the Authorization Request API,
check whether the input client_id, redirect_uri, and response_type are
correct. For details about how to set the request parameters, see their
descriptions in Parameters of the Authorization Request API of 3.1.2.2
Initiating Authorization to a Third-party App by an Owner. If redirect_uri
contains characters such as & and redirect_uri is not URL-encoded when the
URL of the authorization request API is combined, the following page may be
returned when the authorization request API is called. In this case, perform
URL-encoding on redirect_uri. For details, see the description of RedirectUrl
in Link Example of the Authorization Request API of 3.1.2.2 Initiating
Authorization to a Third-party App by an Owner.
● If the exception "?error=invalid_scope&error_description=OAuth

%202.0%20Parameter:%20scope" is returned in the callback URL when an
owner calls the authorization request API (the scope parameter is required),
check whether the input scope parameter is correct and whether scopes are
separated by spaces.
SmartPVMS
8.1.2 Handling the Exception Returned by Calling the Token

Obtaining API
● If the following error information is returned when you call the API for
obtaining a token, check whether the value of grant_type is correct. For
details about how to configure the request parameter, see the grant_type
description in Request Parameters of the API for Obtaining Tokens of
3.1.2.3 Obtaining the Access Token of the Open API by a Third-Party App.
HTTP/1.1 400
{
"error_description": "unsupported_grant_type",
"error": "1111"
}
● If the authentication fails and the following error information is returned
when you call the API for obtaining tokens, check whether client_id and
client_secret are correct. For details about how to configure the request
parameters, see the description of client_id and client_secret in Request
Parameters of the API for Obtaining Tokens of 3.1.2.3 Obtaining the
Access Token of the Open API by a Third-Party App.
HTTP/1.1 401
{
"error": "invalid_client"
}
● If the following error information is returned when you call the API for
obtaining a token, the input parameter verification fails.
If the value of grant_type is authorization_code, check whether the
execution interval of the operations in 3.1.2.3 Obtaining the Access Token of
the Open API by a Third-Party App exceeds 5 minutes after the
authorization code is obtained in 3.1.2.2 Initiating Authorization to a Third-
party App by an Owner. If the interval exceeds 5 minutes, the authorization
code has expired. In this case, the owner needs to send an authorization
request again to obtain a new authorization code. Operations in 3.1.2.3
Obtaining the Access Token of the Open API by a Third-Party App must be
performed to obtain the access token and refresh token using the new
authentication code within 5 minutes. If the interval does not exceed 5
minutes, check whether the values of code and redirect_uri are correct. For
details about how to set the request parameters, see the description of code
and redirect_uri in the access token and refresh token request parameters
obtained using an authorization code in 3.1.2.3 Obtaining the Access Token
of the Open API by a Third-Party App.
If grant_type is refresh_token, check whether refresh_token is correct. For
details about how to configure request parameters, see refresh_token in the
request parameters for using the refresh token to obtain the access token in
3.1.2.3 Obtaining the Access Token of the Open API by a Third-Party App.
HTTP/1.1 400
{
"error_description": "invalid_grant",
"error": "1110"
}
8.1.3 Why Does the Northbound API Return Error Code 305?
If error code 305 is returned when you call a northbound API, as shown in the
following figure, the access token is invalid. That is, the owner's authorization
information cannot be parsed through the access token. The possible cause is that
SmartPVMS
the access token has expired (validity period: one hour). In this case, you need to
use the refresh token to obtain the access token again. For details, see 3.1.2.3
Obtaining the Access Token of the Open API by a Third-Party App.
If error code 401 is returned when you call a northbound API, as shown in the
following figure, you do not have sufficient access token permissions. That is, the
permission set authorized by the owner to the OAuth 2.0 client does not contain
the requested open API. In this case, the owner needs to authorize the permission
group to which the open API belongs. For details, see 3.1.2.2 Initiating
Authorization to a Third-party App by an Owner.
8.1.5 Why Does the Northbound API Return Error Code 407 or
429?
If error code 407 or 429 is returned when you call a northbound API, as shown in
the following figure, the API is called too frequently in a period of time, triggering
API flow control. See 4.1 Flow Control Policy in OAuth Connect Mode for the
flow control policies in OAuth Connect mode.
SmartPVMS
8.1.6 How Do I Obtain O&M Support When Open APIs Are

Accessed in OAuth Connect Mode?
NOTICE
Connecting to open APIs in OAuth Connect mode is for trial use only in Europe.
The following O&M support modes are available only to European customers.
Based on the interconnection status between the third-party system and

FuisonSolar SmartPVMS, two phases are involved: commissioning phase and
operation phase. The O&M support policies vary depending on the phases.
Int Phase O&M Description

erc Definition Supp
on ort
nec Polic
tio y
n
Sta
tus
Co Commission the Dedic Customers can send service requests to the

m interconnection ated Huawei service contact person or dedicated
mis between a third- supp email address. Huawei rapidly responds to and
sio party system ort handles problems in special channels.
nin and FusionSolar 1. Service contact person: regional manager/FR
g SmartPVMS.
2. Dedicated email address:
EU_DP_ServiceOperation<huaweipartners@hua
wei.com>
SmartPVMS
Op The third-party Remo Customers submit service requests through the

era system has been te hotline and obtain solutions from Huawei. In
tio interconnected techn addition, customers can perform self-service
n with FusionSolar ical O&M through online technical support
SmartPVMS and supp provided by Huawei.
is running ort 1. Hotline service: Customers contact the
properly and service contact person (frontline service
stably. manager or FR), customer service hotline
(0080033666666), or customer service email
address (eu_inverter_support@huawei.com)
and Huawei will respond to the customer
service request.
2. Remote troubleshooting: includes technical
consulting services and problem handling
services. Huawei provides a solution to the
customer based on the service request
submitted by the customer.
3. Online technical support: Customers can
access the Digital Power Smart Chatbot in
either of the following methods to obtain
product documents and technical support:
(1) Log in to https://solar.huawei.com, click
in the upper right corner, and choose Support
> Online Support.
(2) Log in to the FusionSolar app and choose
Services > Customer Service Chabot.
8.2 FAQs About the API Account Mode
8.2.1 Why Do I Fail to Create an API Account?

An administrator can create a certain number of API accounts to access open APIs.
The app permissions belong to the administrator's company. An app can be
granted multiple plant resource permissions.
If you fail to create an API account, check whether the number of created API
accounts exceeds the upper limit (five by default).
8.2.2 What Is the New or Old Flow Control Policy for

Northbound APIs?
As the number of API accounts increases, a single API account manages an
increasing number of plants and devices. To better meet user requirements, the
system updates the old flow control policy for northbound APIs and launched a
new policy. By default, new API accounts adopt the new policy. The differences
between the new and old flow control policies are as follows:
SmartPVMS
Old policy: The static flow control policy is adopted, which means that each API
account is allowed to send the same number of calling requests for one API. For
details, see 6.2 Old Policy for API Flow Control.
New policy: The dynamic flow control policy is adopted, which means that the
new policy is based on the number of resources owned by API accounts. An API
account with more plants and devices is allowed to send more API calling requests
in a period of time. For details, see 4.2 Flow Control Using the API Account.
8.2.3 Why Does the Login Fail After I Enter the Correct
Username and Password?
If the login still fails after you enter the correct username and password, try the
following steps:
Step 1 Check whether parameter names are correct.
Step 2 Check whether the API account has expired.
Step 3 Check whether the API account is disabled.
Step 4 Check whether the API account is locked. If you enter incorrect login passwords for
five consecutive times, the account will be locked.
----End
8.2.4 Why Do I Need to Log In Again When I Use the Token to

Call an API?
If you encounter this issue, try the following steps:
1. Check whether your token is not used for more than 30 minutes because the
validity period of a token is 30 minutes. If you continuously call a token within 30
minutes, the validity period will be automatically extended.
2. An account can have only one online session. Repeated login will invalidate the
generated token. If a token is invalid, check to eliminate the repeated login issue.
This error code is returned when you call the northbound API, as shown in the
following figure.
In this case, you need to check whether the API account has the permission to
access the API. You can try the following steps to check the permissions for basic
and control APIs:
SmartPVMS
Step 1 Log in to the NMS as an administrator and choose System > Company
Management > Northbound Management.
Step 2 Locate the API account and click Modify in the Operation column. On the
displayed page, check whether the corresponding APIs option is enabled.
----End
If the API you access is within the basic and control API ranges, you have not
granted the permission on the restricted APIs.
8.2.6 Why Does the Northbound API Return Error Code 407 or
429?
If error code 407 or 429 is returned when you call a northbound API, as shown in
the following figure, the API is called too frequently in a period of time, triggering
API flow control.
There are new and old policies for API accounts. For details about the new policy,
see 4.2 Flow Control Using the API Account. For details about the old policy, see
6.2 Old Policy for API Flow Control.
8.3 Why Is No Data or Only Part of Data Found When I

Call a Northbound API for Data Query?
If no data or part of data about the plant or device is found when you call the API
for accessing the northbound plant list to query data, try the following steps:
Step 1 Check whether the target plant or device exists and whether the plant or device is
bound to the corresponding OAuth 2.0 client of the API account or third-party app
by comparing the parameters returned in 5.1.1.1 Plant List API or 5.1.1.2 Device
List API.
SmartPVMS
Step 2 Find the corresponding northbound API in 5 API Reference, check whether the API
supports the target device type, and check whether the device type is correct.
Step 3 Check whether the target device is disconnected.
Step 4 If Configure Owner Authorization is enabled for the company to which the plant
or device belongs and the company has been bound to the OAuth 2.0 client of the
API account or third-party app, as shown in the following figure, choose Plants >
Operation. In the Set Permissions dialogue box, check whether API Access is
enabled.
Owners can log in to the FusionSolar app, choose Me > Plant management on
the toolbar at the bottom, select a plant, choose Set Permissions, and check
whether to enable API Access.
SmartPVMS
Figure 8-1
SmartPVMS
Figure 8-2
Figure 8-3
----End
SmartPVMS
8.4 How Long Is the Data Collection Time of the API

for Real-Time Plant Data?
The time for the API to return collected data is usually 5 minutes.
8.5 Why Do the Hourly/Daily/Monthly/Yearly Data APIs

of the Plant or the Daily/Monthly/Yearly Data APIs of
the Device Sometimes Return Small Data Value?
When you call the hourly/daily/monthly/yearly data APIs of the plant or the daily/
monthly/yearly data APIs of the device to query data, the data value returned by
the APIs is small.
The issue occurs because data queries through these APIs are based on reports,
but there is a delay in summarizing data from reports.
8.6 Why Do I Fail to Query Historical Alarms by Calling

the Alarm Query API?
Currently, this API can be used to query only the current (active) alarm
information of the device.
8.7 Why Does the /thirdData/getStationList API Return

Error Code 401 or 402?
The reason is that APIs in Plant List API have been pre-offline. We provide the new
APIs for replacement (see 5.1.1.1 Plant List API). You are advised to replace APIs
in Plant List API with APIs in 5.1.1.1 Plant List API.
8.8 Why Is the Plant ID Returned by the Plant List

Inconsistent with That Displayed on the SmartPVMS?
During the evolution of the management system, the plant IDs change. To ensure
user experience of existing open API users, the management system is compatible
with the plant IDs of these open API users.
8.9 Why Do the Plant IDs Returned for the Same Plant
Vary Depending on Open API Users?
During the evolution of the management system, the plant IDs change. To ensure
user experience of existing open API users, the management system is compatible
with the plant IDs of these open API users.
SmartPVMS
If you have multiple open API accounts applied for in different periods, their plant
IDs may be different.
8.10 How Do I Compare and Obtain Plants That Are

Not Returned by the Plant List API?
If you find that the number of returned plants decreases when you call the API for
accessing the northbound plant list, perform the following steps to obtain the
plant information that is not returned:
Step 1 Log in to the management system as a company administrator and choose
System > Company Management > Northbound Management to view the
company bound to the API account.
Figure 8-4 If the page shown in the following figure is displayed, view the
company bound to the API account in the plant list API.
Figure 8-5 If the page shown in the following figure is displayed, view the
company bound to the API account in the selected company area.
Step 2 Choose Plants > Plant Management, select the company bound to the API
account, and click Export to obtain all the plants of the company. If there are a
SmartPVMS
large number of plants, you are advised to adjust the records displayed on each
page.
Figure 8-6
Step 3 Compare the plants exported from the page with those returned by the plant list
API to obtain the plants that are not returned.
----End

SmartPVMS 24.5.0 Northbound API Reference

Uploaded by

Copyright:

Available Formats

SmartPVMS 24.5.0 Northbound API Reference

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

SmartPVMS 24.5.0 Northbound API Reference

Uploaded by

Copyright:

Available Formats

SmartPVMS

HUAWEI DIGITAL POWER TECHNOLOGIES CO., LTD.

Trademarks and Permissions

Huawei Digital Power Technologies Co., Ltd.

Futian, Shenzhen 518043

People's Republic of China

Issue 01 (2024-07-01) Copyright © Huawei Digital Power Technologies Co., Ltd. i

4 Flow Control Description.....................................................................................................40

Issue 01 (2024-07-01) Copyright © Huawei Digital Power Technologies Co., Ltd. ii

5.1.3 Alarm................................................................................................................................................................................... 125

7 Best Practices....................................................................................................................... 225

Issue 01 (2024-07-01) Copyright © Huawei Digital Power Technologies Co., Ltd. iv

24.5.0 Northbound API Changes

API for https://Domain name of the This API is used to Ne

Issue 01 (2024-07-01) Copyright © Huawei Digital Power Technologies Co., Ltd. 1

API Name Method and Path Description Re

API for https://Domain name of the This API is used to Ne

API for https://Domain name of the This API is used to Ne

API for https://Domain name of the This API is used to Ne

API for https://Domain name of the This API is used to Ne

Issue 01 (2024-07-01) Copyright © Huawei Digital Power Technologies Co., Ltd. 2

API Name Method and Path Description Re

API for https://management system Query the execution Ne

Hourly https://Domain name of the The PVYield and Mo

Daily Plant https://{Domain name of the The PVYield and Mo

Monthly https://{Domain name of the The PVYield and Mo

Yearly https://Domain name of the The PVYield and Mo

API for https://Management system You are not advised to Mo

API for https://Management system You are not advised to Mo

24.4.0 Northbound API Changes

Issue 01 (2024-07-01) Copyright © Huawei Digital Power Technologies Co., Ltd. 3

24.2.0 Northbound API Changes

Added 3.1 OAuth Connect.

Old API New API Description

/thirdData/getStationList /thirdData/stations The new API supports

/thirdData/ /thirdData/ The new API supports a

Issue 01 (2024-07-01) Copyright © Huawei Digital Power Technologies Co., Ltd. 4

Old API New API Description

/rest/openapi/ /rest/openapi/ The new API can deliver

Issue 01 (2024-07-01) Copyright © Huawei Digital Power Technologies Co., Ltd. 5

2.1 Introduction to Northbound Open APIs

Issue 01 (2024-07-01) Copyright © Huawei Digital Power Technologies Co., Ltd. 6

HTTP Status Codes

2.2 API Architecture

Issue 01 (2024-07-01) Copyright © Huawei Digital Power Technologies Co., Ltd. 7

Figure 2-1 WebService NBI architecture

2.3 API Overview

Device List Returns the device list of a given plant by page.

Moni Real-time Obtains real-time data such as the energy yield,

Issue 01 (2024-07-01) Copyright © Huawei Digital Power Technologies Co., Ltd. 8

API API API Name Description

Real-time Obtains real-time device data. The real-time data

Historical Obtains the 5-minute data of a device in a given

Alar Querying Queries device active alarms of by plant or query

Daily plant Queries the daily data of a plant in a month. The

Monthly Queries the monthly data of a plant in a year.

Monthly Queries the monthly data of a device. The data

Issue 01 (2024-07-01) Copyright © Huawei Digital Power Technologies Co., Ltd. 9

API API API Name Description

Yearly device Queries the yearly data of a device. The data