开发者平台

简体中文

English

简体中文

English

主题

常见问题 ​

通用问题 ​

如何申请 API 权限？

当前开发者平台注册功能尚未上线，所有 API 权限开通均需通过邮件申请,请参考快速开始页面。

面向云平台用户授权和第三方授权有什么区别？
对比项面向云平台用户授权第三方授权
适用对象业主和安装商第三方服务商、第三方监控平台
账号要求需有锦浪云可登录账号无需锦浪云账号
认证方式自定义 HMAC-SHA1 签名OAuth2.0
数据范围自己拥有或共享的电站经业主授权后的电站
API 调用频率限制是多少？
  • 数据获取接口：10 次/秒
  • 设备控制接口（control / atRead / result）：2 次/秒
  • 策略接口（strategySetting / currentStrategyGet）：10 次/秒
  • 电站月/年发电量列表：10 次/秒

如无法满足业务需求，建议使用 实时数据转发 方式。

数据更新频率是多久？

设备数据更新频率为 5 分钟。

授权相关问题 ​

HMAC-SHA1 签名算法详解：请求头怎么算？sign error 怎么排查？

面向云平台用户授权（业主/安装商）采用自定义 HMAC-SHA1 签名，每次请求需在 Header 中携带 4 个参数：

Header 参数说明
Content-MD5Body 内容做 MD5 得到 128 位二进制，再 Base64 编码
Content-Type固定值 application/json;charset=UTF-8
DateGMT 时间，格式 EEE, d MMM yyyy HH:mm:ss 'GMT'，偏差不能超过 ±15 分钟
AuthorizationAPI {apiId}:{sign}

签名串按以下顺序用换行符 \n 拼接：

POST\n{Content-MD5}\n{Content-Type}\n{Date}\n{CanonicalizedResource}

其中：

  • CanonicalizedResource：要访问的接口路径，如 /v1/api/userStationList
  • sign = Base64(HmacSHA1(apiSecret, 上述签名串))

签名校验工具

如何判断计算是否正确 ​

用官方示例反推校验。以请求体 {"pageNo":1,"pageSize":10} 为例，其 Content-MD5 固定为：

kxdxk7rbAsrzSIWgEwhH4w==

用自己的代码对 {"pageNo":1,"pageSize":10} 计算 MD5 + Base64：

  • 结果等于 kxdxk7rbAsrzSIWgEwhH4w==，说明 Content-MD5 这一步正确；
  • 结果不一致，请检查是否对 Body 原始字符串（未做 URL 编码、无多余空格）取 MD5，以及是否对 128 位二进制数组做 Base64。

sign error 排查清单 ​

如果接口返回 sign error 或签名验证失败，逐项检查：

  • Authorization 头格式是否为 API {apiId}:{sign}（注意 API 后有空格）
  • 签名字符串拼接顺序：POST\n{Content-MD5}\n{Content-Type}\n{Date}\n{CanonicalizedResource}
  • Content-Type 签名串中的值必须与实际发送的请求头一致（application/json;charset=UTF-8）
  • Date 与服务器时间偏差不超过 ±15 分钟，格式为 EEE, d MMM yyyy HH:mm:ss 'GMT'
  • Content-MD5 为请求 Body 的 MD5 值经 Base64 编码后的字符串（不是 hex 字符串）
  • CanonicalizedResource 是否为完整的接口路径（含 /v1/api/ 或 /v2/api/ 前缀）

完整多语言（Python / Node.js / Java）代码示例请参考 授权方式。

KeySecret 泄露了怎么办？

请立即登录锦浪云 WEB 端，进入 服务 → API 管理，重新开通或更换密钥。

Access Token 过期了怎么办？

OAuth2.0 的 Access Token 有效期为 1 天，Refresh Token 有效期为 30 天。请在 Refresh Token 过期前调用刷新接口获取新的 Token。

如果 Refresh Token 也已过期，需要重新走完整的授权流程。

授权码有效期是多久？

授权码有效期为 30 分钟，且只能使用一次。请在获取后及时换取 Access Token。

接口调用问题 ​

