企业微信审批流程调用

1、    审批

1.1审批介绍

概述

目前，企业微信审批应用对企业内部提供了以下接口和能力：

• 获取审批模板详情
• 提交审批申请
• 审批申请状态变化回调通知
• 批量获取审批编号
• 获取审批申请详情

场景描述

企业可通过审批应用或自建应用secret换取access_token，用于企业微信审批应用相关接口调用。

首先，可通过“获取审批模板详情”接口，了解模板内的控件构成及控件id。
然后，可通过“提交审批申请”，利用模板id和控件id，代员工发起和填写审批申请，自定义审批流程。
审批前后，可通过“审批申请状态变化回调通知”，订阅审批单据流转的变化，进行各项拓展动作。
此外，还可通过“批量获取审批编号”、“获取审批申请详情”接口，随时获取审批申请的内容详情和流程状态。

 

 

 

和“审批流程引擎”的区别

企业微信审批应用相关接口，是围绕“审批应用”的开放，数据的写入、读取对象都为企业微信“审批应用”。

“审批流程引擎”相关接口，是在“自建应用”或“第三方应用”中增加流程相关功能，使用和作用对象都为“自建应用”或“第三方应用”，不会影响企业微信“审批应用”。

 

https://work.weixin.qq.com/api/doc/90000/90135/90269

自建应用中的审核只能由js发起，发起审批需要调用发起审批jssdk

1.2使用工具调试api

我们已经创建好一个自建应用，且拿到了可用的应用id及secret，如何调用api控制这个应用呢？下面以发消息为例说明如何调试api接口。

调用api的过程，本质上就是发送http请求给企业微信后台，在正式开发前，我们可以使用工具模拟http请求调试api。这里以 postman 为例（下载地址，使用方法略），当然你也可以使用其它http模拟工具。

发消息api见发送应用消息，可以看到其实就是一个post请求

请求方式：POST（HTTPS）
请求地址： https://qyapi.weixin.qq.com/cgi-bin/message/send?access_token=ACCESS_TOKEN

post 参数为 access_token 和 消息体。

1. 获取access_token

参考开始开发，access_token是应用调用api的凭证，由 corpid和corpsecret换取。

corpid就是企业ID

 

corpsecret 应用的secret

 

请求方式：GET（HTTPS）
请求URL：https://qyapi.weixin.qq.com/cgi-bin/gettoken?corpid=ID&corpsecret=SECRET

使用postman发送这样一个GET请求即可得到access_token（请把截图中的corpid、corpsecret换为自己的corpid、应用secret）

 

1. 构造消息体

参考发送应用消息，可以发送文本、图片、视频等多种类型的应用消息，这里以最简单的文本消息为例：（注意修改touser、agentid为自己想要的接收者userid列表、应用id）

            i.     {

           ii.        "touser" : "abelzhu|ZhuShengben",

          iii.        "msgtype" : "text",

           iv.        "agentid" : 1000002,

            v.        "text" : {

           vi.            "content" : "我就试一下"

          vii.        },

        viii.        "safe":0

           ix.     }

1. 发送消息

如下图示，以上面两步得到的access_token和消息体为参数，在postman中发送post请求即可（红色箭头所指为需要注意的点）

 

如果发送成功，在接收者的企业微信中的相应应用里，会收到一条文本消息。

 

实际上，企业微信提供了一套更方便的模拟工具，见开发者工具的“接口调试工具”。

debug模式调用接口

在开发过程中，可能由于你调用的参数有问题，我们的接口会返回errcode, 此时你可以在“全局错误码说明”查阅相应的错误原因。有时候可能根据错误码说明你仍然不知道自己的参数在哪里出错，这时候你可以在接口请求url里加上debug=1参数（暂未支持微盘相关接口），之后从接口返回的errmsg复制出hint值，再用以下工具进行查询，我们会返回你请求的完整参数（包括header与body）。

