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 Login API
to obtain a token for identity authentication of accessing other APIs.
Communication Between a Third-party System and the SmartPVMS
Figure 3-1 Communication between a third-party system and the SmartPVMS
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.
• Obtaining an Account
• Authentication API
• Calling an API
Obtaining an Account
The permission to access northbound APIs is created by the company administrator. The
procedure is as follows:
1. Choose System > Company Management > Northbound Management from
the main menu.
2. Click Add. In the dialog box that is displayed, set basic information, such as
Associated account, Username, and Password.
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.
To select all plants of a company, select the company.
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.
5. Click OK to save the settings.
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.
• Login API
• Logout API
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.
• 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 Remarks
Type
success Request success or failure flag Boolean Request
success or
true: The request succeeded.
failure flag
false: The request failed.
failCode Error code Integer -
Value 0 indicates that the
status is normal. For other
error codes, see Error Code
List.
params Parameters - - -
currentTime Current system time, in Long -
milliseconds
message Optional message String If the login
is
successful,
the
document
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
}
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.
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.
Request Parameters
Parameter Description Data Mandatory/Optional
Type
xsrfToken XSRF-TOKEN returned in the response String Mandatory
header after a successful login through
the login API.
Response Packet
Parameter Description Data Remarks
Type
success Request success or failure flag Boolean Request
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 Error Code List.
params Parameters - - -
Parameter Description Data Remarks
Type
currentTime Current system time, in Long -
milliseconds
message Optional message String -
data Returned data Object -
Example
Request example:
"xsrfToken":"x-
apepjy1fpd2ptete1f7zuqimep7wuqen9hkb3xaourelbyrx9jio7s09hgk6ca2mdlksjdglasdhj
aklsdfhhdsahwedyuioqwehjkd"
Response example:
Example 1: successful logout
"success":true,
"data":null,
"failCode":0,
"params":{
"currentTime":1503046597854
},
"message":null
Example 2: failed logout
"data":null,
"success":false,
"failCode":20004,
"params":{
"currentTime":1503046597854
},
"message":null
}
Logout example:
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.
Access Example
1. Create an API account on the management system and bind the account to a PV
plant. For details, see Obtaining an Account.
2. Obtain the login credential xsrf-token by referring to 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.
3. Content-Type: application/json
Enter the login credential xsrf-token in the request header to access the corresponding
API to obtain data.
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.
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 Flow Control Policy in OAuth Connect Mode. For
details about flow control using an API account, see Flow Control Using the API
Account.
• Flow Control Policy in OAuth Connect Mode
• Flow Control Using the API Account
