APsystems OpenAPI

User Manual

Copyright © 2016-2023 Altenergy Power System Inc. All Rights Reserved

 APsystems OpenAPI User Manual

Version List：

Version Author Date Description

V1.0 Yamin.Luo 2022/09/16 First Document
Edit the token URL
V1.1 Yamin.Luo 2023/03/24
Change the expiration time of refresh token
Change the JWT Token authentication method to
V1.2 Yusheng.huang 2023/10/07
signature authentication method
V1.3 Yusheng.huang 2023/10/31 Add meter interface
V1.4 Yamin.Luo 2023/11/17
V1.5 Yamin.Luo 2023/11/17 Add inverter-level data API
V1.6 Yamin.Luo 2024/02/07 Optimize the interface for end user

2
 APsystems OpenAPI User Manual

Chapter
APsystems OpenAPI ....................................................................................................................... 1
User Manual .................................................................................................................................. 1
1. Overview ....................................................................................................................................4
2. Authenticate and Authorize ........................................................................................................4
2.1 Register an OpenAPI Account ............................................................................................4
2.2 Authentication ..................................................................................................................4
2.2.1 Headers: Fixed request header information ............................................................5
2.2.2 Calculate the signature ........................................................................................... 5
2.3 Authorization ....................................................................................................................6
2.4 Base Url ............................................................................................................................ 6
3. API ............................................................................................................................................. 7
3.1 System Details API ............................................................................................................ 7
3.1.1 Get Details for a Particular System ..........................................................................7
3.1.2 Get Inverters for a Particular System ...................................................................... 8
3.1.3 Get Meters for a Particular System ......................................................................... 9
3.2 System-level Data API ..................................................................................................... 10
3.2.1 Get Summary Energy for a Particular System ........................................................ 10
3.2.2 Get Energy in Period for a Particular System ......................................................... 11
3.3 ECU-level Data API .......................................................................................................... 12
3.3.1 Get Summary Energy for a Particular ECU ............................................................. 13
3.3.2 Get Energy in Period for a Particular ECU .............................................................. 13
3.4 Meter-level Data API .......................................................................................................15
3.4.1 Get Summary Energy for a Particular Meter ..........................................................15
3.4.2 Get Energy in Period for a Particular Meter ...........................................................17
3.5 Inverter-level Data API .................................................................................................... 19
3.5.1 Get Summary Energy for a Particular Inverter .......................................................19
3.5.2 Get Energy in Period for a Particular Inverter ........................................................21
3.5.3 Get Energy in a Day for all inverters below a Particular ECU ..................................24
4. Annex .......................................................................................................................................25
4.1 Annex 1. Response Code Definition .................................................................................25

3
 APsystems OpenAPI User Manual

1. Overview
Welcome to APsystems’ OpenAPI for developer portal. Anyone can register an API account on the
platform after the application to access the system details and system data.

The OpenAPI is a REST API and delivers data in JSON format via HTTPS. It has five categories:
 System Details API
 System-level Data API
 ECU-level Data API
 Meter-level Data API
 Inverter-level Data API

2. Authenticate and Authorize

2.1 Register an OpenAPI Account
Send an application email to APsystems’ support email address with the information below:
 Who you are?
 Why do you want to register an OpenAPI account?
 What to do with the data?

When your application was approved, you will get an email with your App Id and App Secret.

Parameter Type Description

This is a unique identify id for each OpenAPI account. It is a 32-bit
App Id string string with numbers and letters. It can not be changed when it was
signed.
This is the password to verify the valid OpenAPI account to
generate the access token and refresh token. It is a 32-bit string
App Secret string
with numbers and letters. It will have a default value the first
time. If you want to change it, email APsystems.

Note: Keep the access information safe and secret, do not disclose it to others.

2.2 Authentication
If you have got your App Id and App Secret, you can access the OpenAPI. And you need to calculate
a signature for each request.

4
 APsystems OpenAPI User Manual

2.2.1 Headers: Fixed request header information

You need to put the common parameters into the headers of each API request.

Parameter Required Type Description

