OpenAPI Guide

Token Encryption Transmission Guide

This guide provides detailed instructions on securely using the RSA encryption algorithm to encrypt tokens (Token) for transmission within our open platform. Following this guide ensures the highest level of protection for sensitive data during transmission between the client and the server.
Detailed operations can be found below.

Token Encryption Process

• Generate Key Pair
  Developers need to apply for a token in the platform application. The system generates a key pair, and developers download the token information (including Key ID, Key, and Public Key). This information is used for token encryption, while the private key is used for decryption.
• Token Application and Download
  1. Access Device Management
     Navigate to Device Management. See Device Management for details.
  2. Apply and Download Token
     Add or download a token. See Token Management for details.
• API Interface Explanation
  The system securely retrieves the token information and encrypts it using the RSA algorithm to generate a ciphertext. This encrypted ciphertext is included in the HTTP headers of API requests as part of authentication or authorization information. This process ensures confidentiality and prevents sensitive information leakage during transmission. (For encryption methods, refer to the sample code below.)

Sample Code

JAVA Example File

Golang Example File

.Net Example File

Common Request Error Codes

Code	Description
401	Access token expired, requires renewal
404	API endpoint error
428	User or tenant does not exist
429	User not registered
500	Internal server error
503	Service busy, try again later
1000	Data already exists

Device Time-Series Data

Device Time-Series Data Push

tip

You can push time-series data from devices, supporting multiple devices in one request. The total data count per request must not exceed 1,000 records.

URL: /dataPlatform/openapi

HTTP Method: POST

Request Body Type: Array

Authentication: Header fields (encryption methods in API Call Demo)

Field Name	Type	Required	Location	Description
X-Source-SecretId	string	Yes	Header	Key ID
X-Source-SecretKey	string	Yes	Header	Encrypted Key Text

Array Object Description

Field Name	Type	Required	Description
time	string	No	Device data collection time
equipmentName	string	Yes	Device name
functionType	string	Yes	Device function point name
buildingName	string	Yes	Device building name (must match the registered building name)
devEui	string	No	Unique identifier for IoT devices
value	double	No	Numeric value for the function point (either value or reading is required)
reading	string	No	String value for the function point (either value or reading is required)
unit	string	No	Unit for the function point

Response Field Description

Field Name	Type	Description
code	int	Response code, 200 indicates success
message	string	System message
isSuccess	boolean	Returns True if successful, False otherwise

Error Codes

For more details, refer to Common Request Error Codes.

Device Details Query

tip

Retrieve details for a single device.

URL: /device/v1/mn/{devEui}

HTTP Method: GET

Authentication: Header fields (encryption methods in API Call Demo)

Field Name	Type	Required	Location	Description
X-Source-SecretId	string	Yes	Header	Key ID
X-Source-SecretKey	string	Yes	Header	Encrypted Key Text

Request Parameters

Field Name	Type	Required	Description
devEui	string	Yes	Unique identifier for IoT devices

Response Field Description

Field Name	Type	Description
code	int	Response code, 200 indicates success
message	string	System message
isSuccess	boolean	Returns True if successful, False otherwise
data	object	Device detail object

Data Object Fields

Field Name	Description
name	Device name
alias	Device alias
equModel	Device model
points	Device function points (array of objects)
devEUI	Unique identifier for IoT devices
location	Device registration location
isOnline	Indicates if the device is online (True = Online, False = Offline)
descriptions	Device description
isIot	Indicates if the device is IoT (True = IoT, False = Non-IoT)
buildingName	Registered building name

Points Array in Device Details - Field Description

Field Name	Description
type	Device point name
unit	Device point unit
bmsId	Non-IoT device point ID
control	Indicates if reverse control is supported (True: supported, False: not supported)

Error Codes

For more details, refer to Common Request Error Codes.

Device List Query

tip

This query retrieves all device information accessible under the current tenant.

URL: /device/v1/mn/page

HTTP Request Method: GET

Authentication: Header Field Description (encryption method detailed in API Call Demo)

Field Name	Field Type	Required	Location	Description
X-Source-SecretId	string	Yes	Header	Secret ID
X-Source-SecretKey	string	Yes	Header	Secret Key Encrypted Text

Request Parameters

Field Name	Field Type	Required	Description
current	int	Yes	Current page
size	int	Yes	Number of items per page
name	string	No	Device name (supports fuzzy matching)
devEui	string	No	IoT device unique identifier (exact match)
buildingName	string	No	Building name entered during registration (exact match)
equModel	string	No	Device model name (exact match)

Response Fields Description

Field Name	Field Type	Description
code	int	Response code (200 indicates success)
message	string	System message
isSuccess	boolean	True if successful, False otherwise
data	object	Device list object (total: total count, size: items per page, current: current page, records: device data)

Device Data (records) - Field Description

Field Name	Description
name	Device name
alias	Device alias
equModel	Device model
points	Device point information (see below for individual field descriptions)
devEUI	IoT device unique identifier
location	Device registration location
isOnline	Indicates if the device is online (True: online, False: offline)
descriptions	Device description
isIot	Indicates if it is an IoT device (True: IoT, False: Non-IoT)
buildingName	Building name during device registration

