介绍
工作台开放平台用于把企业业务系统接入工作台。应用可以通过网页入口向员工提供业务功能，也可以通过服务端 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。 - 页面将
code通过 HTTPS 提交给应用后端。 - 应用后端使用
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只用于换取用户身份，应用应在换取后建立自己的登录态。 - 机器人消息和事件订阅都应设计幂等、重试和失败告警。