设备控制 API（用户授权）

设备控制 API 提供对逆变器的远程控制和参数读取功能。适用面向云平台用户授权方式，使用自定义 HMAC-SHA1 签名认证。

适用授权方式：面向云平台用户授权

与第三方授权版本的区别

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

API 基础信息

项目	说明
API 基础地址	https://www.soliscloud.com:13333/
请求方式	POST

认证方式

所有接口请求使用自定义 HMAC-SHA1 签名认证。认证方式详见 面向云平台用户授权。

请求头格式：

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

Sign 计算方式：

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

逆变器寄存器通信协议

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

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

通用响应格式

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

字段	类型	说明
success	Boolean	true=成功，false=失败
code	String	0=成功，其他为失败码
msg	String	code 的文字描述
data	Object	各接口返回数据，详见各接口说明

---

接口概览

远程控制单台逆变器 — /v2/api/control

对单台或多台逆变器下发控制指令，支持所有 Solis 设备。

限流：2 次/秒

请求参数：

参数	类型	必填	说明
inverterSn	String	三选一	逆变器 SN，多台用英文逗号分隔
plantId	String	三选一	电站编码，可从电站相关查询接口或数据转发中获取
nmiCode	String	三选一	澳洲发电户号（NMI），澳大利亚地区专用
atCommand	String	否（与 modbusAddr 二选一）	AT 指令透传字符串。如 AT+TEST=GIN485:01 06 0B BE 00 BE
modbusAddr	Number / String	否（与 atCommand 二选一）	Modbus 寄存器地址，需配合 value 和 functionCode 使用
functionCode	String	否（传 modbusAddr 时必填）	Modbus 功能码，可选值：03（读取保持寄存器）、04（读取输入寄存器）、06（写入单个寄存器），与 modbusAddr 配套使用
value	String	否（传 modbusAddr 时必填）	设置值，需配合 modbusAddr 使用

设备定位（三选一必填）

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

控制方式（二选一必填）

1. atCommand：直接透传 AT 指令字符串
2. modbusAddr + value：直接指定 Modbus 寄存器地址和设置值

请求示例 — 方式 1：AT 指令透传

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

请求示例 — 方式 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"
  }'

响应参数：

字段	类型	说明
code	String	0=成功，其他为失败码
msg	String	结果描述
time	Long	返回时间戳
data	Array	控制结果列表

data 元素字段：

字段	类型	说明
msg	String	单台设备结果描述
code	Integer	单台设备结果码
recv	String	接收到的报文
command	String	发送的 AT 指令

响应示例：

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

---

读取多设备参数值 — /v2/api/atRead

异步读取单台或多台逆变器的当前参数值，返回 orderId 用于后续查询结果。

限流：2 次/秒

请求参数：

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

设备定位（三选一必填）

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

请求示例

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

响应参数：

字段	类型	说明
code	String	0=成功，其他为失败码
msg	String	结果描述
orderId	String	异步指令订单 ID，通过 /v2/api/result 接口查询结果。若未返回此字段，说明无需调用 result 接口
time	String	时间戳

响应示例：

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

注意

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

---

通过订单 ID 获取结果 — /v2/api/result

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

限流：2 次/秒

请求参数：

参数	类型	必填	说明
orderId	String	是	指定 orderId 查询结果详情

请求示例：

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

响应参数：

字段	类型	说明
code	Integer	0=成功，其他为失败码
msg	String	结果描述
data	Array	结果数据列表

data 元素字段：

字段	类型	说明
nmiCode	String	nmi 码
successNum	String	成功设备数量
notChangeNum	String	未变化设备数量
detail	Array	详情列表，包含 sn 和 time
errorMsg	String	错误消息

响应示例：

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

附录

附录1 返回状态码

返回值	描述
0	成功
1	失败
Z0001	登录已过期，请重新登录
Z0002	Content MD5 不正确
403	无权限
429	请求频率过高
I0013	账号或密码错误，请重新输入
B0020	验证码错误
I0012	账号或密码错误，请重新输入
B0053	该账号已绑定第三方账号
R0004	该功能仅向部分客户开放，请联系售后
B0107	采集器型号暂不支持此功能
B0089	设备不属于该电站
B0063	设备三要素未入库
B0115	发送失败
B0124	设备 SN 不存在
B0157	请求时间超过五分钟
R0000	无权限

附录2 寄存器地址参考

逆变器寄存器地址请参考通信协议文档（见页面顶部「逆变器寄存器通信协议」章节）。

---

错误码参考

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