1. 参数签名

API 会对每个访问的请求进行身份验证,即每个请求都需要在公共请求参数中包含签名串(signature)以验证用户身份。

1.1. 安全凭证

1.初次使用销赞云API之前,需要在管理后台开通开放平台权限。安全凭证包括clientID和clientSecret,其中:

  • clientId:用于标识 API 调用者身份。
  • clientSecret:用于加密签名字符串和服务器端验证签名字符串的密钥。

2.为了数据安全,请妥善保存并定期更换clientSecret。

1.2. 生成签名串

有了安全凭证clientId和clientSecret后,就可以生成签名串了。生成签名串的详细过程如下: image.png

假设用户的clientId和clientSecret分别是: clientId:48ca17b00473d5e595ab clientSecret:48ca17b00473d5e595ab48ca17b00473d5e595ab48ca17b00473d5e595ab

这里只是示例,请用户根据自己实际的 clientId 和 clientSecret 和请求参数进行后续操作。

以商品列表接口例,当调用此接口时,其GET请求参数为:

参数名称 描述 参数值
clientId clientID 48ca17b00473d5e595ab
accessToken access token a75e2db38593cbf6e8bc26b9036b8f45**
timestamp 当前时间戳 1609430400
nonce 随机正整数 45234234
signatureMethod 签名方式 HmacSHA256
spuId 待查询的商品ID 1688

1.2.1. 1. 对参数排序

首先对所有请求参数按参数名做字典序升序排列。(所谓字典序升序排列,直观上就如同在字典中排列单词一样排序,按照字母表或数字表里递增顺序的排列次序,即先考虑第一个“字母”,在相同的情况下考虑第二个“字母”,依此类推。)您可以借助编程语言中的相关排序函数来实现这一功能,如 PHP 中的 ksort 函数。上述示例参数的排序结果如下:

{
    "accessToken": "a75e2db38593cbf6e8bc26b9036b8f45ab54ce382bc986c6a9c52e9a527311888ded22d990c54be1",
    "clientId": "48ca17b00473d5e595ab",
    "nonce": "45234234",
    "signatureMethod": "HmacSHA256",
    "spuId": "1688",
    "timestamp": "1609430400"
}

使用其它程序设计语言开发时, 可对上面示例中的参数进行排序,得到的结果一致即可。

1.2.2. 2. 拼接请求字符串

此步骤将生成请求字符串。 将把上一步排序好的请求参数格式化成“参数名称”=“参数值”的形式,如对 clientId 参数,其参数名称为"clientId",参数值为"48ca17b00473d5e595ab",因此格式化后就为 clientId=48ca17b00473d5e595ab

  • “参数值”为原始值而非 URL 编码后的值。
  • 若输入参数的 Key 中包含数组或数组对象,则需要将子级/孙级其转换为.。如spuAttributes[id]=1, 则需要将其转换成spuAttributes.id=1url[0]=https://www.xiaozancloud.com,则需要转成url.0=https://www.xiaozancloud.com

然后将格式化后的各个参数用"&"拼接在一起,最终生成的请求字符串为(请忽略文中的换行):

accessToken=a75e2db38593cbf6e8bc26b9036b8f45ab54ce382bc986c6a9c52e9a527311888ded22d990c54be1
&clientId=48ca17b00473d5e595ab
&nonce=45234234
&signatureMethod=HmacSHA256
&spuId=1688
&timestamp=1609430400

1.2.3. 3. 拼接签名原文字符串

此步骤将生成签名原文字符串。 签名原文字符串的拼接规则为:

请求方法 + 请求主机 +请求路径 + ? + 请求字符串

参数构成说明:

  • 请求方法: 支持 POST 和 GET 方式,这里使用 GET 请求, 注意方法为全大写。
  • 请求主机: 即主机域名,具体请求域名详见各接口说明。
  • 请求路径: API 对应产品的请求路径,,如商品详情请求路径固定为/v1/spu/detail
  • 请求字符串: 即上一步生成的请求字符串。

因此,上述示例的拼接签名原文字符串结果为(请忽略文中的换行):

