Device Control API (OAuth2.0)

The Device Control API provides remote control, parameter reading, strategy configuration, and strategy retrieval capabilities for inverters. This version uses OAuth2.0 Bearer Token authentication.

Authorization method: OAuth2.0 Authorization

Comparison with User-level Authorization Version

• OAuth2.0 Authorization (this document): Intended for third-party platforms and monitoring integrations. Endpoint prefix: /api/control_device/
• Device Control (User Auth): Intended for plant owners and installers. Uses Custom HMAC-SHA1 Signature. Endpoint prefix: /v2/api/

Overview

Item	Details
API Base URL	https://api-oauth2.soliscloud.com/
Request Method	POST
Data Update Frequency	Every 5 minutes

Authentication

All requests must include a valid OAuth2.0 Bearer Token in the HTTP request header:

Authorization: Bearer {access_token}

Device Control Recommendations

Recommended Control Priority

1. First choice: Use /api/control_device/strategySetting for strategy-based dispatch command issuance
2. If strategy dispatch does not meet your requirements, use /api/control_device/control as a supplementary control method
3. If neither approach satisfies your use case, please reach out to the integration team with your specific requirements

Inverter Register Communication Protocol

For register addresses and command parameters referenced in the device control endpoints, please consult the following protocol documentation:

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

Interface Overview

Control Interface — /api/control_device/control

Direct control of a single inverter device, supporting register address write or AT command pass-through.

Rate Limit: 2 times/second

Request Parameters:

Parameter	Type	Required	Description
inverterSn	String	One of three	Inverter SN
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	N	AT command pass-through content (either this or modbusAddr)
modbusAddr	Number / String	N	Register address (either this or atCommand, requires functionCode)
functionCode	String	N (required when using modbusAddr)	Modbus function code. Options: 03 (Read Holding Registers), 04 (Read Input Registers), 06 (Write Single Register). Used with modbusAddr
value	Number	N	Register write value (required when using 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

Request Example (Register Address Mode):

curl -X POST "https://{API_OAUTH2_DOMAIN}/api/control_device/control" \
  -H "Content-Type: application/json;charset=UTF-8" \
  -H "Authorization: Bearer {access_token}" \
  -d '{
    "inverterSn": "SC2024010001",
    "modbusAddr": 48,
    "functionCode": "06",
    "value": 190
  }'

Request Example (AT Command Pass-through Mode):

curl -X POST "https://{API_OAUTH2_DOMAIN}/api/control_device/control" \
  -H "Content-Type: application/json;charset=UTF-8" \
  -H "Authorization: Bearer {access_token}" \
  -d '{
    "inverterSn": "SC2024010001",
    "atCommand": "AT+CMD=..."
  }'

Response Parameters:

Field	Type	Description
code	String	Result code
msg	String	Result message
time	Number	Timestamp
data	Array	Control result list

data element fields:

Field	Type	Description
msg	String	Single device result message
code	String	Single device result code
recv	String	Receive status
modbusAddr	Number / String	Dispatched register address
value	Number	Dispatched register value

Response Example:

{
  "code": "0",
  "msg": "success",
  "time": 1688715608012,
  "data": [
    {
      "msg": "success",
      "code": "0",
      "recv": "1",
      "modbusAddr": 48,
      "value": 190
    }
  ]
}

AT Command Read — /api/control_device/atRead

Read inverter parameters asynchronously. Returns orderId for querying results later.

Rate Limit: 2 times/second

Request Parameters:

Parameter	Type	Required	Description
inverterSn	String	One of three	Inverter SN
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
modbusAddr	Number / String	Y	Register address to read
functionCode	String	N	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_OAUTH2_DOMAIN}/api/control_device/atRead" \
  -H "Content-Type: application/json;charset=UTF-8" \
  -H "Authorization: Bearer {access_token}" \
  -d '{
    "inverterSn": "SC2024010001",
    "modbusAddr": 142
  }'

Response Example:

{
  "code": "0",
  "msg": "success",
  "orderId": "1688715608012_769",
  "data": {},
  "time": 1688715608012
}

Note

This interface is asynchronous. After returning orderId, use the /api/control_device/result interface to query the actual reading result. If orderId is not returned in the response, there is no need to call the result interface.

AT Command Result — /api/control_device/result

Get AT command execution result through orderId.

Rate Limit: 2 times/second

Request Parameters:

Parameter	Type	Required	Description
orderId	String	Y	Order ID returned by batch read

Response Parameters:

Field	Type	Description
code	String	Result code
msg	String	Result message
data	Object	Reading result data

data fields:

Field	Type	Description
nmiCode	String	Data collector SN
successNum	Number	Number of successfully read devices
notChangeNum	Number	Number of unchanged devices
errorMsg	String	Error message

Response Example:

{
  "code": "0",
  "msg": "success",
  "data": {
    "nmiCode": "20025543400",
    "successNum": 1,
    "notChangeNum": 0,
    "errorMsg": ""
  }
}

Strategy Setting — /api/control_device/strategySetting

Batch strategy setting for multiple devices.

Rate Limit: 10 times/second

Request Parameters:

Parameter	Type	Required	Description
inverterSn	String	One of three	Inverter SN
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
controlSwitch	Number	Y	Control switch, 0=off, 1=on

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

Parameter	Type	Required	Description
sysImportLmtSwitch	Number	N	System input power limit switch
sysImportLmtPower	Number	N	System input power limit value (W)
sysExportLmtSwitch	Number	N	System output power limit switch
sysExportLmtPower	Number	N	System output power limit value (W)
actionList	Array	N	Strategy action list