请求示例：https://qyapi.weixin.qq.com/cgi-bin/message/send?access_token=ACCESS_TOKEN&debug=1

查询页面：https://open.work.weixin.qq.com/devtool/query

注意: debug模式有使用频率限制，同一个api每分钟不能超过5次，所以在完成调试之后，请记得要去掉debug=1参数。

使用php版本demo开始开发

为体验以代码的方式调用api的乐趣，下面以php开发语言为例，开发者需有一定的php基础。

从github下载示例代码。可以看到代码结构为：

├── api // API 接口
│ ├── datastructure // API接口需要使用到的一些数据结构
│ ├── examples // API接口的测试用例
│ ├── README.md
│ └── src // API接口的关键逻辑
├── callback // 消息回调的一些方法
├── config.php // 基础配置
├── README.md
└── utils // 一些基础方法

在 api/example/ 路径下，有个 config.php 文件，用于配置自己的企业id、应用id等信息。

如下图所示，修改 CORP_ID、APP_ID、APP_SECRET 为自己的企业信息。

 

在 api/example/ 路径下，有个发送消息的示例 MessageTest.php ，如下图所示，修改 touser（发送给的成员id列表）、toparty（发送给的部门id列表）、totag（发送给的标签id列表）等参数为自己的企业的信息。

 

执行 MessageTest.php 即完成消息发送（调试期间建议在根目录的 config.php 文件里，配置DEBUG参数为true，如果有失败，会打印错误信息）。如果发送成功，接收者的应用里会收到一条消息。

 

使用应用菜单

要实现这样的简单功能：用户点击应用菜单后，展现一个静态网页，告知企业后台系统的内存使用情况。

需要使用Apache搭建企业后台服务，请自行配置好php和Apache环境。

部署应用后台

我们需要在自己的服务器维护一个页面。以常用的 Apache + php 为例，搭建一个简单的企业后台。
在 Apache 的 website 目录下，创建一个页面 getmemoryusage.php，该文件内容如下：

1. <?php
2. echo "system memory usage " . memory_get_usage() . "B\n";
3. ?>

页面非常简单，通过系统函数获取内存使用情况，并打印出来。
这个页面的地址为 http://ip:port/getmemoryusage.php （如何得到ip、port，请参考Apache文献，此处不详述）
如果有正确配置 Apache 服务，在当前浏览器里输入 http://ip:port/getmemoryusage.php ，可以看到页面。
如何让这个页面在企业微信应用中展现呢？

配置应用菜单

在管理端进入上面创建好的自建应用，点击“自定义菜单”项，菜单名自取，菜单内容选“跳转到网页”，URL填上 http://ip:port/getmemoryusage.php ，保存并发布，即完成了添加应用菜单的过程。

应用菜单发布后，从企业微信终端进入该应用，可以看到菜单已经更新。点击菜单即可看到企业后台系统的内存使用情况了！
注意，上面的URL在真实使用时必须外网可访问。如果只是用于测试，外网不可访问，那么测试的终端必须与页面所在服务器在同一个网段，或者使用内网穿透工具（如花生壳）。

1.3获取审批模板详情

调试工具

企业可通过审批应用或自建应用Secret调用本接口，获取企业微信“审批应用”内指定审批模板的详情。

请求方式：POST（HTTPS）
请求地址：https://qyapi.weixin.qq.com/cgi-bin/oa/gettemplatedetail?access_token=ACCESS_TOKEN

请求示例：

1. {
2.    "template_id" : "ZLqk8pcsAoXZ1eYa6vpAgfX28MPdYU3ayMaSPHaaa"
3. }

较早时间创建的模板，id为类似“1910324946027731_1688852032423522_1808577376_15111111111”的数字串。

参数说明：

参数	必须	说明
access_token	是	调用接口凭证。必须使用审批应用或企业内自建应用的 secret获取， 获取方式参考：文档-获取access_token
template_id	是	模板的唯一标识id。可在“获取审批单据详情”、 “审批状态变化回调通知”中获得， 也可在审批模板的模板编辑页面浏览器Url链接中获得。

 

