接口调用

HTTP调用方式可以面向HTTP接口进行开发，ISV可以根据自己系统的情况，选择不同的实现语言来实现对接。

请求参数

公共请求头

除了HTTP协议中规定的头信息以外，本开放接口额外做以下头信息要求：

参数名称	参数类型	说明
Content-Type	String	请填写application/json;charset=UTF-8
access_token	String	大多数接口，需要通过验证身份以后才能访问，需要携带该头信息；请从OAuth接口获取的access_token
req_date	Long	当前时间戳的毫秒数。可以参考java的System.currentTimeMillis()方法生成;（如果未携带该头信息，或与服务端的时间差超过 15 分钟，则云端拒绝该请求）
req_sign	String	签名校验请求的合法性

公共返回报文

在所有请求的返回值里，有一些公共的字段：

参数名称	参数类型	说明
code	String	业务编码
success	Boolean	接口是否成功（是否发生业务异常）
reqId	String	由服务器端生成的唯一标识，对应每次请求。排查接口异常时，可提供该字段方便定位
message	String	业务异常信息
data	Oject	业务数据

返回结果

请求成功时返回结果示例：

{
	"reqId": "5b8d41f68b0d47a49dca4a4812857d49",
	"code": "2000",
	"success": true,
	"message": null,
	"data": {
		"access_token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJbLTEsLTEsLTEsMTAwLFwiXCIsMdIiwiZXhwIjoxNzQwNjIzMTUwLCJpYXQiOjE3MzkzMjcxNTB9.1z55Yzm37AKuQcWlbjg1IaEw9BECCsFp9s6g_or9wyLa5RNmdlA2Kfu_GtRuWuVvkk6ArPjVFtBrcNw",
		"code": null,
		"error_msg": null,
		"expires_in": 7200,
		"orgId": null,
		"refresh_token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJbLTEsLTEsLTEsMTsbCxcIlwiLC0xLG51bGxdIiwiZXhwIjoxNzQxOTE5MTUwLCJpYXQiOjE3MzkzMjcxNTB9.kOW2Cu5O5th58NUJDlDnhu3ircfG45e2vCjUs0QAPlydHQcd6pZRAu9jgg1MmSbioHUs7f4hBsPEw",
		"result": true,
		"token_parameter": null,
		"token_type": null,
		"userId": null
	}
}

请求异常时返回示例：

{
    "reqId": "8146864387cd4847801616abd9e2f16a",
    "code": "2000",
    "success": true,
    "message": null,
    "data": {
        "error_msg": "应用的密钥无效!",
    }
}

签名规则

每个请求头都需要添加req_sign字段，来验证请求的合法性，填写方法如下:

1、req_sign头信息填写的内容如下：

req_sign: API-SV1:<AppKey>:<Signature>

其中：

API-SV1：表示签名算法版本，暂时固定API-SV1

AppKey：为分配给接入方的AppKey

Signature：为签名值，计算方法见下面描述

2、签名值的计算方法:

第一步，拼装待签名字符串

待签名字符串 = HTTPMethod + "_" + Content-Md5 + "_" + req_date + "_" + access_token + "_" + AppSecret

其中：

HTTPMethod：为请求的方法，通常为POST

Content-Md5：为请求Body内容的md5

req_date：为请求头信息中的req_date

access_token：为AppKey和AppSecret登录后获取

AppSecret：为分配给接入方的密钥

注意：
签名字符串必须为UTF-8格式，含有中文字符的签名串必须先进行UTF-8编码
本文档中 md5 相关的结果都转为小写处理

第二步，计算签名

签名值 = Base64(MD5(待签名字符串)))

签名示例