The identity id of the OpenAPI account (App
X-CA-AppId Y string
Id).
X-CA-Timestamp Y string The timestamp you request the API.
Uuid, a 32-bit string, such as:
X-CA-Nonce Y string
“5e36eab8295911ee90751eff13c2920b”
Algorithm
X-CA-Signature-Method Y string
“HmacSHA256” or “HmacSHA1”
X-CA-Signature Y string The signature to verify your request.

2.2.2 Calculate the signature

 Step 1: Get the parameters from the API request

Get the parameters below:

HTTPMethod (GET, POST, DELETE)

Headers (X-CA-AppId, X-CA-Timestamp, X-CA-Nonce, X-CA-Signature-Method)
RequestPath (The last name of the path)

 Step 2: Combine the parameters into one String

Combine the parameters with the orders below:

stringToSign = X-CA-Timestamp + “/” + X-CA-Nonce + “/” + X-CA-AppId + “/” + RequestPath +

“/” + HTTPMethod + “/” + X-CA-Signature-Method

 Step 3: Calculate the signature with the algorithm

Currently, we have support two algorithms to sign the parameters. You can choose one of them
to calculate the signature.
- HmacSHA256
5
 APsystems OpenAPI User Manual

- HmacSHA1

Sign the stringToSign with the APP Secret：

HmacSHA256
Mac hmacSha256 = Mac.getInstance("HmacSHA256");
byte[] appSecretBytes = appSecret.getBytes(Charset.forName("UTF-8"));
hmacSha256.init(new SecretKeySpec(appSecretBytes, 0, appSecretBytes.length, "HmacSHA256"));
byte[] md5Result = hmacSha256.doFinal(stringToSign.getBytes(Charset.forName("UTF-8")));
String signature = Base64.getEncoder().encodeToString(md5Result);

HmacSHA1
Mac hmacSha1 = Mac.getInstance("HmacSHA1");
byte[] appSecretBytes = appSecret.getBytes(Charset.forName("UTF-8"));
hmacSha1.init(new SecretKeySpec(appSecretBytes, 0, appSecretBytes.length, "HmacSHA1"));
byte[] md5Result = hmacSha1.doFinal(stringToSign.getBytes(Charset.forName("UTF-8")));
String signature = Base64.getEncoder().encodeToString(md5Result);

2.3 Authorization
You can access the default data as long as you get your AppId and App Secret. In addition, you can
choose the category corresponding to your business.

Note: According to the access count and data range, it will cause different payments.

2.4 Base Url

The base url is “https://api.apsystemsema.com:9282”.

6
 APsystems OpenAPI User Manual

3. API
3.1 System Details API
3.1.1 Get Details for a Particular System
 URL
/user/api/v2/systems/details/{sid}

 Method
GET

 Description
This request will return the details of the system which you searched for.

 Parameters
Parameter Required Type Description
sid Y string The unique identity id of the system.

 Response
Code Example Model Description
- data(object)
* sid(string)
Unique identity id of the system.
* create_date(string,yyyy-MM-dd)
{
Register date of the system in EMA.
"data": {
* capacity(string)
"sid": "AZ12649A3DFF",
System size. Default unit is kW.
"create_date": "2022-09-01",
* type(int)
"capacity": "1.28",
System type. Default=1.
0 "type": 1,
1, PV system.
"timezone": "Asia/Shanghai",
2, Storage system.
"ecu":["203000001234"]
3, PV & storage system.
},
* timezone(string)
"code": 0
The timezone to the ECU belongs
}
* ecu(list)
ECU ids are registered in this system.
- code(int)
Response code. Refer to 4.1 Annex 1.

7
 APsystems OpenAPI User Manual

Response Code Definition.

3.1.2 Get Inverters for a Particular System

 URL
/user/api/v2/systems/inverters/{sid}

 Method
GET

 Description
This request will return all the devices of a system you searched for.

 Parameters
Parameter Required Type Description
sid Y string The unique identity id of the system.

 Response
Code Example Model Description
- data(list)
{ List of the devices sorted by ECU
"data": [{ * eid(string)
"eid": "203000001234", Unique identity id of the ECU.
"type": 0, * type(int)
"timezone": "Asia/Shanghai", Type of the ECU. Default=0
"inverter": [{ 0, ECU
"uid": "902000001234", 1, ECU with meter activated
0 "type": "QT2D" 2, ECU with storage activated
},{ * timezone(string)
"uid": "902000001235", The timezone to the ECU belongs
"type": "QT2D" * inverter(list)
}] List of the inverters connected to the ECU.
}],  uid(string)
"code": 0 Unique identity id of the inverter.
}  type(string)
Type of the inverter.

