签名规则一
开发: appid:119293597114721214
appkey:bXl5JRsKPn74xhAcy7VZARrIDHkSLfD5
登陆地址:https://hscp.dev.harsonserver.com/openapi
订单地址:https://hspay.dev.harsonserver.com/openapi
---
测试: appid:119293597114721214
appkey:bXl5JRsKPn74xhAcy7VZARrIDHkSLfD5
登陆地址:https://hscp.test.harsonserver.com/openapi
订单地址:https://hspay.test.harsonserver.com/openapi
---
正式: appid:31370874921755649
appkey:NAropsvXehl0SMLcKCRls0xo9WITiVkb
登陆地址:https://hscp.cloud.harsonserver.com/openapi
订单地址:https://hspay.cloud.harsonserver.com/openapi
一、接口协议约定
=================
1、所有接口提交或返回的数据以JSON格式传输。
2、所有参数名称及加密后字符(包含签名),默认使用小写,除非有特别约定的地方会有特殊说明。
3、请求数据格式如下:
{
"company_name": "abcdef",
"code_name": "001",
"short_name": "a",
}
4、有些接口需要客户端对数据进行加密,其请求数据格式如下:
1) JSON(application/json):
{
"encrypted_data": "U2FsdGVkX18y5aFF83lg4Mc8+AMZNoVXYQ9dSB+YP5ld2RIRJkoU35f/4owrSelE+1j8AzR3vKESchs+/pYnqHI7h4U0nWM90LSlZ+wqeEI=",
"timestamp": 1542872055207,
"sign": "U2FsdGVkX18y5a"
}
2) 表单(application/x-www-form-urlencoded)方式提交:
encrypted_data=U2FsdGVkX18y5aFF83lg4Mc8+AMZNoVXYQ9dSB+YP5ld2RIRJkoU35f/4owrSelE+1j8AzR3vKESchs+/pYnqHI7h4U0nWM90LSlZ+wqeEI=&sign=U2FsdGVkX18y5a×tamp=1542872055207
3) 采用URL查询参数,要注意用`encodeURIComponent`将加密的内容编一下码:
encrypted_data=U2FsdGVkX18y5aFF83lg4Mc8%2BAMZNoVXYQ9dSB%2BYP5ld2RIRJkoU35f%2F4owrSelE%2B1j8AzR3vKESchs%2B%2FpYnqHI7h4U0nWM90LSlZ%2BwqeEI%3D&sign=U2FsdGVkX18y5a×tamp=1542872055207
* 加密规则:(暂时所有接口没有开启加密)
1) 数据加密使用 AES。
2) AES 算法(256,ECB,补码方式:PKCS5Padding)。
3) AES 密文使用 base64 编码
4) 数据加密密钥为 appkey
5) 加密内容为整个要提交的JSON内容。
6) 加密内容使用固定的属性名:`encrypted_data`。
5、有些接口会对返回来的数据进行加密,加密规则如上,客户端可以按上面的规则进行解密,其返回的数据格式如下:
1) JSON(application/json):
{
"encrypted_data": "U2FsdGVkX18y5aFF83lg4Mc8+AMZNoVXYQ9dSB+YP5ld2RIRJkoU35f/4owrSelE+1j8AzR3vKESchs+/pYnqHI7h4U0nWM90LSlZ+wqeEI="
}
2) 其它格式,直接返回加密内容:
U2FsdGVkX18y5aFF83lg4Mc8+AMZNoVXYQ9dSB+YP5ld2RIRJkoU35f/4owrSelE+1j8AzR3vKESchs+/pYnqHI7h4U0nWM90LSlZ+wqeEI=
6、所有请求(包含GET、POST、DELETE、PUT等)都要设置access_token参数,可以使用以下三种方式设置:
1) 放在Header的认证头里(推荐这种方式):
Authorization: 'Bearer '+ access_token
2) 直接放在Header头里:
X-Token: access_token
3) 放在URL查询参数里:
token=access_token
7、所有的 POST、PUT、PATCH 请求都必须带签名,签名可以使用以下三种方式携带
1) 放到Header头里传递:
X-Sign: 6KGo5Y2V5oiWVVJM5p+l6K+i5Y+C5pWw
X-timestamp: 1542872055207
2) 表单(application/x-www-form-urlencoded)方式提交:
data=xxx&sign=6KGo5Y2V5oiWVVJM5p+l6K+i5Y+C5pWw×tamp=1542872055207
3) 采用URL查询参数,要注意用`encodeURIComponent`将签名的内容编一下码:
data=xxx&sign=6KGo5Y2V5oiWVVJM5p%2Bl6K%2Bi5Y%2BC5pWw×tamp=1542872055207
4) 如果提交内容是JSON格式,可以将签名参数放到JSON中:
{
"data": "6KGo5Y2V5oiWVVJM5p+l6K+i5Y+C5pWw",
"timestamp": 1542872055207,
"sign": "6KGo5Y2V5oiWVVJM5p+l6K+i5Y+C5pWw"
}
* 签名规则:
1)请求参数,加上appKey进行a-z排序
2)排序后的参数拼起来,例如:appId=8327357471608325&**appKey=44f3ff1e3b887b48&data=+iTkCHmvT/8wHbhQ3+ZeYVCHySx6BwIu/5m86rhRoZc=×tamp=1497957842
3)对2.中的串,进行HMAC-SHA1加密
4)再Base64加密
5)最后得到的签名,放到Header头(X-Sign)
6) 最后将得到的签名值,放到 Header 头里
7) 如果提交内容是JSON格式,在生成签名内容时,子对象要用大括号`{}`括起来,数组用逗号`,`分隔,比如:
提交内容是:
{
"code": 0,
"data": {
"access_token": "glqrpmoYp1YsK9FMbkV",
"app_id": 28378403702864386,
"expires_in": 1440,
"refresh_token": "nzyfdM8UJrpsXk2QtMx",
"scope": [
"user",
"photo"
]
},
"msg": "成功"
}
签名的内容是:
code=0&data={access_token=glqrpmoYp1YsK9FMbkV&app_id=28378403702864386&expires_in=1440&refresh_token=nzyfdM8UJrpsXk2QtMx&scope=photo,user}&msg=成功×tamp=1542872055207
8) 如果同时有提交内容和URL查询参数时,在计算签名时,要将两边的内容都计算在内。
9) 最后要注意:如果需要对提交的数据加密,请加密后,再签名。
8、所有返回的内容都要签,签名规则如上,客户端可以按上面的规则验证签名,签名放到Header头里返回。
10、成功时返回的数据格式:
{
"code": 0,
"data": {
"list": [
{
"company": {
"codeName": "01043",
"companyName": "宜兴华胜汽车服务有限公司",
"disabled": true,
"id": "COM20120312000002",
"shortName": "无锡宜兴店",
},
"companyId": "COM20120312000002",
"deptName": "维修部",
"dutyName": "钣金组长",
"disabled": true,
"id": "MEM20141204000006",
"loginId": "",
"userName": "顾方清"
},
{
"company": {
"codeName": "01006",
"companyName": "苏州华策汽车维修服务有限公司",
"disabled": true,
"id": "COM20100211000007",
"shortName": "苏州吴中店",
},
"companyId": "COM20100211000007",
"deptName": "维修部",
"dutyName": "喷漆组长",
"disabled": true,
"id": "MEM20141204000021",
"loginId": "",
"userName": "张庆飞"
}
],
"page": 300,
"pageSize": 5,
"pages": 400,
"size": 5,
"total": 2000
},
"msg": "成功"
}
其中:code、msg 是公共参数,每次返回都会有
11、失败时返回的数据格式:
{
"code": 10001,
"msg": "参数无效",
"data": [
{
"fieldName": "status",
"message": "值是无效的"
}
]
}
三、客户端需要处理的顺序
=================
1. 要提交的JSON对象
var jsonobj = {
"name": "sky",
"id": 1233
}
2. 将JSON对象转成字符串
var jsonstr = JSON.toString(jsonobj);
3. 如果要加密,则调用AES的加密函数,如果不要加密,则跳到 setp5.2
var encryptstr = AES.encrypt(jsonstr);
4. 生成新的要提交的对象,
var jsonobj_new = {
"encrypted_data": encryptstr
}
5. 获取签名内容,签名内容要加上签名的时间戳,并按key进行排序。
var timestamp = 123456789
5.1 如果内容加密:
var signobj = {
"encrypted_data": encryptstr,
"timestamp": timestamp
}
var signstr = GET_SIGN_CONTENT(signobj); // ==> encrypted_data=encryptstr×tamp=123456789
5.2 如果内容不加密:
var signobj = {
"name": "sky",
"id": 1233,
"timestamp": timestamp
}
var signstr = GET_SIGN_CONTENT(signobj); // ==> name=sky&id=1233×tamp=123456789
6. 生成签名
var sign = DO_SIGN(signstr);
7. 最终要提交的JSON对象
7.1 如果内容加密:
var finalobj = {
"encrypted_data": encryptstr,
"timestamp": timestamp,
"sign": sign
}
7.2 如果内容不加密:
var finalobj = {
"name": "sky",
"id": 1233,
"timestamp": timestamp,
"sign": sign
}