全局说明

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

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小时）内有效