8
 APsystems OpenAPI User Manual

* model(string)
Model of the storage-activated ECU.
* capacity(string)
The capacity of the storage-activated ECU.
Default unit is kWh.
- code(int)
Response code. Refer to 4.1 Annex 1.
Response Code Definition.

3.1.3 Get Meters for a Particular System

 URL
/user/api/v2/systems/meters/{sid}

 Method
GET

 Description
This request will return all the meters of a system you searched for.

 Parameters
Parameter Required Type Description
sid Y string The unique identity id of the system.

 Response
Code Example Model Description
- data(list)
{
List of the meters
"data": ["203000001234"],
0 - code(int)
"code": 0
Response code. Refer to 4.1 Annex 1.
}
Response Code Definition.

9
 APsystems OpenAPI User Manual

3.2 System-level Data API

3.2.1 Get Summary Energy for a Particular System
 URL
/user/api/v2/systems/summary/{sid}

 Method
GET

 Description
This request will return the accumulative energy reported by inverters of a particular system that
you searched for.

 Parameters
Parameter Required Type Description
sid Y string The unique identity id of the system.

10
 APsystems OpenAPI User Manual

 Response
Code Example Model Description
- data(object)
* today(string)
Accumulative energy was reported by inverters on
today. Unit is kWh.
{
* month(string)
"data": {
Accumulative energy was reported by inverters
"today": "12.28",
this month. Unit is kWh.
"month": "12.28",
* year(string)
0 "year": "12.28",
Accumulative energy was reported by inverters
"lifetime": "12.28"
this year. Unit is kWh.
},
* lifetime(string)
"code": 0
Accumulative energy reported by inverters in the
}
lifetime of the system. Unit is kWh.
- code(int)
Response code. Refer to 4.1 Annex 1. Response Code
Definition.

3.2.2 Get Energy in Period for a Particular System

 URL
/user/api/v2/systems/energy/{sid}

 Method
GET

 Description
This request will return four levels of accumulative energy reported by inverters for a particular
system according to the parameters.
- Hourly Energy: Return hourly energy in a day. The length is 24 by default, which shows the
energy calculated per hour during 0 – 23.
- Daily Energy: Return daily energy in a natural month. The length is equal to the number of
days per month.
- Monthly Energy: Return monthly energy in a natural year. The length is 12 by default.
- Yearly Energy: Return yearly energy in a lifetime. The length is equal to the years since the
installation.

11
 APsystems OpenAPI User Manual

Set the “energy_level” to “hourly”, “daily”, “monthly” or “yearly” to get the corresponding
accumulative energy. The format of the “date_range” will change according to the “energy_level”, it
is a field to limit the date to calculate the accumulative energy.

Please set the parameters available to make sure the request is responded to as expected. If the
“data_rage” is later than the current time, it will be rejected.

 Parameters
Parameter Required Type Description
sid Y string The unique identity id of the system.
The energy level to calculate the accumulative energy.
energy_level Y string Available values are “hourly”, “daily”, “monthly”, and
“yearly”.
The data range to calculate the accumulative energy.
The format needs to change according to the value of
“energy_level”.
date_range N string - When “hourly”, the format is “yyyy-MM-dd”.
- When “daily”, the format is “yyyy-MM”.
- When “monthly”, the format is “yyyy”.
- When “yearly”, this field is not required.

 Response
Code Example Model Description
- data(list)
Energy list. The length is stable in each mode.
Unit is kWh.
* 24, when querying “hourly”.
{ * The number of days per month when
"data": ["567.23", "550.32", "320.12"], querying “daily”.
0
"code": 0 * 12, when querying “monthly”.
} * The number of years since installation when
querying “yearly”.
- code(int)
Response code. Refer to 4.1 Annex 1.
Response Code Definition.

3.3 ECU-level Data API

12
 APsystems OpenAPI User Manual

3.3.1 Get Summary Energy for a Particular ECU

 URL