Device Points - Individual Field Description

Field Name	Description
type	Device point name
unit	Device point unit
bmsId	Non-IoT device point ID
control	Indicates if reverse control is supported (True: supported, False: not supported)

Error Codes

For more details, refer to Common Request Error Codes.

Latest Device Point Values Query

tip

Query the latest values of device points accessible under the current tenant.

URL: /device/v1/realtime/{devEui}/values

HTTP Request Method: GET

Authentication: Header Field Description (encryption method detailed in API Call Demo)

Field Name	Field Type	Required	Location	Description
X-Source-SecretId	string	Yes	Header	Secret ID
X-Source-SecretKey	string	Yes	Header	Secret Key Encrypted Text

Request Parameters

Field Name	Field Type	Required	Description
devEui	string	No	IoT device unique identifier (exact match)

Response Fields Description

Field Name	Field Type	Description
code	int	Response code (200 indicates success)
message	string	System message
isSuccess	boolean	True if successful, False otherwise
data	array	Latest values of device points

Data - Individual Field Description

Field Name	Description
time	Data collection time
equipmentName	Device name
buildingName	Device registration building
functionType	Single device point name
devEUI	IoT device unique identifier
value	Device numeric type value
reading	Device string type value
unit	Device point unit

Error Codes

For more details, refer to Common Request Error Codes.

Device Point Historical Value Query

tip

You can query the data values of a single or all points of a device within a specific time range. (The time range can only query data within the past week)

URL: /device/v1/realtime/history

HTTP Request Method: POST

Authentication: Request Header Field Description (Encryption method detailed in API Call Demo)

Field Name	Field Type	Required	Location	Description
X-Source-SecretId	string	Yes	Header	Secret ID
X-Source-SecretKey	string	Yes	Header	Secret Key Encrypted Text

Request Parameters

Field Name	Field Type	Required	Description
equipmentName	string	Yes	Device name (exact match)
functionType	string	No	Device point name
startTime	datetime	No	Start time
endTime	datetime	No	End time
field	string	Yes	Device point value type (VALUE for numeric, READING for string)
equModel	string	No	Device model name (exact match)

Response Fields Description

Field Name	Field Type	Description
code	int	Response code (200 indicates success)
message	string	System message
isSuccess	boolean	True if successful, False otherwise
data	array	Device point value objects

Device Data Array - Field Description

Field Name	Description
time	Data collection time
equipmentName	Device name
buildingName	Device registration building
functionType	Single device point name
devEUI	IoT device unique identifier
value	Device numeric type value
reading	Device string type value
unit	Device point unit

Error Codes

For more details, refer to Common Request Error Codes.

Data Warehouse

Data Push

tip

You can push dataset data (fields and data types must match the dataset configuration). Multiple records can be pushed in one request, but the total number of records in a single request cannot exceed 1,000.

URL: /dataset/v1/{datasetName}

HTTP Request Method: POST

Authentication: Request Header Field Description (Encryption method detailed in API Call Demo)

Field Name	Field Type	Required	Location	Description
X-Source-SecretId	string	Yes	Header	Secret ID
X-Source-SecretKey	string	Yes	Header	Secret Key Encrypted Text
X-Param-ProjectId	string	Header	Yes	Platform Project ID

Request Body Type: Array

Request Parameters

Field Name	Field Type	Required	Description
datasetName	string	Yes	Dataset ID

Response Fields Description

Field Name	Field Type	Description
code	int	Response code (200 indicates success)
message	string	System message
isSuccess	boolean	Returns True if successful, False otherwise

Error Codes

For more details, refer to Common Request Error Codes.

Data Query

tip

You can query data values for a single or all points of a device within a specific time range. (The time range can only query data within the past week)

URL: /device/v1/realtime/history

HTTP Request Method: POST

Authentication: Request Header Field Description (Encryption method detailed in API Call Demo)

Field Name	Field Type	Required	Location	Description
X-Source-SecretId	string	Yes	Header	Secret ID
X-Source-SecretKey	string	Yes	Header	Secret Key Encrypted Text
X-Param-ProjectId	string	Header	Yes	Platform Project ID

Request Parameters

Field Name	Field Type	Required	Description
equipmentName	string	Yes	Device name (exact match)
functionType	string	No	Device point name
startTime	datetime	No	Start time
endTime	datetime	No	End time
field	string	Yes	Device point value type (VALUE for numeric, READING for string)
equModel	string	No	Device model name (exact match)

Response Fields Description

Field Name	Field Type	Description
code	int	Response code (200 indicates success)
message	string	System message
isSuccess	boolean	Returns True if successful, False otherwise
data	array	Device point value objects

Device Data Array - Field Description

Field Name	Description
time	Data collection time
equipmentName	Device name
buildingName	Device registration building
functionType	Single device point name
devEUI	IoT device unique identifier
value	Device numeric type value
reading	Device string type value
unit	Device point unit

Error Codes

For more details, refer to Common Request Error Codes.