开发者平台

简体中文

English

简体中文

English

主题

设备控制 API（第三方授权） ​

设备控制 API 提供对逆变器的远程控制、参数读取、策略下发和读取功能。适用第三方授权方式，使用 OAuth2.0 认证。

适用授权方式：第三方授权

与用户授权版本的区别

  • 第三方授权（第三方监控平台等）：使用 OAuth2.0，接口路径前缀 /api/control_device/
  • 设备控制（用户授权）：面向云平台用户授权，使用自定义 HMAC-SHA1 签名，接口路径前缀 /v2/api/

API 基础信息 ​

项目说明
API 基础地址https://api-oauth2.soliscloud.com/
请求方式POST
数据更新频率5 分钟

认证方式 ​

所有接口请求需在 HTTP 请求头中携带 OAuth2.0 Bearer Token：

Authorization: Bearer {access_token}

第三方服务商设备控制建议 ​

控制接口优先级

  1. 优先推荐 使用 /api/control_device/strategySetting 接口下发指令
  2. 如无法满足需求，可使用 /api/control_device/control 接口进行辅助控制
  3. 如通用数据转发方式仍无法满足需求，请将需求反馈至对接团队

逆变器寄存器通信协议 ​

设备控制接口中的寄存器地址和指令参数，请参考以下协议文档：

  • 并网逆变器：请联系销售获取
  • 储能逆变器：请联系销售获取

接口概览 ​

控制接口 — /api/control_device/control ​

远程控制单台逆变器设备，支持寄存器地址写入或 AT 指令透传两种方式。

限流：2 次/秒

请求参数：

参数类型必填说明
inverterSnString三选一逆变器 SN
plantIdString三选一电站编码，可从电站相关查询接口或数据转发中获取
nmiCodeString三选一澳洲发电户号（NMI），澳大利亚地区专用
atCommandString否AT 指令透传内容（与 modbusAddr 二选一）
modbusAddrNumber / String否寄存器地址（与 atCommand 二选一，传此参数时需同时传 functionCode）
functionCodeString否（传 modbusAddr 时必填）Modbus 功能码，可选值：03（读取保持寄存器）、04（读取输入寄存器）、06（写入单个寄存器），与 modbusAddr 配套使用
valueNumber否寄存器写入值（modbusAddr 模式时必填）

设备定位（三选一必填）

  • inverterSn：逆变器 SN，直接指定设备
  • plantId：电站编码，可从电站相关查询接口或数据转发中获取
  • nmiCode：澳洲发电户号（NMI），澳大利亚地区专用

请求示例（寄存器地址模式）：

bash
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
  }'

请求示例（AT 指令透传模式）：

bash
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=..."
  }'

响应参数：

字段类型说明
codeString结果代码
msgString结果消息
timeNumber时间戳
dataArray控制结果列表

data 元素字段：

字段类型说明
msgString单台设备结果消息
codeString单台设备结果代码
recvString接收状态
modbusAddrNumber / String下发的寄存器地址
valueNumber下发的寄存器值

响应示例：

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

AT 指令读取 — /api/control_device/atRead ​

异步读取逆变器参数。返回 orderId 用于后续查询结果。

限流：2 次/秒

请求参数：

参数类型必填说明
inverterSnString三选一逆变器 SN
plantIdString三选一电站编码，可从电站相关查询接口或数据转发中获取
nmiCodeString三选一澳洲发电户号（NMI），澳大利亚地区专用
modbusAddrNumber / String是要读取的寄存器地址
functionCodeString否Modbus 功能码，可选值：03（读取保持寄存器）、04（读取输入寄存器），与 modbusAddr 配套使用，不传默认为 03

设备定位（三选一必填）

  • inverterSn：逆变器 SN，直接指定设备
  • plantId：电站编码，可从电站相关查询接口或数据转发中获取
  • nmiCode：澳洲发电户号（NMI），澳大利亚地区专用

请求示例：

bash
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
  }'

响应示例：

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

注意

本接口为异步接口。返回 orderId 后，使用 /api/control_device/result 接口查询实际读取结果。若响应中未返回 orderId，说明无需调用 result 接口。

AT 指令结果 — /api/control_device/result ​

通过 orderId 获取 AT 指令执行结果。

限流：2 次/秒

请求参数：

参数类型必填说明
orderIdString是批量读取返回的订单 ID

响应参数：

字段类型说明
codeString结果代码
msgString结果消息
dataObject读取结果数据

data 字段：

字段类型说明
nmiCodeString采集器 SN
successNumNumber成功读取的设备数量
notChangeNumNumber未变化的设备数量
errorMsgString错误消息

响应示例：

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

策略设置 — /api/control_device/strategySetting ​

批量为多个设备设置策略。

限流：10 次/秒

请求参数：

