简介《泛微E9统一集成待办中心接口文档》面向需要将异构系统待办任务接入泛微E9统一待办中心的开发或运维人员核心价值在于解决多系统待办分散、无法集中查看与统一处理的问题。文档基于Webservice接口梳理了完整集成路径先说明服务端配置文件 /ecology/classbean/META-INF/xfire/services.xml 中 OfsTodoDataWebService 的命名空间、服务类与实现类再讲解 receiveTodoRequestByMap 方法的入参和返回参数并逐一解释 syscode、flowid、requestname、workflowname、nodename、pcurl、appurl、creator、createdatetime、receiver、receivedatetime、receivets 等字段的用途还给出可直接套用的SOAP请求XML示例方便开发者快速构造请求并完成联调。对于接口返回值文档中的 dateType、operType 和时间戳 receivets 能帮助判断待办创建状态避免旧数据覆盖新请求这些细节正是联调阶段容易踩坑的地方。压缩包为单个PDF文档体积仅1.6MB便于随时查阅。已有4140人在CSDN浏览学习适合正在做泛微E9二次开发、统一门户待办聚合或OA与业务系统对接的技术人员参考。1. 统一集成待办中心一张接口文档解决跨系统待办不同步问题做过 OA 集成的人都有过这种经历业务系统里的待办已经审批完了OA 里还挂着一堆红点或者反过来OA 里的流程结束了好几天业务系统那边单据还压在经办人头上。两边数据各走各的最终落点成了每天的「人工核对」。泛微 E9 的统一集成待办中心就是为了把第三方业务系统的待办统一收口到 OA 待办门户里让用户只在一个地方看到所有要处理的事处理完的结果再沿着接口回传给原系统。这次要拆的这份接口文档核心就是这个入口的对接链路包括认证怎么签、待办怎么推、状态怎么回、失败怎么查。文档不一定厚但对接逻辑比想象中繁琐既要调通接口又要管住签名、回调、唯一键、时间格式这些容易翻车的细节。适合谁读做 OA 与外部系统对接的集成工程师、实施顾问还有需要在 E9 上做二次开发的同事。下面按我实际对接时的路径来拆先定姿势再跑通最小接口再处理状态回传最后用排查手段兜底。2. 先认准对接姿势E9 待办接口的两种接入模式与认证方式拿到接口文档先别急着看新增待办的字段第一件事是确定你属于哪种接入模式。模式选错了后面的参数表和回调逻辑全对不上调试时间至少翻一倍。2.1 主动推送与被动拉取先分清你属于哪一侧统一集成待办中心里第三方业务系统和 OA 之间有两种常见关系。第一种是业务系统主动把待办推送到 E9由 OA 统一展示用户点开待办后跳回业务系统处理处理完再被动等回调。第二种是 OA 侧提供视图或查询能力让待办中心定时去业务系统拉取待办列表。接口文档里如果大量出现 add、update、revoke 这类动词多半是第一种如果出现 query、list、sync 这类词大概率是第二种。我一般会先确认业务系统的待办数据是实时的还是允许分钟级延迟。实时性强、用户就指着 OA 待办中心做当日工作入口的选主动推送数据量很大、只要求 OA 每天固定时间汇总一次的选被动拉取。主动推送对接成本高一点但用户体验好被动拉取实现简单但每次拉全量还是增量、已读状态怎么同步都比推送更麻烦。选型时要额外评估一条业务系统是否具备「被回调」的条件。主动推送模式下OA 用户在待办中心点了「处理」OA 需要把处理结果传回业务系统业务系统必须提供一个可公网访问的接收地址。很多内网系统这一关就卡住了。被动拉取模式则反过来要求 OA 能访问业务系统的数据库或接口。接口文档里通常两类都覆盖但实际项目中大部分是两种混着用常用待办走推送历史待办走拉取初始化。2.2 签名认证是第一个拦路虎token 与 sign 两种流派泛微 E9 的第三方集成接口认证方式常见的有两套。一套是先用 appId 和 appSecret 换 token后续请求带 token 访问token 有过期时间另一套是签名机制把请求参数按约定排序后拼接加上 secret 做摘要服务端验签通过才放行。接口文档里如果出现 access_token、expires_in那就是前一套如果出现 sign、nonce、timestamp就是后一套。签名机制更容易踩坑因为验签对参数的拼接顺序和编码方式极其敏感。常见做法是先把所有请求参数剔除 sign 本身按参数名 ASCII 升序排列拼成 keyvaluekeyvalue 的形式再在末尾拼接 appSecret做摘要后放到请求里。这里有个玄学点有些服务端会用 URL 解码后的参数验签有些用原始串验签如果你这边对参数做了编码而对方没做就会一直报签名错误。我习惯的做法是请求发出去之前先打印一遍待签串和服务端要求的格式逐字符比对比反复猜测快得多。无论是 token 还是 sign对接第一步都建议先在集成环境跑通一个最简单的接口验证认证链路本身没问题再开始碰业务数据。E9 的集成环境一般会提供配套的接口调试页面能看到请求头、响应报文和错误码用那个页面把签名算出来的结果和服务端返回的报文对照能省掉很多抓包时间。3. 从零跑通新增与更新待办核心参数与最小实现认证链路通了之后第一个要调通的往往就是新增待办接口。这一章把最小实现拆开讲包括参数怎么构造、唯一键怎么用、更新和撤销怎么区分以及最容易出错的时间与编码细节。3.1 新增待办最小请求字段拆解与签名拼装以主动推送为例一般需要一个 POST 请求把待办标题、待办说明、处理人、跳转地址、业务唯一键、到期时间等字段放进去。下面用一个贴近常见写法的 curl 示例说明整体结构具体路径和参数名以你们拿到的文档为准我这里用通用命名签名规则按 2.2 的排序拼接方式处理curl -X POST https://E9_server/api/todo/add \ -H Content-Type: application/json \ -d { appId: your_app_id, timestamp: 2025-01-08 10:00:00, nonce: abc123, sign: 计算出的签名串, bizKey: SALE-20250108-001, todoTitle: 销售合同审批北京区域2025年1月订单, todoDesc: 金额超过50万需要区域总监审批, handler: zhangsan, handlerType: user, openUrl: http://bizsystem.example.com/approval/detail?id10001, expireDate: 2025-01-10 18:00:00, priority: 2, sourceSystem: CRM }这个请求里有几处值得说明。bizKey 是接入方生成的业务唯一键E9 靠它来识别「同一条业务待办」推送重复时服务端可以靠它做幂等。openUrl 是用户在 OA 待办中心点击待办后跳转回业务系统的地址要保证业务系统侧能正常识别这个会话。handler 是处理人的账号或工号handlerType 决定它是按人匹配还是按角色匹配对接前需要和 OA 管理员确认账号体系是用的工号还是登录名这一点最容易在联调阶段返工。sign 的计算是整个请求里最不能出错的部分。常见规则是把除 sign 外的所有参数参与拼串按 key 的字典序排列值只取字符串本身拼完加上 secret 再做摘要。如果文档里写的是「包含业务字段一起参与签名」那 openUrl、todoTitle 这些字段在拼串时也要带上而且顺序必须和文档完全一致。拼串前把所有值为 null 的字段剔除、把嵌套对象序列化成 JSON 字符串再参与签名是两种常见的补充约定务必以文档为准。3.2 更新、撤销与幂等让同一把 bizKey 决定状态待办不是只推一次就结束的。业务单据流转过程中待办标题、处理人、到期时间都会变这就用到了更新能力。更新接口和新增接口的参数结构几乎一样只是动作从 add 换成 update服务端通过 bizKey 找到原有待办做覆盖式更新。这里有一个值得养成的习惯更新请求里把没变的字段也一并传上避免服务端按「空值不更新」或「空值清空」的不同策略产生歧义。撤销则是把已推送的待办置为不可见或已完成。常见做法是调用 revoke 接口传 bizKey 一个参数即可。撤销不是删除服务端一般会把待办标记为取消状态并留存记录这样审计时有迹可循。如果你没有调 revoke而是把待办再次 update 成“已完成”标题用户那边看起来是办了但报表统计里它会一直挂在待办明细里后续对账很麻烦。幂等设计是这三个接口能不能稳定运行的根基。业务系统侧生成的 bizKey 必须稳定不能每次推送同一个单据时重新随机生成。否则重复推送就会在待办中心出现两条内容一样的待办用户处理完一条还剩一条投诉直接到你头上。我见过一个项目就是业务方在同一张单子的状态流转里用了时间戳拼 bizKey一次审批流程生成了五个不同的待办用户直接在 OA 里点了五遍场面很尴尬。正确做法是让单据号本身或单据号加节点标识作为 bizKey跨接口一致。3.3 时间格式与编码两个不起眼却能卡死联调的问题时间字段是所有对接里最容易被忽略的坑。E9 侧接收的时间格式常见的有 yyyy-MM-dd HH:mm:ss 和 yyyy-MM-ddTHH:mm:ss 两种如果业务系统传的是时间戳通常需要转成字符串再传。这里要特别留意时区如果业务系统和 E9 不在同一个时区直接传本地时间会导致到期时间偏差好几个小时待办提前超期或者迟迟不超期用户感知都很明显。我一般会约定统一用服务器本地时间并且都按东八区处理联调前先用一个已知时间在两边各打印一次避免各写各的格式。编码问题则集中在中文标题和跳转地址上。请求体统一用 UTF-8 是基本要求但有些老业务系统内部是 GBK吐出来的字符串经过签名拼串后再被服务端解码就可能变成乱码。签名用的是原始字节还是解码后的字符串也会受到编码影响。排查这类问题最快的办法是把待办标题先传成纯英文或数字跑通了再加中文一次只变一个变量。4. 把处理结果送回业务系统回调 URL 的配置与容错待办推送到 OA 只是上半场。用户真正在 OA 里点开待办、进入业务系统处理完或者直接在 OA 端做了办结操作之后E9 需要把结果通知回业务系统这一步依赖回调机制也是接口文档里最容易被低估篇幅的部分。4.1 回调的完整链路从 OA 操作到业务系统落库回调的基本链路是这样的用户在 OA 待办中心对待办执行「处理」或「办结」动作E9 的服务端根据该待办的来源配置找到业务系统注册的回调地址以 POST 方式把待办标识、处理人、处理时间、处理结果等字段推送过去。业务系统收到后更新自己的单据状态再返回一个约定好的确认报文给 E9。回调地址一般需要在 E9 后台的集成配置里维护有些接口文档会要求接入方在新增待办时直接带上 callbackUrl 字段两种方式都有。我倾向于把回调地址放在后台配置而不是每条待办都传因为回调地址属于通道层面的配置放后台便于统一修改和排查。如果每条待办都传某个业务方传错一次回调就静默丢失了连日志都不好找。接收端实现上业务系统需要提供一个 HTTP 接口接收 POST 并解析参数。下面给一个 Java 侧的接收示例按常见写法处理PostMapping(/api/todo/callback) public MapString, Object callback(RequestBody MapString, Object params) { // 1. 先记录原始报文出问题时有据可查 log.info(callback received: {}, JSON.toJSONString(params)); // 2. 验证签名验签失败直接返回错误码 if (!SignUtil.verify(params, appSecret)) { log.warn(callback sign verify failed: {}, params.get(bizKey)); return Collections.singletonMap(code, -1); } // 3. 按 bizKey 更新业务单据状态 String bizKey (String) params.get(bizKey); String action (String) params.get(action); // approve / reject / complete todoService.updateStatusByBizKey(bizKey, action); // 4. 返回约定的确认报文 return Collections.singletonMap(code, 1); }这段代码的重点在第一步和第二步。第一步先落日志而不是先做业务处理是回调接口的救命习惯——回调报文是 E9 主动发起的业务系统侧看不到请求方是谁只有日志能还原当时收到了什么。第二步的验签不能省否则任何知道回调地址的人都可以伪造处理结果。返回报文用最简单结构E9 侧一般认 code1 表示成功code 非 1 视为失败并进入重试机制。4.2 回调失败与重试为什么必须做幂等和超时控制回调不可能每次都成功。业务系统升级重启、网络闪断、接口超时都可能导致 E9 发过来的回调没有得到正确响应。E9 对失败回调一般有自己的重试策略常见的是间隔递增重试若干次超过次数后待办中心会标记回调失败并留待人工处理。这意味着业务系统的回调接口必须支持重复调用同一个 bizKey 的处理结果要被设计成幂等写入。幂等写法的常见实现是更新单据状态时带一个条件比如「仅当当前状态是待处理时才更新为已审批」。如果收到重复回调第二次进来时状态已经不是待处理直接返回成功即可不再重复触发后续的下游动作。很多对接方在这里翻车第一次回调成功后又收到一次重试结果把单据状态从「已审批」又改回「处理中」业务链条直接乱掉。超时控制也值得统一约定。回调接口的处理逻辑尽量短把耗时操作放到异步队列里去执行接口本身先快速返回成功。如果一个回调处理超过十秒E9 大概率已经超时并开始重试这时候就算你最终处理成功了也还会再收到重复回调。常见做法是接收后先落库再丢进消息队列接口立即返回。返回内容里不要放复杂结构一个状态码加一句提示就够减少序列化开销。5. 对接中的常见问题与避坑记录现象、原因、解决这一章把我在对接 E9 统一集成待办中心时实际踩过的、以及围观同事踩过的坑集中整理一下按「现象 → 原因 → 解决」的方式展开。每一条都是从联调现场的报错和异常里总结出来的不是文档上的标准答案。5.1 待办推送成功但待办中心看不到先查 handler 匹配现象接口返回成功日志也显示推送正常但在 OA 待办中心里就是看不到这条待办切换几个用户都看不到。原因多数时候是 handler 字段传的值和 E9 里的人员账号对不上。业务系统里存的可能是员工姓名而 E9 里配置的登录名是工号也可能 handlerType 传成了 role但角色编码在 E9 里不存在。还有一种隐蔽情况handler 传的是离职人员或已停用账号待办会进入异常节点而不是正常待办列表。解决先用接口文档里配套的查询接口按 bizKey 查这条待办的落库情况和当前状态能看到处理人解析结果。如果查询接口不可用就找 OA 管理员查后台待办表重点看 handler_code 和 handler_type 两个字段存进去的值是否和预期一致。修正后重新推送一次不要反复用同一条 bizKey 覆盖否则容易把排查现场冲掉。5.2 点击待办跳转后提示登录失效openUrl 背后的会话问题现象待办在 OA 里显示正常点开后也跳到了业务系统页面但页面提示登录超时或者要求重新登录用户体验很割裂。原因openUrl 只是给了业务系统一个地址但业务系统不认识这个用户是谁。常见原因有两个一是 openUrl 里没有携带业务系统侧的会话标识或免登 token二是业务系统对来源地址做了域名限制OA 域名不在白名单里。解决让业务系统在 openUrl 上支持一次性的免登参数比如 token 字符串业务系统接收后用它换取会话。免登参数生成后要设置短有效期比如五分钟内有效避免地址被转发。同时把 OA 的访问域名加进业务系统的来源白名单。如果不想改业务系统代码也可以调整待办中心配置让待办点击行为改为复制链接而不是直接跳转用户自己把链接贴到浏览器里打开通常能绕开会话丢失问题但体验会差一些只能当临时方案。5.3 中文标题乱码从签名串到落库全链路排查现象待办推送成功后标题里的中文变成一串问号或乱码英文和数字正常摘要和描述字段同样受影响。原因链路里某一段用了非 UTF-8 编码。最常见的是业务系统侧集成了老旧的 HTTP 客户端默认用 ISO-8859-1 发送 POST body其次是签名拼串时用了 getBytes() 没指定字符集导致签名串本身已经错了但碰巧服务端也按同样错误的方式验签等于两边一起错只不过标题花掉了。解决先把请求体打印出来看原始字节确认发送端编码再检查签名拼串时是否指定了 UTF-8 字符集。然后把服务端日志的日志编码也确认一遍有些时候数据显示乱码只是日志文件编码不对实际库里是好的。用数据库工具直接查待办表里的标题字段最可信以它为准判断问题在哪一段。我习惯在推送脚本里把请求前后的内容都打印一份问题复现时直接比对。5.4 重复推送产生多条待办bizKey 生成规则没守住现象同一个业务单据在待办中心里出现了两条甚至多条记录用户处理完一条另一条还挂着状态不同步。原因bizKey 在重复推送时变了。常见于业务方用时间戳、流水号或随机数参与 bizKey 拼装也有的是因为业务系统重发了某个历史请求数据被当成新待办入库。解决bizKey 只能用业务单据的稳定标识来生成比如单据号、单据号加节点标识。推送前先查一次接口确认该 bizKey 是否已存在存在则改为调用更新接口而不是新增。如果已经是新增成功了就用撤销接口把重复的多余待办撤掉保留最新一条。另外要跟业务方约定对接文档里写的「bizKey 是幂等关键」不是建议是必须执行的约束。5.5 回调一直失败且验签不过原始报文和验签顺序不一致现象E9 后台显示回调失败业务系统的日志里能看到请求进来了但验签始终失败改了好几次签名算法都不行。原因回调里的参数经过网络传输后在业务系统接收端被重新解析某些字段的编码或顺序发生了变化。比如 E9 发的是 JSON body业务系统框架自动做了 URL 解码导致参与验签的字符串和 E9 发送端计算签名时用的字符串不一致。另外如果验签时把 JSON 里的字段重新排序了再拼串顺序和发送端不一致也必然失败。解决回调验签时不要对接收到的报文做任何加工直接用原始 body 字符串参与校验。如果框架自动解析了 body就从 request 里重新获取原始输入流拿到 byte[] 再按文档要求的算法验签。调试时在验签方法入口打印接收到的原始报文和参与验签的拼串跟 E9 侧发送日志里记录的报文逐字节比对多对比一两次就能定位差异点。6. 上线前这样验证和复盘把测试用例与日志排查固化成习惯对接调通不等于可以上线。E9 统一集成待办中心这种跨系统链路线上问题几乎都出在「正常流程之外的分支」里所以上线前的验证要刻意覆盖异常分支而不是只跑通主流程。我习惯先建一张测试用例表按业务动作列场景每个场景对应一个预期结果新增待办推送后能在待办中心看到同一个 bizKey 重复推送不产生第二条更新标题和处理人后待办中心展示随之刷新撤销后待办消失处理待办后回调成功回调不响应时 E9 重试回调验签失败时有错误日志。每到一类用例都记录返回报文和时间方便后面回溯。重点测的是重复推送和回调重试这两类它们最容易被业务方忽略却是在生产环境制造脏数据的头号原因。日志排查是上线后的第一手段。E9 侧打开接口访问日志和异常日志业务系统侧统一打印回调接收日志、签名验签日志和状态更新日志。两边的时间戳要一致否则对照时差会误导判断。我一般约定所有日志里的时间统一用服务器本地时间格式精确到秒。排查问题时先按 bizKey 全局检索把 E9 日志里该 bizKey 的推送记录、回调记录和业务系统侧的接收记录按时间排成一条线问题在哪一段一目了然。最后留一个验证技巧上线后的前三天每天固定时间用查询接口扫一遍当天推送的待办核对数量、状态和失败回调记录。这个动作能帮你确认线上数据量下的稳定性也能及时发现接口文档之外的真实边界。我自己的习惯是把这个核对脚本留在集成环境里不删后续每次业务方调整流程先跑一遍脚本再发版省掉了很多半夜被叫起来查数的时间。希望帮到你。本文还有配套的精品资源点击获取