签名

接口概述

所有 OpenAPI 请求都需要在 HTTP 请求头中携带签名信息。生产域名为 https://api.vmos.cn，测试域名为 https://test.vmos.cn。

请求头

名称	类型	必填	说明
x-ak	string	是	访问密钥 ID，由平台分配
x-timestamp	string	是	13 位毫秒时间戳
x-sign	string	是	HMAC-SHA256 计算后的签名
x-merchant	string	是	商户名称
x-nonce	string	是	随机串，建议每次请求唯一

签名规则

待签名字符串格式如下：

timestamp + path + body

• timestamp：与 x-timestamp 请求头保持一致。
• path：完整 API 路径，必须以 / 开头。
• body：
  • GET 请求时为查询参数字符串，没有参数时为空字符串。
  • POST 请求时为紧凑格式 JSON 字符串，不能包含多余空格和换行。

计算方式

使用 HMAC-SHA256(待签名字符串, SecretKey) 计算签名，并将结果转成小写十六进制字符串。

GET 请求示例

https://api.vmos.cn/vmcloud/api/external/getPhoneInfo?equipmentId=12345

参与签名的内容：

timestamp: 1618900299000
path: /vmcloud/api/external/getPhoneInfo
body: equipmentId=12345
待签名字符串: 1618900299000/vmcloud/api/external/getPhoneInfoequipmentId=12345

POST 请求示例

{
  "orderId": 1,
  "configId": 10,
  "goodNum": 10,
  "goodTimeId": 10,
  "openId": "abc",
  "payPrice": 20000
}

参与签名的内容：

timestamp: 1618900400000
path: /vmcloud/api/external/lockGoodStock
body: {"orderId":1,"configId":10,"goodNum":10,"goodTimeId":10,"openId":"abc","payPrice":20000}
待签名字符串: 1618900400000/vmcloud/api/external/lockGoodStock{"orderId":1,"configId":10,"goodNum":10,"goodTimeId":10,"openId":"abc","payPrice":20000}

常见错误

{
  "code": 1307,
  "msg": "签名校验不通过",
  "data": null
}

常见原因包括：

• x-ak 不存在或已禁用
• 签名字符串拼接错误
• JSON 请求体不是紧凑格式
• 请求头格式不正确

Java 示例

String stringToSign = timestamp + path + (body != null ? body : "");
Mac hmacSha256 = Mac.getInstance("HmacSHA256");
SecretKeySpec secretKeySpec = new SecretKeySpec(secretKey.getBytes(StandardCharsets.UTF_8), "HmacSHA256");
hmacSha256.init(secretKeySpec);
byte[] hash = hmacSha256.doFinal(stringToSign.getBytes(StandardCharsets.UTF_8));

Python 示例

string_to_sign = timestamp + path + (body if body else "")
signature = hmac.new(
    secret_key.encode("utf-8"),
    string_to_sign.encode("utf-8"),
    hashlib.sha256
).hexdigest()

完整请求头示例

x-ak: 4d7755d674c74c7d389df9539f0a061d
x-timestamp: 1618900299000
x-sign: 3f2a1b0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4e3f2a1
x-merchant: star-cloud
x-nonce: 26b6ab4d77b24a768a5bc7c1757b09b3