参数类型必填说明
inverterSnString三选一逆变器 SN
plantIdString三选一电站编码，可从电站相关查询接口或数据转发中获取
nmiCodeString三选一澳洲发电户号（NMI），澳大利亚地区专用
controlSwitchNumber是控制开关，0=关闭，1=开启

设备定位（三选一必填）

  • inverterSn：逆变器 SN，直接指定设备
  • plantId：电站编码，可从电站相关查询接口或数据转发中获取
  • nmiCode：澳洲发电户号（NMI），澳大利亚地区专用
参数类型必填说明
sysImportLmtSwitchNumber否系统输入功率限制开关
sysImportLmtPowerNumber否系统输入功率限制值 (W)
sysExportLmtSwitchNumber否系统输出功率限制开关
sysExportLmtPowerNumber否系统输出功率限制值 (W)
actionListArray否策略动作列表

actionList 元素字段：

参数类型必填说明
actionsNumber是动作类型
beginDateString是开始日期
endDateString是结束日期
powerNumber否功率值 (W)
socLowerLimitNumber否SOC 下限
socUpperLimitNumber否SOC 上限
pvShutdownSwitchNumber否光伏关机开关
doControlSwitchNumber否DO 控制开关
allowGridChargeNumber否允许电网充电开关

动作类型说明

  • actions=1：电池待机
  • actions=2：储能充放电
  • actions=3：并网口输入/输出功率控制
  • actions=5：自发自用模式

功率正数为充电，负数为放电。$NOW 表示立即执行，durationMinutes 指定持续时长（分钟）。

智慧能量策略配置示例 ​

以下示例展示通过 strategySetting 接口下发智慧能量策略的典型场景。时间格式统一为 HH24:MM（24 小时制），功率单位为 W，功率正数表示充电、负数表示放电。

场景一：计划定时策略（全时段调度） ​

按固定时间区间执行多模式轮询调度，适用于日常常态化能量管理。 如果并网口的取送电功率需要进行定时修改，目前可以通过该接口的多次调用（每次调用设置不同的功率值）来实现。

json
{
    "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"
        }
    ]
}

字段补充：

字段说明
allowGridCharge电网补电使能：1 = 允许电网为电池充电，0 = 禁止
socUpperLimit充电电量上限（%），达到限值停止充电
socLowerLimit放电电量下限（%），达到限值停止放电
durationMinutes任务持续时长（分钟），到期后恢复原有策略
场景二：实时控制 — 立即待机 ​

设备即刻进入待机状态，按指定时长保持，结束后恢复原有策略。

json
{
    "inverterSn": "110CA999C999999",
    "controlSwitch": 1,
    "sysImportLmtSwitch": 1,
    "sysImportLmtPower": 8500,
    "sysExportLmtSwitch": 1,
    "sysExportLmtPower": 7500,
    "actionList": [
        {
            "actions": 1,
            "beginDate": "$NOW",
            "durationMinutes": 60
        }
    ]
}
场景三：实时控制 — 立即充电 ​

临时触发储能充电任务，即刻执行并限定运行时长。

json
{
    "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
        }
    ]
}
场景四：实时控制 — 立即放电 ​

临时触发储能放电任务，即刻执行并限定运行时长。

json
{
    "inverterSn": "110CA999C999999",
    "controlSwitch": 1,
    "sysImportLmtSwitch": 1,
    "sysImportLmtPower": 8500,
    "sysExportLmtSwitch": 1,
    "sysExportLmtPower": 7500,
    "actionList": [
        {
            "actions": 2,
            "beginDate": "$NOW",
            "durationMinutes": 60,
            "power": -2500,
            "socLowerLimit": 25
        }
    ]
}
场景五：策略关闭 ​

关闭整体能量调度策略，保留并网功率限制参数，清空动作任务列表。

json
{
    "inverterSn": "110CA999C999999",
    "controlSwitch": 0,
    "sysImportLmtSwitch": 1,
    "sysImportLmtPower": 8500,
    "sysExportLmtSwitch": 1,
    "sysExportLmtPower": 7500,
    "actionList": []
}
通用约束规则 ​
  1. 时间格式：定时时段使用 HH24:MM，取值范围 00:00 ~ 23:59
  2. $NOW：立即执行，无需等待定时，配合 durationMinutes 使用
  3. 功率参数：所有功率值为整型，单位 W
  4. SOC 参数：取值范围 0 ~ 100，代表电池电量百分比
  5. 时段优先级：实时临时指令 > 定时计划策略
  6. 单次请求仅针对单台逆变器（按 inverterSn 唯一匹配）

读取执行策略 — /api/control_device/currentStrategyGet ​

获取当前策略设置。

限流：10 次/秒

请求参数：

参数类型必填说明
inverterSnString是逆变器 SN

注意

面向云平台用户授权接口不包含设备控制 API。设备控制仅在第三方授权下支持。

错误码参考

接口返回的 code 错误码及说明请参考 错误码。