企業微信審批流程調用

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 這個接口