Device Control API (User Auth)

Device Control API provides remote control and parameter reading functions for inverters. Applies to User-level Authorization using Custom HMAC-SHA1 Signature authentication.

Authorization method: User-level Authorization

Difference from OAuth2.0 Version

• User-level Authorization: Custom HMAC-SHA1 Signature, interface path prefix /v2/api/
• Device Control (OAuth2.0): For third-party platforms, OAuth2.0 authentication, interface path prefix /api/control_device/

API Basic Information

Item	Description
API Base URL	https://www.soliscloud.com:13333/
Request method	POST

Authentication

All interface requests use Custom HMAC-SHA1 Signature authentication. See User-level Authorization for details.

Request header format:

Content-MD5: [Content-MD5]
Content-Type: application/json;charset=UTF-8
Date: [Date]
Authorization: API {apiId}:{sign}

Sign calculation:

Sign = base64(HmacSHA1(apiSecret, "POST\n" + Content-MD5 + "\n" + Content-Type + "\n" + Date + "\n" + CanonicalizedResource))

Inverter Register Communication Protocol

For register addresses and command parameters used in device control interfaces, please refer to the following protocol documents:

• Grid-Connected Inverter: Please contact sales to obtain
• Hybrid Inverter: Please contact sales to obtain

Common Response Format

{
  "success": true,
  "code": "0",
  "msg": "success",
  "data": {}
}

Field	Type	Description
success	Boolean	true=success, false=failure
code	String	0=success, others=failure code
msg	String	Description of code value
data	Object	Interface-specific return data

---

Interface Overview

Remote Control of a Single Inverter — /v2/api/control

Issue control instructions to a single or multiple inverters. Supports all Solis devices.

Rate limit: 2 times/second

Request Parameters:

Parameter	Type	Required	Description
inverterSn	String	One of three	Inverter SN, use "," to split multiple
plantId	String	One of three	Plant ID, available from plant query interfaces or real-time data forwarding
nmiCode	String	One of three	NMI (National Meter Identifier), Australia only
atCommand	String	No (one of atCommand/modbusAddr)	AT command passthrough string. E.g. AT+TEST=GIN485:01 06 0B BE 00 BE
modbusAddr	Number / String	No (one of atCommand)	Modbus register address, used with value and functionCode
functionCode	String	No (required when using modbusAddr)	Modbus function code. Options: 03 (Read Holding Registers), 04 (Read Input Registers), 06 (Write Single Register). Used with modbusAddr
value	String	No (required when modbusAddr is used)	Set value, used with modbusAddr

Device Identification (one of three required)

• inverterSn: Inverter SN, directly identifies the device
• plantId: Plant ID, available from plant query interfaces or real-time data forwarding
• nmiCode: NMI (National Meter Identifier), Australia only

Control Method (choose one)

1. atCommand: Direct AT command passthrough
2. modbusAddr + value: Direct Modbus register address and set value

Request Example — Method 1: AT Command Passthrough

curl -X POST "https://{API_DOMAIN}:13333/v2/api/control" \
  -H "Content-MD5: {Content-MD5}" \
  -H "Content-Type: application/json;charset=UTF-8" \
  -H "Date: {Date}" \
  -H "Authorization: API {apiId}:{sign}" \
  -d '{
    "inverterSn": "380205022C190102",
    "atCommand": "AT+TEST=GIN485:01 06 0B BE 00 BE"
  }'

Request Example — Method 2: modbusAddr + value

curl -X POST "https://{API_DOMAIN}:13333/v2/api/control" \
  -H "Content-MD5: {Content-MD5}" \
  -H "Content-Type: application/json;charset=UTF-8" \
  -H "Date: {Date}" \
  -H "Authorization: API {apiId}:{sign}" \
  -d '{
    "inverterSn": "380205022C190102",
    "modbusAddr": 48,
    "functionCode": "06",
    "value": "190"
  }'

Response Parameters:

Field	Type	Description
code	String	0=success, others=failure code
msg	String	Result description
time	Long	Return timestamp
data	Array	Control result list

data element fields:

Field	Type	Description
msg	String	Single device result description
code	Integer	Single device result code
recv	String	Received packet
command	String	AT command sent

Response Example:

{
  "code": "0",
  "data": [
    {
      "msg": "380205022C190102  Time: 1688744454...",
      "code": 0,
      "recv": "01060BBE00BE6BBA",
      "command": "AT+TEST=GIN485:01 06 0b be 00 be 6b ba"
    }
  ],
  "time": "1688715605600"
}