签名示例	执行结果	示例描述
请求body： {"nsrsbh":"915211111111111111"}	请求body Md5结果： Content-Md5=4e7f9b81e299ad014cfbc6949c3f4e04	请注意空格换行等空白字符，如果POST请求body内容包含空格换行等空白字符，请签名用的字符串也包含，保持和POST请求body一致，最简单的做法是请求body和计算签名都去掉空白字符串
待签名字符串： signStr=HTTPMethod_Content-Md5_req_date_accessToken_appSecret =POST_4e7f9b81e299ad014cfbc6949c3f4e04_xxx_yyy_zzz	签名前：POST_4e7f9b81e299ad014cfbc6949c3f4e04_1581588537349_eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJbLTEsLTEsLTEsMTAwLFwiXCIsMTAwMDEwMDEsbnVsbCxcIlwiLC0xXSIsImV4cCI6MTU4Mjg4Mjg0NSwiaWF0IjoxNTgxNTg2ODQ1fQ.T4GTFFzf6xD2n1rrCFVu88dQA8ipEobX2_i-Ub7qvIkxrTScmUm_113r1VEsTGhysA-jLFVwFWOtRqEaWvIvVA_9r27FCIHtmIAUBoNjA5Z5hq2vTCEfAL82YzrnV4vdlhpXAp2 签名 md5后： a41cc679d3c2303933d0acb002c18b14 继续base64之后最终签名值： freq_signMD5=YTQxY2M2NzlkM2MyMzAzOTMzZDBhY2IwMDJjMThiMTQ=	1、xxx请替换成实际的时间戳，类似1581588537349的格式 2、yyy请替换成实际取到的accessToken, 类似 eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJbLTEsLTEsLTEsMTAwLFwiXCIsMTAwMDEwMDEsbnVsbCxcIlwiLC0xXSIsImV4cCI6MTU4Mjg4Mjg0NSwiaWF0IjoxNTgxNTg2ODQ1fQ.T4GTFFzf6xD2n1rrCFVu88dQA8ipEobX2_i-Ub7qvIkxrTScmUm_113r1VEsTGhysA-jLFVwFWOtRqEaWvIvVA 3、zzz请替换成实际的appSecret，类似 9r27FCIHtmIAUBoNjA5Z5hq2vTCEfAL82YzrnV4vdlhpXAp2
req_sign=API-SV1:appKey :freq_signMD5	最终请求header，req_sign的值： API-SV1:1000xxxx:YTQxY2M2NzlkM2MyMzAzOTMzZDBhY2IwMDJjMThiMTQ=	1000xxxx请替换为实际的appkey

上述举例的数据是为了验证签名算法，请先按照举例的数据验证 md5 和 base64 算法，看看生成的签名值是否正确，实际请求请按照实际数据签名。

Java调用示例

jdk8/jdk8+

📌

注意：！！！这里获取到的access_token需要缓存到本地缓存中再使用，频繁请求login接口会被限制。

Python调用示例

📌

注意：！！！这里获取到的access_token需要缓存到本地缓存中再使用，频繁请求login接口会被限制。

Php调用示例

📌

注意：！！！这里获取到的access_token需要缓存到本地缓存中再使用，频繁请求login接口会被限制。

Go调用示例

📌

注意：！！！这里获取到的access_token需要缓存到本地缓存中再使用，频繁请求login接口会被限制。

API鉴权调用常见问题

1、login接口的client_secret需要MD5(appSecret)后32位小写，req_sign签名中的直接使用appSecret。
2、header中的req_date和req_sign签名中的req_date需要相同。
3、确认MD5函数的结果是否正确，校验使用https://www.sojson.com/encrypt_md5.html
4、body中请求参数和req_sign签名中的请求参数要一致，使用字符串，尽量不要有空格和回车。
5、login请求参数：

{
"grant_type":"client_credentials",
"client_appkey":"appkey",
"client_secret":"md5(appsecret)32位小写"
}

6、业务接口请求头中四个参数如下：

header: {
'content-type': 'application/json', 
'access_token': access_token,
'req_date': req_date,
'req_sign': req_sign
}

请求参数#

签名规则#

签名示例#

Java调用示例#

Python调用示例#

Php调用示例#

Go调用示例#

API鉴权调用常见问题#

请求参数

签名规则

签名示例

Java调用示例

Python调用示例

Php调用示例

Go调用示例

API鉴权调用常见问题