/user/api/v2/systems/{sid}/devices/ecu/summary/{eid}

 Method
GET

 Description
This request will return the accumulative energy reported by inverters below an ECU that you
searched for.

 Parameters
Parameter Required Type Description
sid Y string The identity id of the system.
eid Y string The identity id of ECU.

 Response
Code Example Model Description
- data(object)
* today(string)
Accumulative energy was reported by
inverters on today. Unit is kWh.
{ * month(string)
"data": { Accumulative energy was reported by
"today": "12.28", inverters this month. Unit is kWh.
"month": "12.28", * year(string)
0 "year": "12.28", Accumulative energy was reported by
"lifetime": "12.28" inverters this year. Unit is kWh.
}, * lifetime(string)
"code": 0 Accumulative energy reported by
} inverters in the lifetime of the system.
Unit is kWh.
- code(int)
Response code. Refer to 4.1 Annex 1.
Response Code Definition.

3.3.2 Get Energy in Period for a Particular ECU

13
 APsystems OpenAPI User Manual

 URL
/user/api/v2/systems/{sid}/devices/ecu/energy/{eid}

 Method
GET

 Description
This request will return four levels of accumulative energy reported by inverters below a particular
ECU according to the parameters.
- Power Telemetry: Return the power telemetry in a day.
- Hourly Energy: Return hourly energy in a day. The length is 24 by default, which shows the
energy calculated per hour during 0 – 23.
- Daily Energy: Return daily energy in a natural month. The length is equal to the number of
days per month.
- Monthly Energy: Return monthly energy in a natural year. The length is 12 by default.
- Yearly Energy: Return yearly energy in a lifetime. The length is equal to the years since the
installation.

Set the “energy_level” to “hourly”, “daily”, “monthly” or “yearly” to get the corresponding
accumulative energy. The format of the “date_range” will change according to the “energy_level”, it
is a field to limit the date to calculate the accumulative energy.

Please set the parameters available to make sure the request is responded to as expected. If the
“date_rage” is later than the current time, it will be rejected.

 Parameters
Parameter Required Type Description
sid Y string The unique identity id of the system.
eid Y string The identity id of ECU.
The energy level to calculate the accumulative energy.
energy_level Y string Available values are “minutely”, “hourly”, “daily”,
“monthly”, and “yearly”.
The data range to calculate the accumulative energy.
The format needs to change according to the value of
date_range N string “energy_level”.
- When “minutely”, the format is “yyyy-MM-dd”.
- When “hourly”, the format is “yyyy-MM-dd”.

14
 APsystems OpenAPI User Manual

- When “daily”, the format is “yyyy-MM”.

- When “monthly”, the format is “yyyy”.
- When “yearly”, this field is not required.

 Response
Code Example Model Description
- data(list)
When choosing “hourly”, “daily”, “monthly”,
and “yearly”. Return energy list. The length is
stable in each mode. Unit is kWh.
* 24, when querying “hourly”.
* The number of days per month when
querying “daily”.
* 12, when querying “monthly”.
* The number of years since installation
when the query “yearly”.
- data(object)
When choosing “minutely”. Return energy
object. The length is not stable.
{
* time(list)
"data": ["567.23", "550.32", "320.12"],
0 Time list, each point is in a string format
"code": 0
HH:mm
}
* energy(list)
Energy list, each point is in a string
format, corresponding to the time. Unit is
kWh
* power(list)
Power list, each point is in a string format,
corresponding to the time. Unit is W
* today(string)
Accumulative energy produced on the
day. Unit is kWh
- code(int)
Response code. Refer to 4.1 Annex 1.
Response Code Definition.

3.4 Meter-level Data API

3.4.1 Get Summary Energy for a Particular Meter

15
 APsystems OpenAPI User Manual

 URL
/user/api/v2/systems/{sid}/devices/meter/summary/{eid}

 Method
GET

 Description
This request will return the accumulative energy reported by an Meter ECU that you searched for.

 Parameters
Parameter Required Type Description
sid Y string The identity id of the system.
eid Y string The identity id of Meter ECU.

 Response