---

Reading Parameter Values from Multiple Devices — /v2/api/atRead

Asynchronously read current parameter values from one or more inverters. Returns orderId for subsequent result query.

Rate limit: 2 times/second

Request Parameters:

Parameter	Type	Required	Description
inverterSn	String	One of three	Inverter SN, use "," to split multiple
plantId	String	One of three	Plant ID, available from plant query interfaces or real-time data forwarding
nmiCode	String	One of three	NMI (National Meter Identifier), Australia only, use "," to split multiple
modbusAddr	Number / String	Yes	Modbus register address
functionCode	String	No	Modbus function code. Options: 03 (Read Holding Registers), 04 (Read Input Registers). Used with modbusAddr, defaults to 03

Device Identification (one of three required)

• inverterSn: Inverter SN, directly identifies the device
• plantId: Plant ID, available from plant query interfaces or real-time data forwarding
• nmiCode: NMI (National Meter Identifier), Australia only

Request Example

curl -X POST "https://{API_DOMAIN}:13333/v2/api/atRead" \
  -H "Content-MD5: {Content-MD5}" \
  -H "Content-Type: application/json;charset=UTF-8" \
  -H "Date: {Date}" \
  -H "Authorization: API {apiId}:{sign}" \
  -d '{
    "inverterSn": "380205022C190102",
    "modbusAddr": "142"
  }'

Response Parameters:

Field	Type	Description
code	String	0=success, others=failure code
msg	String	Result description
orderId	String	Async instruction order ID, use /v2/api/result to query result. If not returned, there is no need to call the result interface
time	String	Timestamp

Response Example:

{
  "msg": "success",
  "code": "0",
  "data": {
    "msg": "1",
    "yuanzhi": "-16143",
    "command": "AT+TEST=GIN485:01 03 a8 66 00 01 44 75",
    "needLoop": "false"
  },
  "orderId": "1688715608012_769",
  "time": "1688715608012"
}

Note

This is an asynchronous interface. After receiving the orderId, use the /v2/api/result interface to query the actual read results. If orderId is not returned in the response, there is no need to call the result interface.

---

Obtain Result via Instruction Order ID — /v2/api/result

Obtain AT instruction execution results via orderId.

Rate limit: 2 times/second

Request Parameters:

Parameter	Type	Required	Description
orderId	String	Yes	Query result details for the specified orderId

Request Example:

curl -X POST "https://{API_DOMAIN}:13333/v2/api/result" \
  -H "Content-MD5: {Content-MD5}" \
  -H "Content-Type: application/json;charset=UTF-8" \
  -H "Date: {Date}" \
  -H "Authorization: API {apiId}:{sign}" \
  -d '{"orderId": "1688715608012_769"}'

Response Parameters:

Field	Type	Description
code	Integer	0=success, others=failure code
msg	String	Result description
data	Array	Result data list

data element fields:

Field	Type	Description
nmiCode	String	nmi code
successNum	String	Number of successful devices
notChangeNum	String	Number of unchanged devices
detail	Array	Detail list with sn and time
errorMsg	String	Error message

Response Example:

{
  "success": true,
  "code": "0",
  "msg": "success",
  "data": [
    {
      "nmiCode": "20025543400",
      "successNum": "1",
      "notChangeNum": "0",
      "detail": [{ "sn": "380205022C190102", "time": 1688715608012 }],
      "errorMsg": ""
    }
  ]
}

Appendix

Appendix 1: Return Status Codes

Code	Description
0	Success
1	Fail
Z0001	Login has expired, please log in again
Z0002	Content MD5 is incorrect
403	No permissions
429	Frequent requests
I0013	Account or password error, please re-enter
B0020	Verification code error
I0012	Account or password error, please re-enter
B0053	This account is already bound to a third-party account
R0004	This feature is only available to some customers. Please contact after-sales
B0107	The collector model does not yet support this function
B0089	The equipment does not belong to the power plant
B0063	The three elements of the equipment have not been stored in the warehouse
B0115	Fail in send
B0124	The device SN does not exist
B0157	Request time exceeds five minutes
R0000	No permissions

Appendix 2: Register Address Reference

For inverter register addresses, refer to the communication protocol documents (see the "Inverter Register Communication Protocol" section at the top of this page).

---

Error Code Reference

For a complete list of code error codes and their descriptions, please refer to Error Codes.