调用接口返回 "时间偏差过大" 怎么办？

面向云平台用户授权接口要求请求头中的 Date 字段与服务器时间偏差不能超过 正负 15 分钟。请检查本地服务器时间是否准确，并使用 GMT 时区格式。

如何批量查询多个设备？

数据获取接口支持通过 snList（逆变器/采集器）或 idList（电站）参数批量查询。单次调用最多返回 100 台 设备数据。游标分页参数 minId（起始 ID）已上线，深翻页请使用 minId 游标（传入上一页最后一条记录的 id + 1）继续获取，详见 分页说明。

控制接口中的 `modbusAddr` 是什么？

modbusAddr（Modbus 寄存器地址）是设备控制接口中下发指令的寄存器定位标识，需配合 value（写入值）和 functionCode（功能码：03/04/06）使用。不同寄存器地址对应不同的控制功能（如功率限制、工作模式切换等）。具体寄存器地址定义请参考 设备控制 文档中的寄存器通信协议。

此外也可通过 atCommand 参数直接透传 AT 指令字符串。

关于 cid

早期基于 cid（Control ID）的控制方式将逐步废弃，建议新接入使用 modbusAddr 方案。

电站管理问题 ​

如何新增电站并绑定逆变器？

使用电站管理接口中的 addStationBindCollector 接口新增电站并绑定采集器。如需绑定逆变器，可使用 addDevice 接口。

电站分享给第三方后如何取消？

可通过电站管理接口中的电站解绑/取消分享接口操作，或在锦浪云 App/WEB 端的电站分享管理中手动取消。

实时数据转发问题 ​

实时数据转发支持哪些协议？

支持 RocketMQ、MQTT、HTTP 三种推送方式，可根据自身业务场景选择。

实时数据推送有频率限制吗？

实时数据转发为秒级推送，无频率限制，适合高频数据采集场景。

常见故障排查 ​

接口返回 404 怎么处理？

404 表示请求的接口路径不存在，常见原因：

  • 接口路径拼写错误：请检查路径是否与文档完全一致，注意大小写和斜杠
  • 使用了错误版本的接口：不同授权方式与接口类别的路径前缀不同，请勿混用：
    • 用户授权（HMAC）：数据获取、电站管理为 /v1/api/，设备控制为 /v2/api/
    • 第三方授权（OAuth2.0）：数据获取为 /api/access_data/，设备控制为 /api/control_device/
  • Authorization 类型与接口不匹配：HMAC 签名接口不支持 Bearer Token，反之亦然
接口返回 500 怎么处理？

500 表示服务端内部错误，建议：

  1. 检查请求参数是否符合文档要求（必填项、数据类型、格式）
  2. 检查 Content-MD5 计算是否正确（需对请求 Body 做 MD5 后转 Base64）
  3. 稍后重试，如持续出现请联系对接团队并提供请求示例和时间戳
  4. 检查请求 Body 是否为有效的 JSON 格式，Content-Type 是否为 application/json;charset=UTF-8
连接超时 / 请求无响应怎么处理？
  • 域名解析问题：确认使用的 API 域名正确（国内：api.ginlong.com，国际：www.soliscloud.com）
  • 网络访问限制：检查服务器防火墙或出站规则是否允许访问 API 域名的 443 端口
  • 频率限制：数据获取接口限流 10 次/秒，控制接口限流 2 次/秒；如超限会触发限流，建议增加重试间隔
  • 设置合理超时时间：建议客户端超时时间设置为 30 秒
OAuth2.0 返回 401 / token 无效怎么处理？
  • 检查 Authorization 头格式：Bearer {access_token}，注意大写 B
  • Access Token 有效期为 1 天，过期后需使用 Refresh Token 重新获取
  • Refresh Token 有效期为 30 天，过期后需重新走完整的授权流程
  • 确认 Token 是否来自正确的授权环境（国内 / 国际域名不互通）

其他问题 ​

支持哪些语言？

当前开发者平台文档支持 简体中文 和 英文。部分 API 接口可通过 lang 参数控制返回数据的语言。