Code Example Model Description
{
"code": 0,
"data":
{
"today": { - data(object)
"consumed": "394.408090", Meter Summary energy Info.
"exported": "0.000000", * today(map)
"imported": "560.523540", Today’s energy.
"produced": "833.884550" * month(map)
}, Energy of the month.
0 "month": { * year(map)
"consumed": "394.408090", Energy of the year.
"exported": "0.000000", * lifetime(map)
"imported": "560.523540", Lifetime energy.
"produced": "833.884550" - code(int)
}, Response code. Refer to 4.1 Annex 1.
"year": { Response Code Definition.
"consumed": "6394.408090",
"exported": "0.000000",
"imported": "4560.523540",
"produced": "1833.884550"

16
 APsystems OpenAPI User Manual

},
"lifetime": {
"consumed": "6394.458090",
"exported": "0.000000",
"imported": "4561.643540",
"produced": "1833.894550"
}
}
}

3.4.2 Get Energy in Period for a Particular Meter

 URL
/user/api/v2/systems/{sid}/devices/meter/period/{eid}

 Method
GET

 Description
This request will return four levels of accumulative energy reported by inverters below a particular
Meter ECU according to the parameters.
- Power Telemetry: Return the power telemetry in a day.
- Hourly Energy: Return hourly energy in a day. The length is 24 by default, which shows the
energy calculated per hour during 0 – 23.
- Daily Energy: Return daily energy in a natural month. The length is equal to the number of
days per month.
- Monthly Energy: Return monthly energy in a natural year. The length is 12 by default.
- Yearly Energy: Return yearly energy in a lifetime. The length is equal to the years since the
installation.

Set the “energy_level” to “hourly”, “daily”, “monthly” or “yearly” to get the corresponding
accumulative energy. The format of the “date_range” will change according to the “energy_level”, it
is a field to limit the date to calculate the accumulative energy.

Please set the parameters available to make sure the request is responded to as expected. If the
“date_rage” is later than the current time, it will be rejected.

 Parameters
Parameter Required Type Description
sid Y string The unique identity id of the system.

17
 APsystems OpenAPI User Manual

eid Y string The identity id of Meter ECU.

The energy level to calculate the accumulative energy.
energy_level Y string Available values are “minutely”, “hourly”, “daily”,
“monthly”, and “yearly”.
The data range to calculate the accumulative energy.
The format needs to change according to the value of
“level”.
- When “minutely”, the format is “yyyy-MM-dd”.
date_range N string
- When “hourly”, the format is “yyyy-MM-dd”.
- When “daily”, the format is “yyyy-MM”.
- When “monthly”, the format is “yyyy”.
- When “yearly”, this field is not required.

 Response
Code Example Model Description
{ - data(list)
"code": 0, When choosing “hourly”, “daily”,
"data": { “monthly”, and “yearly”. Return
"time": ["01", "02",...], energy list. The length is stable in
"produced": ["40.300","50.016",...], each mode. Unit is kWh.
"consumed": ["40.300","50.016",...], * 24, when querying “hourly”.
"imported": ["40.300","50.016",...], * The number of days per month
"exported": ["40.300","50.016",...], when querying “daily”.
} * 12, when querying “monthly”.
* The number of years since
installation when the query
0 "code": 0, “yearly”.
"data": { - data(object)
"today": { When choosing “minutely”. Return
"consumed": "5.996600", energy object. The length is not
"exported": "0.071860", stable.
"imported": "3.712280", * time(list)
"produced": "2.356180" Time list, each point is in a string
}, format HH:mm
"time": ["23:57"], * energy(map)
"power": { Energy list, each point is in a
"consumed": ["167.96"], string format, corresponding to
"imported_exported": ["167.96"], the time. Unit is kWh

18
 APsystems OpenAPI User Manual

"produced": ["0.00"] * power(map)

}, Power list, each point is in a
"energy": { string format, corresponding to
"consumed": ["0.015620"], the time. Unit is W
"exported": ["0"], * today(map)
"imported": ["0.01562"], Accumulative energy produced
"produced": ["0.00000"] on the day. Unit is kWh
} - code(int)
} Response code. Refer to 4.1 Annex 1.
} Response Code Definition.

3.5 Inverter-level Data API

3.5.1 Get Summary Energy for a Particular Inverter
 URL