template_id查看位置

 

 

1.审批应用的Secret可获取企业自建模板及第三方服务商添加的模板详情；自建应用的Secret可获取企业自建模板的模板详情。
2.接口调用频率限制为600次/分钟。

---

返回结果 ：

1. {
2.     "errcode": 0,
3.     "errmsg": "ok",
4.     "template_names": [
5.         {
6.             "text": "全字段",
7.             "lang": "zh_CN"
8.         }
9.     ],
10. 10.     "template_content": {
11. 11.         "controls": [
12. 12.             {
13. 13.                 "property": {
14. 14.                     "control": "Selector",
15. 15.                     "id": "Selector-15111111111",
16. 16.                     "title": [
17. 17.                         {
18. 18.                             "text": "单选控件",
19. 19.                             "lang": "zh_CN"
20. 20.                         }
21. 21.                     ],
22. 22.                     "placeholder": [
23. 23.                         {
24. 24.                             "text": "这是单选控件的说明",
25. 25.                             "lang": "zh_CN"
26. 26.                         }
27. 27.                     ],
28. 28.                     "require": 0,
29. 29.                     "un_print": 0
30. 30.                 },
31. 31.                 "config": {
32. 32.                     "selector": {
33. 33.                         "type": "single",
34. 34.                         "exp_type": 0,
35. 35.                         "options": [
36. 36.                             {
37. 37.                                 "key": "option-15111111111",
38. 38.                                 "value": [
39. 39.                                     {
40. 40.                                         "text": "选项1",
41. 41.                                         "lang": "zh_CN"
42. 42.                                     }
43. 43.                                 ]
44. 44.                             },
45. 45.                             {
46. 46.                                 "key": "option-15222222222",
47. 47.                                 "value": [
48. 48.                                     {
49. 49.                                         "text": "选项2",
50. 50.                                         "lang": "zh_CN"
51. 51.                                     }
52. 52.                                 ]
53. 53.                             }
54. 54.                         ]
55. 55.                     }
56. 56.                 }
57. 57.             }
58. 58.         ]
59. 59.     }

60. }

参数说明：

参数	说明
template_names	模板名称，若配置了多语言则会包含中英文的模板名称，默认为zh_CN中文
template_content	模板控件信息
└ controls	模板控件数组。模板详情由多个不同类型的控件组成，控件类型详细说明见附录。
└ └ property	模板控件属性，包含了模板内控件的各种属性信息
└ └ └ control	控件类型：Text-文本；Textarea-多行文本；Number-数字；Money-金额；Date-日期/日期+时间；Selector-单选/多选；Contact-成员/部门；Tips-说明文字；File-附件；Table-明细；Attendance-假勤控件；Vacation-请假控件；Location-位置；RelatedApproval-关联审批单；Formula-公式；DateRange-时长
└ └ └ id	控件id
└ └ └ title	控件名称，若配置了多语言则会包含中英文的控件名称，默认为zh_CN中文
└ └ └ placeholder	控件说明，向申请者展示的控件填写说明，若配置了多语言则会包含中英文的控件说明，默认为zh_CN中文
└ └ └ require	是否必填：1-必填；0-非必填
└ └ └ un_print	是否参与打印：1-不参与打印；0-参与打印
└ └ config	模板控件配置，包含了部分控件类型的附加类型、属性，详见附录说明。目前有配置信息的控件类型有：Date-日期/日期+时间；Selector-单选/多选；Contact-成员/部门；Table-明细；Attendance-假勤组件（请假、外出、出差、加班）

---

附录

附1：Date控件（日期/日期+时间控件）config说明：

1. {
2.     "date": {
3.         "type": "day"
4.     }
5. }

参数	说明
date	类型标志，日期/日期+时间控件的config中会包含此参数
└ type	时间展示类型：day-日期；hour-日期+时间

附2：Selector控件（单选/多选控件）config说明：

