介紹
工作臺開放平臺用於將企業業務系統接入工作臺。應用可以透過網頁入口為員工提供業務功能，也可以透過服務端 API 讀取授權範圍內的組織資料、發送機器人訊息，以及接收組織變更事件。
平臺概述
工作臺開放平臺將企業應用入口、身份、組織資料和訊息能力統一到一套開發者介面中。開發者只需關注應用設定、頁面接入、服務端呼叫和業務安全，不需要了解平臺內部實作。
平臺角色
| 角色 | 主要職責 |
|---|---|
| 企業管理員 | 管理應用、可見範圍、權限、機器人和發布狀態 |
| 應用負責人 | 維護應用設定、入口地址和版本發布 |
| 應用前端 | 渲染頁面、判斷執行環境、申請一次性授權碼 |
| 應用後端 | 保管密鑰、換取令牌和使用者身份、呼叫服務端 API |
| 企業員工 | 在工作臺開啟應用並使用業務功能 |
應用形態
- 網頁應用：設定桌面端和行動端入口，在工作臺中開啟業務頁面。
- 應用機器人：以應用身份向成員發送單聊訊息，適合提醒、通知和待辦觸達。
- 群聊機器人：繫結指定群聊，透過 Webhook 向群內發送訊息。
- 事件接收端：接收組織資料變更回呼，並在應用側完成驗簽、解密和冪等處理。
能力組成
| 能力 | 典型使用方式 | 主要文件 |
|---|---|---|
| 工作臺應用 | 建立應用、設定入口、設定可見範圍並發布 | 本頁應用建立與發布 |
| 端內免登 | 頁面透過 SDK 取得一次性 code，服務端換取當前使用者身份 | 客戶端 SDK、免登流程 |
| 應用級 API | 服務端使用 access_token 呼叫通訊錄、企業資訊和機器人介面 | 本頁 API 總覽、服務端 API |
| 事件訂閱 | 平臺向應用回呼組織資料變更 | 事件訂閱 |
API 總覽
服務端 API 統一使用 https://{gateway_host} 作為入口。除 OAuth 介面外，大多數介面返回統一外殼：{ "code": 200, "msg": "", "data": {} }。
| 分類 | 介面或能力 | 鑑權方式 | 說明 |
|---|---|---|---|
| 鑑權 | /auth/v1/oauth/token | appId + appSecret | 取得應用級 access_token |
| 免登 | SDK 取得 code、/auth/v1/oauth/userinfo | 客戶端登入態 + 應用令牌 | 取得當前使用者身份 |
| 通訊錄 | /open/v1/contact/* | access_token | 查詢部門和成員 |
| 企業資訊 | /open/v1/enterprise/info | access_token | 查詢企業名稱和 Logo |
| 應用機器人 | /open/v1/robot/messages | access_token | 單聊或批量發送機器人訊息 |
| 群聊機器人 | /webhook/robot/send | Webhook 令牌 + 簽名 | 向指定群聊發送訊息 |
| 事件訂閱 | 應用設定的 HTTPS 回呼地址 | 平臺簽名與加密 | 接收組織變更 |
權限標識
| 權限標識 | 作用 |
|---|---|
link.snsapi.base | 申請端內免登 code |
contact.department.read | 讀取部門和部門成員 |
contact.user.read | 讀取成員詳情 |
enterprise.info.read | 讀取企業基礎資訊 |
robot.push | 發送應用機器人訊息 |
通用約定
- 應用級令牌預設有效期為 7200 秒，建議快取並在過期前刷新。
code預設有效期為 300 秒且只能使用一次。- 成員 ID、部門 ID 在 JSON 中使用字串。
- 查詢介面可在網路錯誤或 5xx 時有限重試；鑑權、參數和權限錯誤不要自動重試。
- 詳細請求參數、響應欄位和多語言示例見服務端 API。
核心概念與憑證
應用狀態
| 狀態 | 說明 |
|---|---|
| 開發中 | 可以設定和聯調，但尚未向員工投放 |
| 已發布 | 按可見範圍投放到工作臺，開放介面可用 |
| 已停用 | 員工無法開啟應用，已簽發令牌失效 |
| 已刪除 | 應用及其設定被刪除，原應用標識不再復用 |
關鍵概念
| 概念 | 說明 |
|---|---|
| 可見範圍 | 決定員工能否看到應用，也決定通訊錄介面返回範圍 |
| 平臺入口 | 應用在桌面端或行動端開啟時使用的 H5 地址 |
| 端內免登地址 | 允許頁面申請 code 的地址白名單 |
| 應用機器人 | 以應用身份向成員發送單聊訊息的機器人 |
| 群聊機器人 | 繫結群聊並透過 Webhook 發送訊息的機器人 |
| 事件訂閱 | 平臺主動向應用回呼組織資料變化 |
憑證分工
| 憑證 | 使用方 | 用途 | 安全要求 |
|---|---|---|---|
appId | 前端和後端 | 標識應用 | 可出現在前端，但不能單獨用於鑑權 |
appSecret | 後端 | 取得應用 access_token | 只保存在後端 |
access_token | 後端 | 呼叫開放介面 | 不下發到瀏覽器或客戶端 |
code | 前端到後端 | 一次性換取當前使用者身份 | 不快取、不寫日誌、不放 URL |
| Webhook 令牌與密鑰 | 後端 | 呼叫群聊機器人 | 只保存在服務端並定期輪換 |
客戶端登入態只用於客戶端申請 code；應用 access_token 只用於服務端呼叫開放介面。不要混用客戶端登入態、應用令牌或應用密鑰。
身份換取
- 頁面透過官方 SDK 申請一次性
code。 - 頁面透過 HTTPS 將
code提交給應用後端。 - 應用後端使用
access_token呼叫 UserInfo 介面。 - 後端根據返回的
userId建立應用自己的會話。
code 綁定的使用者身份是權威來源，請求體中另外提交的使用者 ID 不能覆蓋平臺身份。
應用建立與發布
建立應用
在管理後臺進入開發者中心，建立企業內部應用並填寫應用名稱、圖示、負責人和應用描述。建立成功後取得 appId；appSecret 只展示給有權限的管理人員，應立即保存到服務端密鑰管理系統。
設定應用
| 設定項 | 用途 |
|---|---|
| 桌面端平臺入口 | 員工從桌面端工作臺開啟的 H5 地址 |
| 行動端平臺入口 | 員工從行動端工作臺開啟的 H5 地址 |
| 端內免登地址 | 允許頁面申請 code 的地址白名單 |
| 可見範圍 | 決定哪些員工可以看到應用和讀取哪些組織資料 |
| 開放權限 | 開啟通訊錄、企業資訊、機器人等服務端能力 |
| IP 白名單 | 限制服務端 API 的來源 IP，可選 |
| 事件訂閱 | 設定組織事件回呼地址、簽名令牌和加密密鑰 |
| 機器人 | 建立應用機器人或設定群聊機器人 |
平臺入口與端內免登地址是兩個不同設定：入口決定應用從哪裡開啟，免登地址決定哪些頁面可以申請授權碼。
發布版本
設定保存後建立版本並發布。只有已發布、已啟用且已開啟客戶端顯示的應用，才會投放到工作臺並正常使用開放介面。
發布前檢查：
- 兩端入口均為可訪問的 HTTPS 地址；
- 免登地址覆蓋實際發起授權的頁面；
- 可見範圍和開放權限符合最小權限原則；
- 服務端已設定
appSecret、回呼驗簽和令牌快取； - 頁面已處理瀏覽器環境、授權失敗、網路逾時和重複進入；
- 機器人訊息已設定冪等鍵和失敗重試策略。
版本變更
修改入口、可見範圍、權限或機器人設定後，應重新發布版本並在目標端驗證。停用應用會阻止員工開啟應用，並使已簽發的 access_token 失效；刪除應用後原 appId 不再復用。
機器人與事件概覽
平臺提供兩類機器人和一類事件訂閱能力，三者的憑證、訊息範圍和處理方式不同。
| 能力 | 用途 | 呼叫或接收方式 | 適合場景 |
|---|---|---|---|
| 應用機器人 | 以應用身份向成員發送單聊訊息 | 服務端 API + access_token | 告警、待辦、審批提醒 |
| 群聊機器人 | 向綁定的群聊發送訊息 | Webhook + 簽名 | 群通知、值班播報 |
| 事件訂閱 | 接收成員和部門變化 | HTTPS 回呼 + 驗簽解密 | 組織資料增量同步 |
選擇建議
- 需要向指定成員觸達時使用應用機器人；批量發送時使用批量介面並處理逐項結果。
- 只需要向一個工作群廣播時使用群聊機器人，不要把 Webhook 密鑰當作應用令牌。
- 需要持續同步組織資料時，使用事件訂閱作為變更信號，並用通訊錄 API 定期對帳。
通用安全要求
- 所有機器人和事件密鑰只保存在服務端。
- 對發送請求使用冪等鍵，對事件使用
eventId去重。 - 回呼先驗證簽名、時間戳和解密結果，再解析業務欄位。
- 不要在日誌中記錄令牌、簽名原文、授權碼或完整回呼密文。
最小接入閉環
建立應用 → 設定入口與權限 → 發布應用 → 頁面申請 code
→ 服務端換取使用者身份 → 服務端呼叫業務 API → 建立應用自己的會話
設計原則
- 客戶端和服務端使用不同憑證，不能互相替代。
- 應用可見範圍同時影響工作臺展示、免登和通訊錄資料返回。
- 一次性
code只用於換取使用者身份，換取後應建立應用自己的登入態。 - 機器人訊息和事件訂閱都應設計冪等、重試和失敗告警。