★ FEATURED ARTICLE 简介这份文档面向需要与泛微协同办公系统做集成的开发者与运维人员聚焦泛微9.0 REST接口的实际调用方法帮助解决注册鉴权、流程创建与单点登录等对接难题。资源包内共1个docx文件压缩包约1.71MB以图文步骤形式整理接口地址、请求头与请求体示例便于对照查阅。内容覆盖注册接口获取appid与spk、applytoken接口通过RSA加密获取token、doCreate接口创建流程实例以及mainData与detailData主表和子表数据的填写格式并附E9单点登录getToken接口与requestid、ssoToken拼接示例。目前已有8350人学习下载适合需要快速跑通泛微接口联调、排查鉴权与参数格式问题的中高级开发者参考。1. 泛微 9.0 REST 接口调用说明从创建流程到单点登录的落地拆解手里拿到一份泛微 9.0 的 REST 接口调用说明很多人第一反应是翻到接口列表就开始拼 URL结果调创建流程接口时返回 500调单点登录时跳转死循环。这份文档真正值钱的地方不在接口数量而在于它把泛微 9.0 的鉴权体系、流程创建参数结构、单点跳转令牌机制讲清楚了。泛微 9.0 的 REST 接口覆盖了流程创建、单点登录、组织架构同步、文档操作等核心场景适合正在做 OA 系统集成、需要把外部业务系统跟泛微打通的后端开发和实施人员。如果你手上正好有这份说明别急着写代码先把鉴权和参数结构吃透后面能省掉大量排查时间。2. 鉴权体系与接口调用前置条件为什么你的 token 总是过期2.1 泛微 9.0 REST 鉴权的三种模式泛微 9.0 的 REST 接口鉴权不是单一方案它根据调用场景分了几种模式。最常见的是基于appidappsecret换取token的模式适合服务端到服务端的后台调用另一种是基于用户会话的sessionkey模式适合已经登录的前端页面发起请求还有一种是针对单点登录场景的stoken令牌模式这个后面单独讲。先说你最可能踩坑的第一种。泛微 9.0 获取 token 的接口通常是这样的# 获取 token 的典型请求 curl -X POST http://{oa_host}/api/ec/dev/auth/applytoken \ -H Content-Type: application/x-www-form-urlencoded \ -d appidyour_appid \ -d appsecretyour_appsecret返回结构一般包含token和expires_in两个关键字段。expires_in单位是秒泛微默认给的有效期不算长常见是 7200 秒。这里第一个坑就来了很多人拿到 token 后缓存起来但没算好过期时间结果业务跑着跑着突然报鉴权失败。我一般会在缓存里存token的同时记一个expire_at now expires_in - 300留 5 分钟缓冲避免边界时间翻车。appid和appsecret的生成入口在泛微后台的「集成中心」或「接口管理」模块不同补丁版本位置略有差异。生成后要确认对应的接口权限已经勾选否则 token 能拿到但调具体接口时返回 403。2.2 请求头与公共参数的固定写法泛微 9.0 的 REST 接口在请求头上有一套固定要求漏掉任何一个都可能直接 401 或 500。常见的请求头包括请求头是否必填说明Content-Type必填创建流程用application/json鉴权接口用application/x-www-form-urlencodedappid必填应用标识跟申请 token 时一致token必填鉴权通过后拿到的令牌userid条件必填部分接口需要指定操作人不传则用 appid 绑定的默认用户这里有个容易忽略的点userid在创建流程接口里非常关键它决定了流程的创建人是谁。如果不传泛微会用 appid 对应的系统账号导致流程创建出来挂在错误的人名下后续审批流转全乱。血泪经验是创建流程前先确认userid对应的泛微用户存在且状态正常否则接口返回的错误信息可能只有一句「用户不存在」排查起来很费时间。2.3 用 Postman 先跑通再写代码我一般建议先用 Postman 把鉴权和创建流程两个接口跑通再动代码。步骤很简单新建一个 POST 请求URL 填http://{oa_host}/api/ec/dev/auth/applytokenBody 选x-www-form-urlencoded填入appid和appsecret发送后拿到token。新建第二个 POST 请求URL 填创建流程的接口地址Headers 里加上appid、token、Content-Type: application/jsonBody 选raw并填入 JSON 参数。观察返回的status字段泛微一般用status: 1表示成功status: 0或非 1 表示失败具体错误码在message里。这一步能帮你排除掉网络、鉴权、参数格式三类问题中的前两类剩下的就是纯业务参数问题了。3. 创建流程接口的参数结构与实战调用3.1 创建流程接口的 URL 与请求体结构泛微 9.0 创建流程的 REST 接口地址通常是/api/workflow/paService/createRequest或类似路径具体以你手上的说明文档为准。请求体是一个 JSON 对象核心字段包括workflowId、requestName、creatorId、data等。{ workflowId: 123, requestName: 外部系统发起的采购申请, creatorId: 10086, data: { field_001: 采购部, field_002: 办公用品一批, field_003: 2025-06-01 } }workflowId是流程模板的 ID不是流程名称。这个 ID 要在泛微后台的流程管理里查或者通过「获取流程列表」接口拿到。很多人直接填流程名称结果接口报「流程不存在」这就是没搞清楚 ID 和名称的区别。creatorId是创建人的泛微用户 ID不是登录名。泛微内部用id来标识用户登录名是另一套。如果你只有登录名需要先调用户查询接口换到id。data里的字段名field_001、field_002是泛微流程表单的字段标识不是显示名称。这些标识在流程表单设计器里能看到通常是field_加数字的格式。字段类型也要匹配日期字段传字符串2025-06-01通常没问题但如果是数字字段传了非数字字符串接口会直接报参数错误。3.2 用 Python 封装一个可复用的创建流程函数下面是一个我常用的 Python 封装把鉴权和创建流程串起来import requests import time class WeaverClient: def __init__(self, host, appid, appsecret): self.host host.rstrip(/) self.appid appid self.appsecret appsecret self.token None self.token_expire_at 0 def _get_token(self): 获取 token带本地缓存和过期缓冲 if self.token and time.time() self.token_expire_at: return self.token url f{self.host}/api/ec/dev/auth/applytoken resp requests.post(url, data{ appid: self.appid, appsecret: self.appsecret }, timeout10) result resp.json() # 泛微返回的 token 字段名以实际文档为准常见为 token self.token result.get(token) expires_in int(result.get(expires_in, 7200)) # 留 300 秒缓冲避免边界过期 self.token_expire_at time.time() expires_in - 300 return self.token def create_request(self, workflow_id, request_name, creator_id, data): 创建流程 token self._get_token() url f{self.host}/api/workflow/paService/createRequest headers { appid: self.appid, token: token, Content-Type: application/json } payload { workflowId: str(workflow_id), requestName: request_name, creatorId: str(creator_id), data: data } resp requests.post(url, jsonpayload, headersheaders, timeout15) return resp.json()这段代码的关键点有三个一是 token 缓存带了 300 秒缓冲避免刚好在过期瞬间发起请求二是workflowId和creatorId都强制转成字符串因为泛微接口对类型比较敏感传数字有时会报格式错误三是超时时间设了 10 到 15 秒泛微在流程节点多的时候响应会慢超时太短容易误判为失败。3.3 创建流程后的返回值解析与后续动作创建流程成功后泛微一般返回requestId和status。requestId是这次流程实例的唯一标识后续如果要查流程状态、催办、或者做单点跳转都要用到它。result client.create_request( workflow_id123, request_name外部系统发起的采购申请, creator_id10086, data{ field_001: 采购部, field_002: 办公用品一批, field_003: 2025-06-01 } ) if result.get(status) 1: request_id result.get(requestId) print(f流程创建成功requestId{request_id}) else: print(f创建失败{result.get(message)})注意status的类型。泛微有些版本返回字符串1有些返回数字1代码里最好做兼容判断比如str(result.get(status)) 1。这个细节看起来小但在不同补丁版本之间迁移时经常翻车。4. 单点登录接口的令牌机制与跳转实现4.1 单点登录的 stoken 是怎么生成的泛微 9.0 的单点登录不是简单拼一个 URL 带上用户名密码而是用stoken令牌机制。流程是外部系统先调泛微的登录令牌接口传入用户标识泛微返回一个一次性的stoken然后外部系统把stoken拼到泛微的登录 URL 上用户浏览器跳转过去就自动登录了。# 获取单点登录 stoken 的典型请求 curl -X POST http://{oa_host}/api/ec/dev/auth/ssoToken \ -H Content-Type: application/x-www-form-urlencoded \ -d appidyour_appid \ -d appsecretyour_appsecret \ -d loginIdzhangsanloginId是泛微用户的登录名不是用户 ID。这一点跟创建流程接口不一样创建流程用creatorId用户 ID单点登录用loginId登录名。搞混了就会报「用户不存在」。返回的stoken通常有效期很短常见是 60 秒到 5 分钟而且是一次性的用过就失效。所以不能提前批量生成一堆 stoken 存着必须每次跳转前实时获取。4.2 拼接单点登录 URL 的正确姿势拿到stoken后拼接待登录 URL 的格式一般是http://{oa_host}/login/Login.jsp?stoken{stoken}或者有些版本是http://{oa_host}/wui/index.html?stoken{stoken}具体路径以你手上的说明文档为准。这里有个坑URL 里的stoken如果包含特殊字符必须做 URL 编码否则浏览器解析时会截断导致登录失败。Python 里用urllib.parse.quote处理一下就行。from urllib.parse import quote def build_sso_url(host, stoken): 拼接单点登录跳转 URL encoded_token quote(stoken, safe) return f{host}/login/Login.jsp?stoken{encoded_token}另外单点登录跳转必须是在浏览器里发起不能是服务端requests去请求。因为泛微登录成功后要写 Cookie 到浏览器服务端请求拿到的 Cookie 没法传给用户浏览器。这个逻辑搞反了就会出现「接口返回成功但用户还是没登录」的玄学现象。4.3 单点登录与创建流程的联动场景实际项目里单点登录和创建流程经常一起用。典型场景是外部系统里用户点了一个按钮系统先在后台调创建流程接口生成流程实例拿到requestId然后再生成stoken把用户直接跳到泛微的流程详情页。# 先创建流程 result client.create_request(...) request_id result.get(requestId) # 再获取 stoken stoken_resp requests.post( f{host}/api/ec/dev/auth/ssoToken, data{appid: appid, appsecret: appsecret, loginId: zhangsan}, timeout10 ) stoken stoken_resp.json().get(stoken) # 拼接跳转到流程详情页的 URL sso_url f{host}/workflow/request/ViewRequest.jsp?requestid{request_id}stoken{quote(stoken)}这样用户点一下按钮流程创建了页面也直接跳过去了体验比较顺。注意requestid和stoken两个参数都要带上缺一个都会导致跳转后看不到流程或者没登录。5. 避坑与常见问题排查那些文档里没写的细节5.1 现象创建流程返回 500message 为空原因最常见的是data里的字段标识跟流程模板不匹配。泛微在字段校验失败时有时不返回具体哪个字段错了只给一个空 message 加 500 状态码。解决先把data精简到只传一个必填字段跑通后再逐个加字段定位到具体是哪个字段的问题。另外确认流程模板的版本跟接口调用的版本一致模板改过字段但接口还在传旧字段也会 500。5.2 现象token 刚拿到就报鉴权失败原因服务器时间不同步。泛微在校验 token 时会比对时间戳如果调用方服务器跟泛微服务器时间差超过几分钟token 会被判定为无效。解决检查两台服务器的时间同步情况Linux 上用date命令对比必要时配 NTP 同步。这个坑很隐蔽因为 token 明明刚拿到但就是不能用。5.3 现象单点登录跳转后提示「令牌已失效」原因stoken被用了两次。有些前端框架在页面加载时会发多次请求或者用户刷新了页面导致同一个stoken被重复提交。泛微的stoken是一次性的第二次用就失效。解决确保每次跳转前重新获取stoken不要在页面里缓存stoken。如果是 SPA 应用在路由跳转前实时获取。5.4 现象创建流程成功但流程挂在错误的人名下原因creatorId传的是登录名而不是用户 ID泛微可能匹配到了一个默认用户或者系统账号。解决先用用户查询接口把登录名换成用户 ID再传给creatorId。泛微的用户查询接口一般是/api/hrm/user/getUserInfo之类的路径具体以文档为准。5.5 现象接口在测试环境正常生产环境超时原因生产环境的流程模板节点多、触发了一些后台逻辑比如触发其他流程、发消息导致响应时间变长。解决把超时时间从默认的 5 秒调到 15 到 30 秒同时确认泛微服务器的负载情况。如果经常超时考虑把创建流程改成异步方式先返回一个受理标识再通过回调或轮询拿最终结果。6. 进阶技巧用日志和重试机制把接口稳定性拉满接口调通只是第一步真正上生产后网络抖动、泛微服务重启、token 过期这些问题都会出现。我一般会在客户端加两层保护请求日志和有限重试。import logging import requests from requests.adapters import HTTPAdapter from urllib3.util.retry import Retry logging.basicConfig(levellogging.INFO, format%(asctime)s %(levelname)s %(message)s) def build_session(): 构建带重试的 session session requests.Session() retry Retry( total3, backoff_factor1, status_forcelist[500, 502, 503, 504], allowed_methods[POST, GET] ) adapter HTTPAdapter(max_retriesretry) session.mount(http://, adapter) session.mount(https://, adapter) return session def create_request_with_log(client, workflow_id, request_name, creator_id, data): 带日志和重试的创建流程 session build_session() token client._get_token() url f{client.host}/api/workflow/paService/createRequest headers { appid: client.appid, token: token, Content-Type: application/json } payload { workflowId: str(workflow_id), requestName: request_name, creatorId: str(creator_id), data: data } logging.info(f创建流程请求: workflowId{workflow_id}, creatorId{creator_id}) try: resp session.post(url, jsonpayload, headersheaders, timeout20) logging.info(f创建流程响应: status{resp.status_code}, body{resp.text[:500]}) return resp.json() except requests.exceptions.RequestException as e: logging.error(f创建流程请求异常: {e}) raise重试策略里status_forcelist只对 5xx 做重试不要对 4xx 重试因为 4xx 通常是参数错误重试多少次都一样。backoff_factor1表示第一次重试等 1 秒第二次等 2 秒第三次等 4 秒给泛微服务一点恢复时间。日志里我习惯把请求参数和响应体的前 500 个字符打出来这样出问题时能快速定位是参数错了还是泛微那边报了什么错。但注意别把appsecret和完整 token 打进日志生产环境日志可能被多方查看敏感信息要脱敏。还有一个习惯每次泛微升级补丁后我会把创建流程和单点登录两个核心接口重新跑一遍回归。因为泛微不同补丁版本之间接口路径、参数名、返回结构都可能有微调文档不一定同步更新。从那以后我每次上线前都强制走一遍鉴权、创建流程、单点跳转这三步的冒烟测试确认没问题再放量。希望帮到你。本文还有配套的精品资源点击获取
阅读完成 · 觉得有帮助？