1. {
2.     "selector": {
3.         "type": "single",
4.         "options": [
5.             {
6.                 "key": "option-15111111111",
7.                 "value": [
8.                     {
9.                         "text": "选项1",
10. 10.                         "lang": "zh_CN"
11. 11.                     }
12. 12.                 ]
13. 13.             },
14. 14.             {
15. 15.                 "key": "option-15222222222",
16. 16.                 "value": [
17. 17.                     {
18. 18.                         "text": "选项2",
19. 19.                         "lang": "zh_CN"
20. 20.                     }
21. 21.                 ]
22. 22.             }
23. 23.         ]
24. 24.     }

25. }

参数	说明
selector	类型标志，单选/多选控件的config中会包含此参数
└ type	选择类型：single-单选；multi-多选
└ options	选项，包含单选/多选控件中的所有选项，可能有多个
└ └ key	选项key，选项的唯一id，可用于发起审批申请，为单选/多选控件赋值
└ └ value	选项值，若配置了多语言则会包含中英文的选项值，默认为zh_CN中文

附3：Contact控件（成员/部门控件）config说明：

1. {
2.     "contact": {
3.         "type": "multi",
4.         "mode": "department"
5.     }
6. }

参数	说明
contact	类型标志，单选/多选控件的config中会包含此参数
└ type	选择方式：single-单选；multi-多选
└ mode	选择对象：user-成员；department-部门

附4：Table（明细控件）config说明：

1. {
2.     "table": {
3.         "children": [
4.             {
5.                 "property": {
6.                     "control": "Text",
7.                     "id": "Text-15111111111",
8.                     "title": [
9.                         {
10. 10.                             "text": "明细内文本控件",
11. 11.                             "lang": "zh_CN"
12. 12.                         }
13. 13.                     ],
14. 14.                     "placeholder": [
15. 15.                         {
16. 16.                             "text": "这是明细内文本控件的说明",
17. 17.                             "lang": "zh_CN"
18. 18.                         }
19. 19.                     ],
20. 20.                     "require": 0,
21. 21.                     "un_print": 0
22. 22.                 }
23. 23.             }
24. 24.         ],
25. 25.         "stat_field": []
26. 26.     }

27. }

参数	说明
table	类型标志，明细控件的config中会包含此参数
└ children	明细内的子控件，内部结构同controls

附5：Attendance控件（假勤控件）config说明：
说明:【出差】【加班】【外出】模板特有的控件

1. {
2.     "attendance": {
3.         "date_range": {
4.             "type": "hour"
5.         },
6.         "type": 3
7.     }
8. }

参数	说明
attendance	类型标志，假勤控件的config中会包含此参数
└ date_range	假期控件属性
└└ type	时间刻度：hour-精确到分钟, halfday—上午/下午
└ type	假勤控件类型：1-请假，3-出差，4-外出，5-加班

附6：Vacation控件（假勤控件）说明：
说明:【请假】模板特有控件, 请假类型强关联审批应用中的假期管理。

1. {
2.     "vacation_list": {
3.         "item": [{
4.             "id": 1,
5.             "name": [{
6.                 "text": "年假",
7.                 "lang": "zh_CN"
8.             }]
9.         }, {
10. 10.             "id": 2,
11. 11.             "name": [{
12. 12.                 "text": "事假",
13. 13.                 "lang": "zh_CN"
14. 14.             }]
15. 15.         }
16. 16.         ...//省略
17. 17.         ]
18. 18.     }

19. }

参数	说明
vacation_list	假期类型数组
└ item	单个假期类型属性
└└ id	假期类型标识id
└└ name	假期类型名称，默认zh_CN中文名称

---

错误说明

错误码	说明
301025	参数错误，请求template_id非法
301026	通用错误码，拉取审批模板内部接口失败

 

1.2基础应用审批

基础审批应用，可以调用https://qyapi.weixin.qq.com/cgi-bin/oa/applyevent 这个接口