跳转至

全局说明

全局说明

所有未特殊标明的接口均遵守此全局规范

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小时内定时重复请求。

加解密说明

加密:

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时间戳(秒), 有度demo中有checkToken()示例

返回

{
   "errcode": 0,
   "errmsg": "ok",
   "encrypt": "$encrypt_accessToken"
}
参数 必须 说明
errcode 全局返回码
errmsg 结果说明
encrypt 加密后的新accessToken,成功时返回

encrypt解密后数据结构:

{
   "accessToken": "$accessToken",
   "expireIn": 7200
}
参数 说明
accessToken 新的accessToken。每次换取都会生成新的
expireIn 7200秒(2小时)内有效