开发规范

1. 接口域名说明

HTTP 请求 URL 约定如下：

请求类型	域名
HTTP POST 请求	https://openapi.lechange.cn:443/openapi/[method]

2. HTTP 请求数据格式说明

开放平台 HTTP 请求格式约定如下：

参数列表		参数类型	参数说明
system	ver	String	协议版本信息，当前为1.0
	sign	String	签名值，平台用来做签名校验。计算步骤见下文第4节
	appId	String	appId，控制台-我的应用-应用信息中获取
	time	Long	发起接口调用的客户端时间戳（UTC时间戳，单位为秒），该时间与当前时间戳误差不能超过5分钟，否则返回SN1002错误码
	nonce	String	随机数（32位），nonce值在5分钟内不能重复使用，否则返回SN1005错误码
params		Map	HTTP接口方法使用的参数集合，value为组装好的Map对象
id		String	请求唯一标示ID，每次请求调用时传入唯一非空字符串。建议使用随机数

以获取管理员账号 accessToken 接口为例，请求数据格式如下：

{
  "system": {
    "ver": "1.0",
    "appId": "lcdxxxxxxxxx",
    "sign": "xjhCQBoJ9hRDsCjyDcHjtDNzRZ3ZJezcawsfWeiaoxU=",
    "time": 1706511734,
    "nonce": "f5a1ae2d-c09c-4d39-a744-83a5c2c653c2"
  },
  "id": "98a7a257-c4e4-4db3-a2d3-d97a3836b87c",
  "params": {}
}

3. HTTP 响应应答格式说明

开放平台 HTTP 请求响应返回格式约定如下：

字段列表		字段类型	字段说明
result	code	String	请求返回码，具体详见全局返回码说明
	msg	String	请求返回码详情描述，具体详见全局返回码说明
	data	Map	请求接口返回的具体内容信息，value为组装好的Map对象
id		String	请求接口时开发者传入的id

以获取管理员账号 accessToken 接口为例，响应数据格式如下：

{
  "result": {
    "msg": "操作成功。",
    "code": "0",
    "data": {
      "expireTime": 259176,
      "accessToken": "At_00006ac6e32d123141238f60147de7ec"
    }
  },
  "id": "98a7a257-c4e4-4db3-a2d3-d97a3836b87c"
}

4. HTTP 鉴权 sign 计算说明

4.1 计算步骤

生成“签名原始串”：将 time、nonce、appSecret 三个参数按键值对拼接，顺序为 time → nonce → appSecret，中间以英文逗号分隔（编码格式 UTF-8）：

签名原始串 = time:{time},nonce:{nonce},appSecret:{appSecret}

appSecret 请在控制台-我的应用-应用信息中获取。

派生签名密钥 password：对 appSecret 做 SHA-256，结果转为 小写十六进制字符串：

password = LowerCase(Hex(SHA-256(appSecret)))

计算 sign：以 password 为密钥，对“签名原始串”做 HMAC-SHA256，再将结果做 Base64 编码：

sign = Base64(HMAC-SHA256(签名原始串, password))

4.2 代码示例（Java）

import org.apache.commons.codec.digest.DigestUtils;

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.text.MessageFormat;
import java.time.Instant;
import java.util.Base64;
import java.util.UUID;

/**
 * 计算 sign 示例
 */
// 1、获取当前时间戳（UTC，秒）
Long time = Instant.now().getEpochSecond();
// 2、获取随机数
String nonce = UUID.randomUUID().toString();
// 3、真实appSecret请在 控制台-我的应用 中获取，下方只是示例值
String appSecret = "test123456789test123456789";
// 4、生成原始串
String SIGN_TEMPLATE = MessageFormat.format(
        "time:{0},nonce:{1},appSecret:{2}", time.toString(), nonce, appSecret);
// 5、派生 password = LowerCase(Hex(SHA-256(appSecret)))
String password = DigestUtils.sha256Hex(appSecret).toLowerCase();
// 6、计算 sign = Base64(HMAC-SHA256(SIGN_TEMPLATE, password))
Mac mac = Mac.getInstance("HmacSHA256");
mac.init(new SecretKeySpec(password.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
byte[] digest = mac.doFinal(SIGN_TEMPLATE.getBytes(StandardCharsets.UTF_8));
String sign = Base64.getEncoder().encodeToString(digest);

4.3 标准案例

可按下列固定入参在本地试跑；若计算结果与案例一致，则代表计算过程正确。

入参	值
time	`1706511734`
nonce	`f5a1ae2d-c09c-4d39-a744-83a5c2c653c2`
appSecret	`test123456789test123456789`

步骤 1 — 签名原始串：

time:1706511734,nonce:f5a1ae2d-c09c-4d39-a744-83a5c2c653c2,appSecret:test123456789test123456789

步骤 2 — 派生 password：

1f2da89b2fab404859f02bcc80e8521bc7a63af3e5b1da5318f7cf7c56836b09

步骤 3 — 计算 sign：

xjhCQBoJ9hRDsCjyDcHjtDNzRZ3ZJezcawsfWeiaoxU=

最终标准 https 请求体中 system 参数示例如下：

{
  "system": {
    "ver": "1.0",
    "appId": "lcdxxxxxxxxx",
    "sign": "xjhCQBoJ9hRDsCjyDcHjtDNzRZ3ZJezcawsfWeiaoxU=",
    "time": 1706511734,
    "nonce": "f5a1ae2d-c09c-4d39-a744-83a5c2c653c2"
  },
  "id": "98a7a257-c4e4-4db3-a2d3-d97a3836b87c",
  "params": {}
}