/user/api/v2/systems/{sid}/devices/inverter/summary/{uid}

 Method
GET

 Description
This request will return the energy of an inverter which you searched for.

 Parameters
Parameter Required Type Description
sid Y string The unique identity id of the system.
uid Y string The identity id of inverter.

 Response
Code Example Model Description
{ - data(list)
"data": { Energy list per channel.
0 "d1": "12.28",  d1(string)
"m1": "12.28", Accumulative energy reported by channel
"y1": "12.28", 1 of the inverter today.
19
 APsystems OpenAPI User Manual

"t1": "12.28",  m1(string)

"d2": "12.28", Accumulative energy reported by channel
"m2": "12.28", 1 of the inverter in this month.
"y2": "12.28",  y1(string)
"t2": "12.28", Accumulative energy reported by channel
"d3": "12.28", 2 of the inverter in this month.
"m3": "12.28",  t1(string)
"y3": "12.28", Accumulative energy reported by channel
"t3": "12.28", 3 of the inverter in this month.
"d4": "12.28",  d2(string)
"m4": "12.28", Accumulative energy reported by channel
"y4": "12.28", 2 of the inverter today.
"t4": "12.28"  m2(string)
}, Accumulative energy reported by channel
"code": 0 1 of the inverter in this month.
}  y2(string)
Accumulative energy reported by channel
2 of the inverter in this month.
 t2(string)
Accumulative energy reported by channel
3 of the inverter in this month.
 D3(string)
Accumulative energy reported by channel
3 of the inverter today.
 m3(string)
Accumulative energy reported by channel
1 of the inverter in this month.
 y3(string)
Accumulative energy reported by channel
2 of the inverter in this month.
 t3(string)
Accumulative energy reported by channel
3 of the inverter in this month.
 d4(string)
Accumulative energy reported by channel
4 of the inverter today.
 m4(string)
Accumulative energy reported by channel
1 of the inverter in this month.
 y4(string)

20
 APsystems OpenAPI User Manual

Accumulative energy reported by channel

2 of the inverter in this month.
 t4(string)
Accumulative energy reported by channel
3 of the inverter in this month.

- code(int)
Response code. Refer to 4.1 Annex 1. Response
Code Definition.

3.5.2 Get Energy in Period for a Particular Inverter

 URL
/user/api/v2/systems/{sid}/devices/inverter/energy/{uid}

 Method
GET

 Description
This request will return five levels of accumulative energy below a particular inverter according to
the parameters.
- Power Telemetry: Return the power telemetry in a day.
- Hourly Energy: Return hourly energy in a day. The length is 24 by default, which shows the
energy calculated per hour during 0 – 23.
- Daily Energy: Return daily energy in a natural month. The length is equal to the number of
days per month.
- Monthly Energy: Return monthly energy in a natural year. The length is 12 by default.
- Yearly Energy: Return yearly energy in a lifetime. The length is equal to the years since the
installation.

Set the “energy_level” to “hourly”, “daily”, “monthly” or “yearly” to get the corresponding
accumulative energy. The format of the “date_range” will change according to the “energy_level”, it
is a field to limit the date to calculate the accumulative energy.

Please set the parameters available to make sure the request is responded to as expected. If the
“date_range” is later than the current time, it will be rejected.

 Parameters
Parameter Required Type Description
sid Y string The unique identity id of the system.

21
 APsystems OpenAPI User Manual

uid Y string The identity id of inverter.

The energy level to calculate the accumulative energy.
energy_level Y string Available values are “minutely”, “hourly”, “daily”,
“monthly”, and “yearly”.
The data range to calculate the accumulative energy.
The format needs to change according to the value of
“energy_level”.
- When “minutely”, the format is “yyyy-MM-dd”.
date_range N string
- When “hourly”, the format is “yyyy-MM-dd”.
- When “daily”, the format is “yyyy-MM”.
- When “monthly”, the format is “yyyy”.
- When “yearly”, this field is not required.

 Response
