WorkBuddy集成OA系统操作指南

将WorkBuddy深度集成到现有OA系统中，能够实现单点登录、流程触发与数据双向同步，从而构建一体化的数字办公空间。即使当前OA系统未开放标准API或未配置OAuth信任关系，也无需担心，以下三种主流技术路径可以帮你实现无缝对接。

一、通过OAuth 2.0授权码模式建立可信身份联合

此方式的核心目标是实现单点登录。用户只需在OA系统登录一次，即可安全调用WorkBuddy服务，所有令牌交换都在后端完成，有效避免了前端凭证泄露的风险。

首先，在OA系统后台找到“外部应用接入”或类似模块，创建一个新的Web应用。应用名称可设为“WorkBuddy集成客户端”，最关键的一步是正确设置授权回调地址，必须填入你的WorkBuddy实例专属地址：https://your-workbuddy-domain.com/oauth/callback。此地址后续需要在WorkBuddy后台进行匹配，务必保持一致。

创建成功后，你会获得OA系统分配的client_id和client_secret。接着，进入WorkBuddy管理后台的【集成中心】，找到【OAuth 2.0应用注册】，选择“自定义平台”并手动填入刚才获取的凭证，同时还需要填写OA系统的授权端点（通常是类似/oauth/authorize的路径）和令牌端点（类似/oauth/token）。

为了进一步提升安全性，建议勾选【启用PKCE增强】选项。保存配置后，点击【启动授权流程】，系统会自动跳转到OA登录页面。用户完成认证授权后，WorkBuddy后端便会自动完成令牌交换，获取到访问令牌和刷新令牌，至此，可信身份通道就建立完成了。

二、调用OA系统RESTful API实现流程级联动

如果你的OA系统已经提供了标准的RESTful API文档，那么通过主动调用API来实现数据拉取和流程触发，是一种非常灵活的方式。这尤其适用于需要定期同步待办、审批状态等结构化数据的场景。

实施的第一步，是仔细查阅OA厂商提供的API文档，确认关键接口的可用性，例如获取待办列表的GET /api/v1/tasks/pending，或提交审批的POST /api/v1/approvals/submit。

然后，在WorkBuddy的【数据源中心】添加一个新的自定义API源。为其命名（如“主OA系统”），并填入OA系统API的基础URL，例如https://oa.yourcompany.com/api/v1。在认证方式上，选择“Bearer Token”，并粘贴上一步通过OAuth流程获取的access_token。别忘了启用【自动刷新令牌】选项，以保证长期连接的有效性。

接下来可以配置同步策略。比如，可以设置每15分钟调用一次待办查询接口，并将响应体中的task_id、title等字段映射到WorkBuddy内部的待办事项模型中。

更进一步的自动化可以在【流程编排】中实现。新建一个“OA待办自动处理”流程，添加一个“HTTP请求”节点来调用审批提交接口。在请求的JSON载荷中，可以将approval_id这类参数动态绑定为上一个节点输出的task_id，从而实现流程的自动流转。

三、部署Webhook接收OA系统事件推送

与前两种主动拉取或请求的方式不同，Webhook是一种由OA系统主动推送事件的机制。WorkBuddy作为订阅方实时响应，无需轮询，效率更高，非常适合处理公文签发、流程归档这类需要即时触发的关键动作。

首先，在WorkBuddy管理后台的【事件中心】找到【Webhook服务】，创建一个新的接收端点。系统会为你生成一个唯一的URL，格式类似于：https://your-workbuddy-domain.com/webhook/oa-event-7f3a9d。

然后，登录OA系统的管理员后台，通常在“系统集成”或“Webhook管理”区域，添加一个新的订阅。将上一步生成的URL粘贴到“目标地址”栏中。

在订阅设置中，选择你需要关注的事件类型，例如“公文签发完成”、“流程归档成功”等。内容格式通常选择JSON。为了确保通信安全，务必启用签名验证功能，并复制OA系统生成的secret_key，将其回填到WorkBuddy Webhook配置页的“签名密钥”字段中。

最后，在WorkBuddy侧为每一种事件类型配置具体的响应动作。例如，当收到“公文签发完成”事件时，可以自动触发一个流程：调用本地Word模板引擎生成带电子签章的PDF文件，并将其上传到指定的网络存储路径，如/archive/official-docs/20260518_XXX.pdf。

点击【启用订阅】后，WorkBuddy便开始监听来自OA的事件。首次成功接收到测试事件后，服务状态通常会显示为绿色的对勾图标，标志着实时事件通道已就绪。