腾讯乐享接口文档

# 接入指南

# 第一步：填写服务器配置

企业管理员可以在管理后台配置用于接收腾讯乐享回调请求的服务器URL。配置成功后，企业将得到一个 secret 用于服务器接收请求时验证消息来源合法性。

# 第二步：验证消息是否来自腾讯乐享

腾讯乐享回调请求的数据格式为 JSON 结构，如文档新增评论的回调请求数据如下：

{
    "nonce":"3072f432-bfc5-4e79-a24d-8fe4741da471",
    "timestamp":1540368608,
    "sign":"7b3d8492887e6c79b16cab7f093102d6dae5de5b",
    "action":"doc/comment/add",
    "attributes":{
        "doc_id":"b252f800d76311e89ca37589846814b7",
        "comment_id":"39080d18d76411e897a87ba398858639",
        "content":"乐享内文档评论的内容"
    },
    "operator":"StaffID",
	"operator_info":{"name":"StaffID"}
}

每个回调请求都会带上 nonce, timestamp, sign 三个参数用于验证消息来源是否合法。结合第一步得到的 secret，可使用以下方法验证：

判断 sign == sha1(nonce . secret . timestamp)，若返回 true 则消息来源合法。

重放攻击：部分系统内部由于安全扫描等原因重放乐享的回调请求，可能会导致回调被重复处理，如重复写入数据、重复推送消息等。

处理方案：建议验证完签名(sign)后，再判断timstamp是否在当前系统时间的3~5秒内（可根据网络延迟适当调整），并对nonce记录到缓存中，设置过期时间跟前面判断的timestmp有效时间一致。若缓存中存在nonce，则代表该请求已接收处理过，不再处理。

# 第三步：结合业务参数和文档处理请求

回调请求的业务参数包括：action、 attributes、 operator，部分业务回调会包含 is_anonymous

# 参数说明：

参数 说明
action 员工在腾讯乐享平台上触发的事件类型
并非所有事件都会回调，以目前文档提供的为准
attributes 用户触发的事件具体的内容和属性
operator 触发者StaffID，是否明文展示取决于is_anonymous
is_anonymous 用户是否匿名操作

← 文档 →