GETopenapi.xiaozancloud.com/v1/spu/detail?accessToken=a75e2db38593cbf6e8bc26b9036b8f45ab54ce382bc986c6a9c52e9a527311888ded22d990c54be1
&clientId=48ca17b00473d5e595ab
&nonce=45234234
&signatureMethod=HmacSHA256
&spuId=1688
&timestamp=1609430400

1.2.4. 4. 生成签名串

此步骤生成签名串。

计算签名的方法有两种:HmacSHA256 和 HmacSHA1 这里要根据您指定的签名算法(即 signatureMethod 参数)生成签名串。当指定 signatureMethod 为 HmacSHA256 时,需要使用 HmacSHA256 计算签名,其他情况请使用 HmacSHA1 计算签名。

首先使用签名算法(HmacSHA256 或 HmacSHA1)对上一步中获得的 签名原文字符串 进行签名,然后将生成的签名串使用 Base64 进行编码,即可获得最终的签名串。

具体代码如下,以 PHP 语言为例,由于本例中所用的签名算法为 HmacSHA256,因此生成签名串的代码如下(使用其它程序设计语言开发时,可用上述示例中的原文字符串进行签名验证,得到的签名串与例子中的一致即可):

$secretKey = '48ca17b00473d5e595ab48ca17b00473d5e595ab48ca17b00473d5e595ab';
$srcStr = 'GETopenapi.xiaozancloud.com/v1/spu/detail?accessToken=a75e2db38593cbf6e8bc26b9036b8f45ab54ce382bc986c6a9c52e9a527311888ded22d990c54be1&clientId=48ca17b00473d5e595ab&nonce=45234234&signatureMethod=HmacSHA256&spuId=1688&timestamp=1609430400';
$signStr = base64_encode(hash_hmac('sha256', $srcStr, $secretKey, true));
echo $signStr;

最终得到的签名串为:

WIx0BB27is6lN4PbkfIhwUjxxzWIlhp/ao3frtLSsuk=

同理,当您指定签名算法为 HmacSHA1 时,生成签名串的代码如下:

$secretKey = '48ca17b00473d5e595ab48ca17b00473d5e595ab48ca17b00473d5e595ab';
$srcStr = 'GETopenapi.xiaozancloud.com/v1/spu/detail?accessToken=a75e2db38593cbf6e8bc26b9036b8f45ab54ce382bc986c6a9c52e9a527311888ded22d990c54be1&clientId=48ca17b00473d5e595ab&nonce=45234234&signatureMethod=HmacSHA256&spuId=1688&timestamp=1609430400';
$signStr = base64_encode(hash_hmac('sha1', $srcStr, $secretKey, true));
echo $signStr;

最终得到的签名串为:

i6bf6s4HVnG6L/iPogdAdntUpmI=

1.3. 签名串编码

生成的签名串并不能直接作为请求参数,需要对其进行 URL 编码。 如上一步生成的签名串为WIx0BB27is6lN4PbkfIhwUjxxzWIlhp/ao3frtLSsuk=,则其编码后为WIx0BB27is6lN4PbkfIhwUjxxzWIlhp%2Fao3frtLSsuk%3D。因此,最终得到的签名串请求参数 (signature) 为:WIx0BB27is6lN4PbkfIhwUjxxzWIlhp%2Fao3frtLSsuk%3D,它将用于生成最终的请求URL。

如果用户的请求方法是 GET,则对所有请求参数的参数值均需要做 URL 编码;此外,部分语言库会自动对 URL 进行编码,重复编码会导致签名校验失败。

1.4. 鉴权失败

当鉴权不通过时,可能出现如下表的错误:

错误代码 错误类型 错误描述
1002 权限受限 请求的scope无效、未授权或格式错误
1003 参数错误 缺少必要参数,具体见接口传参要求
1004 client认证失败 client未授权、未开通api权限或已失效
1005 请求的次数超过了速率限制, x秒后再试 接口调用频繁,触发限流,需要减少调用次数。
1010 签名验证失败 签名不一致,请确保请求参数中的signature 按照上述步骤计算正确,特别注意 signature 要做 url 编码后再发起请求。
1011 accessToken验证失败 accessToken不存在或已过期失效。
1500 系统内部错误 接口调用稍后重试。

results matching ""

    No results matching ""