- 产品介绍
- 用户指南
-
最佳实践
- 概述
- SparkPack 企业ERP泛微OA集成指南
- SparkPack 企业ERP和钉钉集成
- SparkPack 企业ERP和黑湖MES集成
- SparkPack 企业ERP条码集成指南
- SparkPack 企业ERP企业微信集成指南
- SparkPack解决方案预集成培训
- 运维管理
- 常见问题
- 文档下载
- 通用参考
展开导读
链接复制成功！
审批事件
配置事件订阅
钉钉会向应用推送订阅的事件，例如部门变更、签到通知、打卡通知等。通过订阅这些事件，可以更好地与钉钉集成。你只需告诉钉钉当某个事件发生时，钉钉需要推送消息到哪个URL，钉钉会以HTTP POST请求的方式将事件内容以JSON格式推送给你。
事件订阅流程
事件订阅的流程如下图所示。
首先，开发者需要在钉钉开放平台配置HTTP请求接收地址用于接收推送的订阅事件，然后设置要订阅的事件。在配置完请求地址后，钉钉开放平台会向该地址发送POST请求，只有在规定时间内正确返回了包含"success"的加密字符串才完成事件订阅。
配置请求地址和事件订阅
- 登录开发者后台，找到已创建的企业内部应用。
- 单击事件订阅，然后单击编辑配置用于接收请求的HTTP地址。
注意
确保该地址公网可以访问。
编辑完请求地址，单击保存按钮时，开放平台会向你配置的网址推送一个 application/json 格式的 POST 请求, 用于验证你配置的网址的合法性。请求如下：
{
"encrypt": "ajls384kdjx98XX" // 加密字符串，解密方法请看下方的消息加解密
}
当你收到开放平台的POST验证请求时，你需要做解密处理，并在1500ms内返回包含success的加密字符串（JSON格式）。钉钉开放平台收到返回的JSON信息后会做解密处理，如果可以得到正常的success字符串，则验证回调信息推送正常，否则会判定为失败的回调信息。
- 成功配置请求地址后，在事件订阅列表区域，开启要订阅的事件。
接收并响应事件
- 接收事件信息
当事件发生时，钉钉会主动向配置的HTTP地址发送POST请求，推送对应的事件信息。例如订阅通讯录事件后，当通讯录发生变更时，会向注册的HTTP地址推送事件信息，其格式如下。
说明
钉钉服务器推送信息是即时推送，如果企业的回调地址没有在1500毫秒内返回正确的加密信息给钉钉服务器，钉钉服务器会判断为推送失败。
请求的URL格式如下：
http://你注册的HTTP地址?signature=111108bb8e6dbc2xxxx×tamp=1783610513&nonce=380320111
包含的JSON数据如下：
{
"encrypt":"1ojQf0NSvw2WPvW7LijxS8UvISr8pdDP+rXpPbcLGOmIBNbWetRg7IP0vdhVgkVwSoZBJeQwY2zhROsJq/HJ+q6tp1qhl9L1+ccC9ZjKs1wV5bmA9NoAWQiZ+7MpzQVq+j74rJQljdVyBdI/dGOvsnBSCxCVW0ISWX0vn9lYTuuHSoaxwCGylH9xRhYHL9bRDskBc7bO0FseHQQasdfghjkl"
}
其中：
- signature为消息体签名。
- timestamp为时间戳。
- nonce为随机字符串。
- encrypt为加密的推送事件信息。
- 响应事件信息
当你收到开放平台的POST验证请求时，你需要做解密处理，并在1500ms内返回包含success的加密字符串（JSON格式）。钉钉开放平台收到返回的JSON信息后会做解密处理，如果可以得到正常的success字符串，则验证回调信息推送正常，否则会判定为失败的回调信息。
具体返回给钉钉的数据格式如下：
注意
返回的数据格式必须是JSON格式。
{
"msg_signature":"111108bb8e6dbce3c9671d6fdb69d1506xxxx",
"timeStamp":"1783610513",
"nonce":"123456",
"encrypt":"1ojQf0NSvw2WPvW7LijxS8UvISr8pdDP+rXpPbcLGOmIxxxx"
}
其中：
- msg_signature为消息体签名。
- timeStamp为时间戳。
- nonce为随机字符串。
- encrypt为success加密字符串。
消息加解密
为了保证数据传输的安全，钉钉在推送订阅事件时，会携带配置的token用来验证事件来源。同时使用该密钥对消息内容做对称加密。
单击这里获取回调加解密类库和对应demo。
钉钉服务器会把msg消息体明文编码成encrypt。encrypt = Base64_Encode(AES_Encrypt[random(16B) + msg_len(4B) + msg + $key])是对明文消息msg加密处理后的Base64编码。其中：
- random为16字节的随机字符串。
- msg_len为4字节的msg长度，网络字节序。
- msg为消息体明文。
- key为应用的appKey。
取出返回的JSON中的encrypt字段：
- 对密文BASE64解码：aes_msg=Base64_Decode(encrypt)；
- 使用AESKey做AES解密：rand_msg=AES_Decrypt(aes_msg)；
审批事件类型
|
事件类型 |
说明 |
|---|---|
|
bpms_task_change |
审批任务开始、结束、转交。 注意 此事件仅针对当前审批人。 |
|
bpms_instance_change |
审批实例开始、结束。 注意 此事件为审批流实例。 |
审批实例开始
示例：
{
"EventType": "bpms_instance_change",
"processInstanceId": "ad253df6-e175caf-xxxxxxxxxxxx",
"corpId": "corpidxxxxxxxxxxxxx",
"createTime": 1495592259000,
"title": "自测-1016",
"type": "start",
"staffId": "er5875",
"url": "https://aflow.dingtalk.com/dingtalk/mobile/homepage.htm",
"processCode":"Pro-xxx"
}
参数说明：
|
参数 |
说明 |
|---|---|
|
EventType |
事件类型。 |
|
processInstanceId |
审批实例id。 |
|
corpId |
审批实例所在的企业corpId。 |
|
createTime |
创建审批实例时间。时间戳，单位毫秒。 |
|
title |
审批实例标题。 |
|
type |
类型，type为start表示审批实例开始。 |
|
staffId |
发起审批实例的员工userId。 |
|
url |
审批实例url，可在钉钉内跳转到审批页面。 |
|
processCode |
审批模板的唯一码。 |
审批实例结束|终止
示例：
{
"EventType": "bpms_instance_change",
"processInstanceId": "ad253df6-e175caf-xxxxxxxxxxxx",
"finishTime": 1495592305000,
"corpId": "dinge8a56572f80b02a8ffexxxx",
"title": "自测-1016",
"type": "finish",
"url": "https://aflow.dingtalk.com/dingtalk/mobile/homepage.htm?corpid=ding2c015874d817xxxx&dd_share=",
"result": "refuse",
"createTime": 1495592272000,
"staffId": "manager75",
"processCode":"Pro-xxx"
}
参数说明：
|
参数 |
说明 |
|---|---|
|
EventType |
事件类型。 |
|
processInstanceId |
审批实例id。 |
|
corpId |
审批实例对应的企业corpId。 |
|
createTime |
创建审批实例时间。时间戳，单位毫秒。 |
|
finishTime |
结束审批实例时间。时间戳，单位毫秒。 |
|
title |
实例标题。 |
|
type |
|
|
staffId |
发起审批实例的员工userId。 |
|
url |
审批实例url，可在钉钉内跳转到审批页面。 |
|
result |
正常结束时result为agree，拒绝时result为refuse，审批终止时没这个值。 |
|
processCode |
审批模板的唯一码。 |
审批任务开始
示例：
{
"EventType": "bpms_task_change",
"processInstanceId": "ce133dd0-5b22-9516-xxxxxxxxxxxx",
"corpId": "corpidxxxxxxxxxxxxx",
"createTime": 1495593189000,
"title": "自测-1016",
"type": "start",
"staffId": "manager75",
"processCode":"Pro-xxx"
}
参数说明：
|
参数 |
说明 |
|---|---|
|
EventType |
事件类型。 |
|
processInstanceId |
审批实例id。 |
|
corpId |
发生审批任务变更的企业corpId。 |
|
createTime |
创建任务的时间。时间戳，单位毫秒。 |
|
title |
实例标题。 |
|
type |
类型，type为start表示审批任务开始。 |
|
staffId |
当前任务的审批人userId。 |
|
processCode |
审批模板的唯一码。 |
审批任务结束
示例：
{
"EventType": "bpms_task_change",
"processInstanceId": "ce133dd0-5b22-9516-xxxxxxxxxxxx",
"finishTime": 1495605749000,
"corpId": "corpidxxxxxxxxxxxxx",
"title": "自测-1016",
"type": "finish",
"result": "refuse",
"remark": "拒绝理由",
"createTime": 1495593189000,
"staffId": "manager75",
"processCode":"Pro-xxx"
}
参数说明：
|
参数 |
说明 |
|---|---|
|
EventType |
事件类型。 |
|
processInstanceId |
审批实例id。 |
|
corpId |
发生审批任务变更的企业corpId。 |
|
createTime |
创建任务的时间。时间戳，单位毫秒。 |
|
finishTime |
结束任务的时间。时间戳，单位毫秒。 |
|
title |
实例标题。 |
|
type |
审批任务结束类型：
|
|
staffId |
当前任务审批人的userId。 |
|
result |
|
|
remark |
remark表示操作时写的评论内容。 |
|
processCode |
审批模板的唯一码。 |
审批任务转交
示例：
{
"EventType": "bpms_task_change",
"processInstanceId": "439bda1c-d9-9d67-xxxxxxxxxxxx",
"finishTime": 1495542282000,
"corpId": "corpidxxxxxxxxxxxxx",
"title": "自测-2017",
"type": "finish",
"result": "redirect",
"createTime": 1495541847000,
"staffId": "08058646137",
"processCode":"Pro-xxx"
}
参数说明：
|
参数 |
说明 |
|---|---|
|
EventType |
事件类型。 |
|
processInstanceId |
审批实例id。 |
|
corpId |
发生审批任务变更的企业corpId。 |
|
createTime |
当前任务创建的时间。时间戳，单位毫秒。 |
|
finishTime |
当前任务结束，即转交动作发生的时间戳，单位毫秒。 |
|
title |
实例标题。 |
|
type |
类型，type为finish表示审批任务转交。 |
|
staffId |
操作转交动作的员工userId。 |
|
result |
redirect：表示审批任务转交。 |
|
processCode |
审批模板的唯一码。 |