actionList element fields:

Parameter	Type	Required	Description
actions	Number	Y	Action type
beginDate	String	Y	Start date
endDate	String	Y	End date
power	Number	N	Power value (W)
socLowerLimit	Number	N	SOC lower limit
socUpperLimit	Number	N	SOC upper limit
pvShutdownSwitch	Number	N	PV shutdown switch
doControlSwitch	Number	N	DO control switch
allowGridCharge	Number	N	Allow grid charge switch

Action Type Description

• actions=1: Battery standby
• actions=2: ESS Charge/Discharge
• actions=3: Grid point import/export power control
• actions=5: Self-Consumption Mode

Positive power = charging; negative power = discharging. Use $NOW for immediate execution; durationMinutes sets the duration in minutes.

Smart Energy Strategy Configuration Examples

The following examples demonstrate typical scenarios for delivering smart energy strategies via the strategySetting endpoint. Time format is unified as HH24:MM (24-hour), power unit is Watt (W), positive values indicate charging and negative values indicate discharging.

Scenario 1: Scheduled Timing Strategy (Full Period Scheduling)

Execute multi-mode polling scheduling based on fixed time intervals, applicable to daily regular energy management.

If the power input and output at the grid-connection port need to be adjusted at specific intervals, this can currently be achieved by calling this interface multiple times (setting a different power value with each call).

{
    "inverterSn": "110CA999C999999",
    "controlSwitch": 1,
    "sysImportLmtSwitch": 1,
    "sysImportLmtPower": 8500,
    "sysExportLmtSwitch": 1,
    "sysExportLmtPower": 7500,
    "actionList": [
        {
            "actions": 1,
            "beginDate": "00:00",
            "endDate": "06:00"
        },
        {
            "actions": 2,
            "beginDate": "06:00",
            "endDate": "12:00",
            "power": 3500,
            "socUpperLimit": 95,
            "allowGridCharge": 1
        },
        {
            "actions": 2,
            "beginDate": "12:00",
            "endDate": "18:00",
            "power": -2500,
            "socLowerLimit": 25
        },
        {
            "actions": 5,
            "beginDate": "18:00",
            "endDate": "23:59"
        }
    ]
}

Supplementary fields:

Field	Description
allowGridCharge	Grid charging enable: 1 = allow grid to charge battery, 0 = prohibit
socUpperLimit	Maximum charging SOC limit (%), charging stops when threshold is reached
socLowerLimit	Minimum discharging SOC limit (%), discharging stops when threshold is reached
durationMinutes	Task duration in minutes; device restores original strategy after expiry

Scenario 2: Real-Time Control — Immediate Standby

Device enters standby mode immediately and maintains the state for a specified duration, then restores the original strategy.

{
    "inverterSn": "110CA999C999999",
    "controlSwitch": 1,
    "sysImportLmtSwitch": 1,
    "sysImportLmtPower": 8500,
    "sysExportLmtSwitch": 1,
    "sysExportLmtPower": 7500,
    "actionList": [
        {
            "actions": 1,
            "beginDate": "$NOW",
            "durationMinutes": 60
        }
    ]
}

Scenario 3: Real-Time Control — Immediate Charging

Trigger a temporary ESS charging task that executes immediately with a limited running duration.

{
    "inverterSn": "110CA999C999999",
    "controlSwitch": 1,
    "sysImportLmtSwitch": 1,
    "sysImportLmtPower": 8500,
    "sysExportLmtSwitch": 1,
    "sysExportLmtPower": 7500,
    "actionList": [
        {
            "actions": 2,
            "beginDate": "$NOW",
            "durationMinutes": 60,
            "power": 3500,
            "socUpperLimit": 95,
            "allowGridCharge": 1
        }
    ]
}

Scenario 4: Real-Time Control — Immediate Discharging

Trigger a temporary ESS discharging task that executes immediately with a limited running duration.

{
    "inverterSn": "110CA999C999999",
    "controlSwitch": 1,
    "sysImportLmtSwitch": 1,
    "sysImportLmtPower": 8500,
    "sysExportLmtSwitch": 1,
    "sysExportLmtPower": 7500,
    "actionList": [
        {
            "actions": 2,
            "beginDate": "$NOW",
            "durationMinutes": 60,
            "power": -2500,
            "socLowerLimit": 25
        }
    ]
}

Scenario 5: Strategy Deactivation

Disable the global energy scheduling strategy, preserve grid power limit parameters, and clear the task list.

{
    "inverterSn": "110CA999C999999",
    "controlSwitch": 0,
    "sysImportLmtSwitch": 1,
    "sysImportLmtPower": 8500,
    "sysExportLmtSwitch": 1,
    "sysExportLmtPower": 7500,
    "actionList": []
}

General Constraints & Rules

1. Time format: scheduled periods use HH24:MM, range 00:00 ~ 23:59
2. $NOW: execute immediately without scheduled delay, used with durationMinutes
3. Power parameters: all power values are integers, unit W
4. SOC parameters: range 0 ~ 100, representing battery state of charge percentage
5. Priority rule: real-time temporary commands > scheduled timing strategies
6. A single request only targets one single inverter matched by unique inverterSn

Current Strategy Get — /api/control_device/currentStrategyGet

Get current strategy settings.

Rate Limit: 10 times/second

Request Parameters:

Parameter	Type	Required	Description
inverterSn	String	Y	Inverter SN

Note

User-level authorization interfaces do not include device control APIs. Device control is only supported under OAuth2.0 authorization.

---

Error Code Reference

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