Code Example Model Description
- data(object)
When choosing “hourly”, “daily”,
“monthly”, and “yearly”. Return
energy list per channel. The length is
stable in each mode. Unit is kWh.
* e1(object)
Energy list reported by channel 1.
* e2(object)
{ Energy list reported by channel 2.
"data": { * e3(object)
"e1": ["567.23","550.32","320.12"], Energy list reported by channel 3.
0 "e2": ["567.23","550.32","320.12"], * e4(object)
}, Energy list reported by channel 4.
"code": 0
} When choosing “minutely”, Return
energy list per channel. The length is
stable in each mode. Unit is kWh.
* t(list)
Time list, each point is in a string
format HH:mm
* dc_p1(list)
DC Power on channel 1.
* dc_p2(list)

22
 APsystems OpenAPI User Manual

DC Power on channel 2.
* dc_p3(list)
DC Power on channel 3.
* dc_p4(list)
DC Power on channel 4.
* dc_i1(list)
DC current on channel 1.
* dc_i2(list)
DC current on channel 2.
* dc_i3(list)
DC current on channel 3.
* dc_i4(list)
DC current on channel 4.
* dc_v1(list)
DC voltage on channel 1.
* dc_v2(list)
DC voltage on channel 2.
* dc_v3(list)
DC voltage on channel 3.
* dc_v4(list)
DC voltage on channel 4.
* dc_e1(list)
DC energy on channel 1.
* dc_e2(list)
DC energy on channel 2.
* dc_e3(list)
DC energy on channel 3.
* dc_e4(list)
DC energy on channel 4.
* ac_v1 (list)
AC voltage on channel 1.
* ac_v2(list)
AC voltage on channel 2.
* ac_v3(list)
AC voltage on channel 3.
* ac_t(list)
AC temperature.
* ac_p(list)
AC power.
* ac_f(list)

23
 APsystems OpenAPI User Manual

AC frequency.

- code(int)
Response code. Refer to 4.1 Annex 1.
Response Code Definition.

3.5.3 Get Energy in a Day for all inverters below a Particular ECU
 URL
/user/api/v2/systems/{sid}/devices/inverter/batch/energy/{eid}

 Method
GET

 Description
This request will return five levels of accumulative energy below a particular inverter according to
the parameters.
- Power Telemetry: Return the power telemetry in a day.
- Day Energy: Return the total energy in a day.

Set the “energy_level” to “power” or “energy” to get the corresponding energy. The format of
the “date_range” will change according to the “energy_level”, it is a field to limit the date to
calculate the accumulative energy.

Please set the parameters available to make sure the request is responded to as expected. If the
“date_range” is later than the current time, it will be rejected.

 Parameters
Parameter Required Type Description
sid Y string The unique identity id of the system.
eid Y string The identity id of ECU.
The energy level to calculate the accumulative energy.
energy_level Y string
Available values are “power”, “energy”.
date_range Y string - The data to query. The format is “yyyy-MM-dd”.

 Response
Code Example Model Description
0 { - data(object)

24
 APsystems OpenAPI User Manual

"data": , When choosing “energy”. Return energy list per

"code": 0 channel. The length is stable in each mode. Unit is
} kWh.
* energy(list)
Energy list. The string format in the list is “uid-
channel-energy”.
For example, 701000001234-1-1.24

When choosing “power”, Return power list per

channel. Unit is W.
* time(list)
Time list, each point is in a string format HH:mm
AC voltage on channel 1.
* power(map)
Power list, each point is in a string format,
corresponding to the time.
For example, {701000001234-1: [45,56,78,98]}
The power telemetry length is the same as the
length of time.

- code(int)
Response code. Refer to 4.1 Annex 1. Response
Code Definition.

4. Annex
4.1 Annex 1. Response Code Definition
Code Description
0 Succeed to request.
1000 Data exception.
1001 No data.
2000 Application account exception.
2001 Invalid application account.
2002 The application account is not authorized.

25
 APsystems OpenAPI User Manual

2003 Application account authorization expires.

2004 The application account has no permission.
2005 The access limit of the application account was exceeded.
3000 Access token exception.
3001 Missing Access token.
3002 Unable to verify Access token.
3003 Access token timeout.
3004 Refresh token timeout.
4000 Request parameter exception.
4001 Invalid request parameter.
5000 Internal server exception.
6000 Communication exception.
7000 Server access restriction exception.
7001 Server access limit exceeded.
7002 Too many requests, please request later.
7003 The system is busy, please request later.

26