全局说明(必读)
全局说明
所有未特殊标明的接口均遵守此全局规范
1、 接口均使用http协议;
2、 均采用Json数据格式。主动调用、结果返回、消息回调均有标准Json格式
3、 每次主动调用均需要带上accessToken参数,accessToken参数由buin和appId换取;
4、 POST请求的数据均需要加密。加密方式详见加解密说明。
5、 sdk及demo示例:https://github.com/youduim
主动调用
GET请求不必使用此请求格式,但遵守结果返回格式
请求格式
{
"buin": $buin,
"appId": "$appId",
"encrypt": "$msg_encrypt"
}
参数 | 必须 | 说明 |
---|---|---|
buin | 是 | 企业总机号 |
appId | 是 | 企业应用的ID |
encrypt | 否 | 加密后的消息,接口对应的json数据 |
结果返回格式
{
"errcode": 0,
"errmsg": "ok",
"encrypt": "$encrypt_msg"
}
参数 | 必须 | 说明 |
---|---|---|
errcode | 是 | 全局返回码 |
errmsg | 是 | 结果说明 |
encrypt | 否 | 加密后的消息体,需要时返回 |
errcode和errmsg为全局状态码,部分响应无业务数据时只包含该信息。
消息回调
内容格式
{
"toBuin": $buin,
"toApp": "$app_id",
"encrypt": "encrypt_msg"
}
参数 | 必须 | 说明 |
---|---|---|
toBuin | 是 | 企业号 |
toApp | 是 | 应用ID |
encrypt | 否 | 响应结果Json加密后的消息体 |
消息回调应答格式
{
"errcode": 0,
"errmsg": "ok",
"encrypt": "$encrypt_msg"
}
参数 | 必须 | 说明 |
---|---|---|
errcode | 是 | 全局返回码 |
errmsg | 是 | 结果说明 |
encrypt | 否 | 加密后的消息体,需要时返回。 |
如果没有收到响应结果,有度服务将在24小时内定时重复请求。
加解密说明
有度提供了Java、PHP、Python、C#、Golang语言的SDK,要查看各个平台的加解密代码请通过有度SDK下载访问有度在github上的代码仓库,加解密代码请从SDK源码中查找
有度即时通SDK通讯加密方式采用AES/CBC/PKCS5Padding
在数据请求以及数据返回时均需要使用到加解密
加密:
encryptMsg=Base64Encode(AESEncrypt[random(16B)+msgLen(4B)+msg+$AppID])
AES加密的buff由4部分组成:
1、 16个字节的随机字符串
2、 4个字节的msg长度
3、明文msg
4、$AppID。
其中msg_len为msg的字节数,网络字节序;$AppID为企业应用的AppID。
AES采用CBC模式,数据采用PKCS#7填充至32字节的倍数;IV初始向量大小为16字节。
经AESKey加密后,再进行Base64编码,即获得密文encryptMsg。
请求内容、回调应答中的业务数据(若需要)都需要经过加密放到encrypt,各接口中的数据格式对应到这里。
解密:
1、对密文BASE64解码:aesMsg=Base64Decode(encryptMsg)
2、使用企业应用回调设置中的EncodingAESKey做AES解密:randMsg=AESDecrypt(aesMsg)
3、验证解密后$AppID、msgLen
4、去掉randMsg头部的16个随机字节,4个字节的msg_len,和尾部的AppID即为最终的消息体原文msg
响应内容、回调内容中的业务数据(若存在)都经过加密存放到encrypt字段,各接口中的数据格式对应到这里。
消息体签名:
为了方便开发者验证回调的合法性,在回调url中增加了消息签名,以参数msg_signature标识,开发者可以先验证此参数的正确性后再解密。
验证步骤:
1.计算签名:dev_msg_signature=sha1(sort(token、timestamp、nonce、msg_encrypt))。sort是将参数按照字母字典排序,然后从小到大拼接成一个字符串
2.比较dev_msg_signature和msg_signature是否相等,相等则表示验证通过
参数 | 说明 |
---|---|
token | 后台管理器中设置应用回调时生成的token |
timestamp | 时间戳。有度服务回调参数中返回 |
nonce | 随机字符串。有度服务回调参数中返回 |
msg_encrypt | 加密的消息体。即回调json数据包中的encrypt节点值 |
获取accessToken
正常情况下accessToken有效期为7200秒(2个小时),有效期内重复获取均会返回不同的结果。
POST请求URL:http://[SERVER:7080]/cgi/gettoken
[SERVER:7080]指连接的服务器地址以及端口,默认为7080
{
"buin": $buin,
"appId": "$appId",
"encrypt": "msg_encrypt"
}
参数 | 必须 | 说明 |
---|---|---|
buin | 是 | 企业总机号 |
appId | 是 | 企业应用的ID |
encrypt | 是 | 加密后的消息体,加密内容为当前UNIX时间戳(秒) |
对加解密有疑问?加解密说明能提供帮助
返回
{
"errcode": 0,
"errmsg": "ok",
"encrypt": "$encrypt_accessToken"
}
参数 | 必须 | 说明 |
---|---|---|
errcode | 是 | 全局返回码 |
errmsg | 是 | 结果说明 |
encrypt | 否 | 加密后的新accessToken,成功时返回 |
encrypt解密后数据结构:
{
"accessToken": "$accessToken",
"expireIn": 7200
}
参数 | 说明 |
---|---|
accessToken | 新的accessToken。每次换取都会生成新的 |
expireIn | 7200秒(2小时)内有效 |