简介面向泛微E9协同办公平台二次开发及异构系统对接人员这份资料是统一集成待办中心的Webservice接口说明文档。文档以服务配置文件、方法定义、Map参数说明和SOAP请求XML示例为主线重点讲解receiveTodoRequestByMap接口的调用方式清晰列出syscode、flowid、requestname、pcurl、appurl、receivets等关键字段含义帮助开发者将不同系统的待办任务快速整合到统一待办中心避免重复开发与数据冲突。压缩包内共1个文件为PDF文档大小约1.6MB。目前已有4138人浏览学习。对于正在做泛微E9待办集成、需要梳理接口规范或排查对接参数问题的开发者这份文档可以直接对照使用省去查阅源码与逆向配置的时间。1. 泛微E9统一集成待办中心接口文档先搞清楚它解决什么问题做泛微E9集成的第一天最容易卡住的不是流程建模而是“统一集成待办中心接口文档”这几个字。第三方系统——不管是自研工单、SAP还是MES——想把待办推到OA里或者想让OA的待办回流到外部门户都要走这个中心。它解决的是“两个系统待办不互通”的问题核心动作只有三个推送、更新、办结。这篇文章写给两类人一类是刚接触E9对外接口的实施工程师想知道从哪下手另一类是已经在对接但被鉴权、流程id、已办回调折磨过的开发想找一份能照着排查的实战记录。2. 认清“统一集成待办中心”三种接入方式与四个必看的接口概念2.1 统一集成待办中心在E9里到底是什么E9的待办中心本质是一个“待办汇聚池”。泛微自己的流程待办天然在里面但你公司里的ERP审批、供应商协同、设备巡检工单并不会自动出现在这个池子里。统一集成待办中心就是E9对外开放的一套接口能力第三方系统按规范把待办数据喂进来E9负责渲染、去重、跳转和已办归档。我一般会把“集成待办”和“流程待办”分开看。流程待办是E9引擎产生的有requestid、有节点、有审批历史集成待办是外部系统塞进来的E9不关心你的业务逻辑只关心“给谁看、看什么、点哪跳转”。这个区别决定了你后续所有参数设计。很多项目翻车都是想用流程待办的概念去套集成待办结果字段对不上状态也推不动。从数据结构上说一条集成待办通常包含标题、正文、跳转URL、接收人、来源系统标识、业务主键、过期时间以及一个“待办类型”。这个“待办类型”决定了它显示在我的待办里还是站内信里也是新手最容易漏的字段。理解了这几样再去翻接口文档你会觉得文档里的请求参数每一行都能对上号。2.2 三种接入方式拉取、推送、混合怎么选拿到需求先不要着急调接口把接入方式定下来。E9对接第三方待办我常用的有拉取、推送、混合三种。接入方式谁主动适用场景实时性开发量主要坑拉取E9定时去第三方系统拉待办第三方系统不方便对外开放调用但能提供查询接口分钟级延迟第三方需要写分页查询接口分页游标、已拉取数据的去重推送第三方系统调用E9接口写入待办第三方有服务端能拿到E9的接口地址和凭证秒级第三方写推送逻辑幂等、重复待办、状态同步混合新增用推送已办用回写业务需要闭环待办推进来审批完再通知E9转已办秒级最高状态一致性、回调失败补偿拉取方式适合“E9只做展示”的场景E9不落业务数据但定时任务会消耗性能。推送方式是目前主流因为实时性好且第三方系统是业务源头推完后自己知道改状态。混合模式最贴近真实业务第三方工单审批推一条待办给审批人审批人在E9里点开跳回第三方处理处理完第三方再调用“办结”接口那条待办就从待办列表消失。我一般建议项目组优先选推送除非第三方系统连一个服务端接口都拿不出来。原因很实在拉取的定时任务出了问题你排查的是两个系统的时钟、网络、分页问题链路太长推送失败日志里一眼能看到哪一步断了。2.3 拿到文档先确认四件事不要一上来就把接口文档通读一遍E9的集成待办接口文档少则几十页多则上百页。我拿到文档先找四个问题的答案第一鉴权方式是什么。E9对外接口主流做法是appid加secret换token后续请求带token。如果文档里说“不用鉴权”你反而要警惕说明这是一个内网接口部署架构上会有额外要求。第二业务主键怎么传。E9靠什么识别“同一条待办”是你要传一个唯一标识还是E9自己生成这决定了你能不能安全地重复推送。没有业务主键的接口做幂等会非常痛苦。第三更新和撤销叫法是什么。有的文档里更新叫“修改待办”撤销叫“作废待办”办结叫“完成待办”。动词不同参数结构差不多但你不确认写代码时容易调错接口。第四流程id到底要不要。这里我要重点说后台常有人搜“泛微获取流程id”其实在集成待办场景里你需要区分“E9流程实例的requestid”和“第三方业务ID”。如果只是把外部待办展示在E9待办中心流程id不是必填如果你想从E9流程里同步待办到第三方系统那才需要真正拿到流程id。这一点我在第4章展开讲。前两件事决定你能不能打通后两件事决定你搭出来的东西会不会返工。3. 先换Token再调接口鉴权链路与最小可运行代码3.1 用curl验证Token接口路径以集成中心页面为准E9的对外接口鉴权常见做法是“客户端凭证模式”拿appid和secret换access_tokentoken在有效期内重复使用。不同E9版本的Token接口路径不完全一致你登录E9后台找到“集成中心”或“接口管理”页面上会显示接入地址。不要凭记忆手写路径直接复制页面上的地址最保险。先用curl验证能不能换到token这是最快排错的一步。接口路径形如/api/ec/dev/auth/applytoken但以你环境里页面展示的为准curl -s -X POST http://oa.example.com/api/ec/dev/auth/applytoken \ -H Content-Type: application/json; charsetutf-8 \ -d { appid: todo_center_app, secret: 你的secret, grantType: client_credentials }正常返回里会有access_token和expires_in两个关键字段expires_in告诉你有多少秒有效期。如果你的环境返回字段名不一样比如叫data.token或者result.accessToken以文档为准接口风格差异在后端框架里很常见。这部分最容易踩的坑有两个。第一个是secret抄漏了字符E9生成的secret往往带大小写字母混合复制到Linux终端时注意别被换行符截断。第二个是grantType写错有些版本不要求这个参数有些版本要求小写你先看文档里示例怎么写的。curl通了之后再拿这个token去调业务接口如果返回“token无效”多半是token没放进请求头或者放入的位置不对。3.2 Token有效期与客户端缓存Python示例生产环境不能每次都重新换tokenE9的Token接口同样有频率限制和性能开销。我一般写一个Token管理器缓存token在过期前一分钟自动刷新。这里有一个细节你拿到的expires_in如果是7200秒不要真的等到7200秒才刷新提前60秒刷新能避免边界情况下的401报错。import time import requests class E9TokenManager: def __init__(self, base_url, appid, secret): self.base_url base_url self.appid appid self.secret secret self.token None self.expire_at 0 def get_access_token(self): # 如果token还没有过期直接复用 if self.token and time.time() self.expire_at - 60: return self.token resp requests.post( f{self.base_url}/api/ec/dev/auth/applytoken, json{ appid: self.appid, secret: self.secret, grantType: client_credentials }, timeout5 ) resp.raise_for_status() data resp.json() expires_in int(data.get(expires_in, 7200)) self.token data.get(access_token) self.expire_at time.time() expires_in return self.token这套逻辑里get_access_token被重复调用时如果token还在有效期内不会发起网络请求直接返回内存里的token。expires_in取不到时默认按7200秒处理这是一个保守策略宁可多换一次也不要用一个已经失效的token去调正式接口。代码跑通后把token打出来看一次确认它不是空字符串。接着去调待办推送接口之前先准备一个简单的异常捕获请求失败时打印响应体。E9的接口返回错误时响应体里一般会有错误码和错误描述这两行信息比抓包还直接。4. 推送一条待办到待办中心请求结构、字段映射与状态变更4.1 创建待办最小请求体怎么组织拿到Token下一步是推送一条真实待办。以创建待办接口为例路径形如/api/ec/dev/todo/open实际以文档为准。最小请求体大概是这个结构curl -X POST http://oa.example.com/api/ec/dev/todo/open \ -H Content-Type: application/json; charsetutf-8 \ -H accesstoken: 上一步拿到的token \ -d { bizId: SRM20250120-001, title: 采购合同审批A类备件采购需评审, body: 申请部门设备部金额86,500元请于下班前完成审批。, url: http://srm.example.com/todo/detail?idSRM20250120-001, receiver: zhangsan, sourceSystem: SRM, todoType: approval, deadline: 2025-01-20 18:00:00 }这个请求体里的字段我按优先级拆开解释。bizId是第三方系统的业务主键用于幂等你重复推同一条bizId的待办E9应该视为同一件事而不是创建两条。receiver是接收人账号这里到底传登录名、工号还是用户ID不同E9版本有差异文档里会写明。最稳妥的做法是先用一个你知道的登录名试通再去研究用户ID映射。todoType是待办类型它决定这条记录出现在“待办”还是“消息”里。我遇到过项目把待办推成了站内信用户找不到待办就是这个字段漏了或者值不对。deadline用“yyyy-MM-dd HH:mm:ss”格式不要用带“T”和“Z”的ISO格式E9对时间字符串的解析比较传统。字段是否必填说明bizId必填第三方业务主键决定幂等与后续更新title必填待办标题建议能直接看出业务内容body选填正文详情支持简单文本url必填点击待办后跳转的第三方页面地址receiver必填接收人按文档要求传登录名或用户IDsourceSystem选填来源系统标识便于在列表里区分数据来源todoType建议必填待办类型影响展示位置deadline选填超时时间传了之后E9可以按到期时间排序4.2 状态变更更新、撤销、办结三个动词别混用创建待办只是第一步。第三方业务里标题变了要改审核人变了要换人流程撤回了要撤销审批通过了要转已办。这些操作对应三个接口参数差异不大关键在业务语义。更新接口一般传bizId加需要修改的字段未传的字段保持原值curl -X POST http://oa.example.com/api/ec/dev/todo/update \ -H Content-Type: application/json; charsetutf-8 \ -H accesstoken: 你的token \ -d { bizId: SRM20250120-001, title: 采购合同审批A类备件采购已追加预算, deadline: 2025-01-21 18:00:00 }撤销接口用于业务取消撤销后这条记录不应再出现在待办列表curl -X POST http://oa.example.com/api/ec/dev/todo/cancel \ -H Content-Type: application/json; charsetutf-8 \ -H accesstoken: 你的token \ -d {bizId: SRM20250120-001}办结接口用于审批完成调用后待办应从待办区移到已办区curl -X POST http://oa.example.com/api/ec/dev/todo/complete \ -H Content-Type: application/json; charsetutf-8 \ -H accesstoken: 你的token \ -d { bizId: SRM20250120-001, result: approved, opinion: 同意 }这三个状态变更接口我建议在联调阶段做成一个状态机来测创建后去查询列表确认待办出现办结后去查询列表确认待办消失且已办区出现撤销后再确认不会回弹。E9的待办中心页面有“集成待办”查询入口配合页面查询能直观看到每个动作的效果。4.3 流程id和requestid什么时候必须填从哪拿这是集成待办里最容易糊涂的地方。很多人在对接时纠结“泛微获取流程id”这个问题其实要先分清两个概念E9流程实例IDrequestid和第三方业务ID。如果第三方系统的待办只是“借用”E9的待办中心做展示和跳转那你不需要requestid只需保证bizId唯一就行。E9不关心你的业务数据从哪来它只是替你展示了一个入口。如果需求反过来你要把E9本身的流程待办同步到第三方系统这时候才需要拿到requestid。常见做法是在E9流程设计器里于流程节点事件或表单保存事件中写代码requestid会作为事件参数直接传进来把它写入一张中间表再给第三方系统调用。泛微E9实施手册里通常把这个过程放在“流程集成”章节而不是“统一集成待办中心”章节。还有一种场景你希望用户从第三方系统点进E9流程详情页去审批。这时你需要在推送待办时把E9流程实例ID和第三方业务ID做关联映射。我的建议不要在推送接口里临时去找requestid而是先各自落库推送时只传关联ID减少接口间的硬依赖。5. 避坑与排查5个高频翻车点按现象找原因5.1 推送接口返回成功待办中心却没有记录现象HTTP 200业务返回码也是成功但用户登录E9后待办列表空空如也。这个问题排在翻车榜第一位。原因有两类。第一类是接收人字段传错比如E9文档要求传用户ID你传了登录名系统找不到接收人请求被静默丢弃第二类是todoType或默认接收人配置不对导致数据进了消息列表而不是待办列表。解决先登录E9后台在“集成待办”或“对外接口日志”里查这条请求的处理结果。日志里如果显示“接收人不存在”去用户管理里确认账号状态。再用一个你确定存在的用户ID重推一次排除账号问题。如果日志显示成功但仍不显示检查todoType换成文档示例里的标准值再试。5.2 能取到Token业务接口却报无权限现象Token接口调用成功access_token也能拿到但调创建待办接口时返回“接口无权访问”或“应用未授权”。原因你在集成中心注册了应用但没有给这个应用分配“统一集成待办中心”相关接口的调用权限。泛微E9的接口权限是应用粒度的不是所有接口默认开放。解决去集成中心或接口管理里找到应用详情把待办中心相关的接口权限勾上保存后重新发布应用。注意重新授权后token可能变化重试时换一个新token。5.3 待办可见但点击跳转打不开业务页面现象E9待办列表能看到这条待办点击后页面一直转圈或者白屏。原因url字段传了内网地址比如http://localhost:8080或者http://192.168.x.xE9门户部署在外网或另一个网段访问不了。另一个常见原因是E9对跳转地址有可信域名限制未配置的域名会被拦截。解决url传完整公网可访问地址并在E9的“可信域名”或“安全设置”里加上跳转域名。手机端验证时还要确认域名证书是https且没有过期。我的习惯是联调第一天就测跳转不要等全部推完再测。5.4 重复待办和重复推送没有幂等现象同一个第三方业务ID被推送了两次E9待办列表出现两条标题一模一样的待办。原因推送逻辑没有对bizId做幂等处理或者调用方重试机制太粗暴失败一次就整体重跑。如果接口设计是“按bizId更新”重复推送不会新增如果设计是“无脑插入”就会重复。解决优先使用更新语义。推送前先调用查询接口判断bizId是否已存在存在则走更新不存在才走创建。更稳妥的做法是让E9侧对bizId建立唯一索引重复推送时返回错误码而不是插入新数据。这个要看现场接口实现能力但无论如何调用方必须记录推送状态和返回错误码。5.5 时间字段报错、字符集乱码现象推送时报日期格式错误或者标题里的中文变成乱码偶尔还有emoji导致整个请求失败。原因时间字段传了带时区的ISO字符串E9解析不了字符集不是UTF-8或者HTTP请求头里没标注charsetutf-8。某些版本的接口对表情符号支持也不完整。解决时间统一转成“yyyy-MM-dd HH:mm:ss”在代码里做好格式转换HTTP请求头固定带上Content-Type: application/json; charsetutf-8。如果你用Java的RestTemplate或HttpClient注意String编码不要用系统默认编码。另外有一点容易忽略E9和E10实施手册中接口路径和参数命名并不完全一致对照手册先确认版本别拿E10的示例直接复制到E9环境。6. 上线前自测用一条TEST待办把整条链路走通正式联调前我建议先按“最小闭环”做一次自测不要急着接全量数据。用时间成本最低的方式验证四个环节Token能拿到、待办能推送、列表能显示、跳转能打开。第一步推一条标题里带TEST标记的待办接收人选你自己。推送成功后到个人待办列表里看这条待办应该出现在待办区。第二步点开这条待办确认能跳转到第三方系统且页面能正常操作。第三步在第三方系统里完成审批动作调用办结接口回到E9刷新确认待办区消失、已办区出现。这个闭环里任何一个环节断了都不要急着继续推第二批。排查顺序是先看第三方调用日志确认请求发出、响应结果再看E9接口日志确认E9接收后的处理状态最后看用户端效果。泛微的后台日志里一般有请求ID或traceId前后端用同一个ID串起来省去很多沟通成本。我自己的习惯是留一个调试专用的测试账号和一条测试业务数据任何时候想验证环境推一条就能判断问题出在E9还是第三方。以前做SAP对接第一批发过去的待办全是“未读消息”而不是“待办”查了一下午才发现是todoType漏传。从那以后任何集成现场第一件事先推TEST待办确认展示位置再谈别的。另一个实用技巧是在第三方系统的推送程序里每次请求都把返回的完整报文写进日志。E9的接口返回可能包含错误码、错误描述、提示信息这些内容在你排查翻车时会告诉你准确方向。就算你在代码里已经做了异常捕获“日志里没有完整响应体”也会让排查时间翻倍。这套方法反复用下来集成待办中心这件事儿的玄学成分会越来越少剩下的都是能复现、能定位、能修复的确定问题。希望帮到你。本文还有配套的精品资源点击获取 泛微E9统一集成待办中心接口对接：推送、更新与办结实战
简介面向泛微E9协同办公平台二次开发及异构系统对接人员这份资料是统一集成待办中心的Webservice接口说明文档。文档以服务配置文件、方法定义、Map参数说明和SOAP请求XML示例为主线重点讲解receiveTodoRequestByMap接口的调用方式清晰列出syscode、flowid、requestname、pcurl、appurl、receivets等关键字段含义帮助开发者将不同系统的待办任务快速整合到统一待办中心避免重复开发与数据冲突。压缩包内共1个文件为PDF文档大小约1.6MB。目前已有4138人浏览学习。对于正在做泛微E9待办集成、需要梳理接口规范或排查对接参数问题的开发者这份文档可以直接对照使用省去查阅源码与逆向配置的时间。1. 泛微E9统一集成待办中心接口文档先搞清楚它解决什么问题做泛微E9集成的第一天最容易卡住的不是流程建模而是“统一集成待办中心接口文档”这几个字。第三方系统——不管是自研工单、SAP还是MES——想把待办推到OA里或者想让OA的待办回流到外部门户都要走这个中心。它解决的是“两个系统待办不互通”的问题核心动作只有三个推送、更新、办结。这篇文章写给两类人一类是刚接触E9对外接口的实施工程师想知道从哪下手另一类是已经在对接但被鉴权、流程id、已办回调折磨过的开发想找一份能照着排查的实战记录。2. 认清“统一集成待办中心”三种接入方式与四个必看的接口概念2.1 统一集成待办中心在E9里到底是什么E9的待办中心本质是一个“待办汇聚池”。泛微自己的流程待办天然在里面但你公司里的ERP审批、供应商协同、设备巡检工单并不会自动出现在这个池子里。统一集成待办中心就是E9对外开放的一套接口能力第三方系统按规范把待办数据喂进来E9负责渲染、去重、跳转和已办归档。我一般会把“集成待办”和“流程待办”分开看。流程待办是E9引擎产生的有requestid、有节点、有审批历史集成待办是外部系统塞进来的E9不关心你的业务逻辑只关心“给谁看、看什么、点哪跳转”。这个区别决定了你后续所有参数设计。很多项目翻车都是想用流程待办的概念去套集成待办结果字段对不上状态也推不动。从数据结构上说一条集成待办通常包含标题、正文、跳转URL、接收人、来源系统标识、业务主键、过期时间以及一个“待办类型”。这个“待办类型”决定了它显示在我的待办里还是站内信里也是新手最容易漏的字段。理解了这几样再去翻接口文档你会觉得文档里的请求参数每一行都能对上号。2.2 三种接入方式拉取、推送、混合怎么选拿到需求先不要着急调接口把接入方式定下来。E9对接第三方待办我常用的有拉取、推送、混合三种。接入方式谁主动适用场景实时性开发量主要坑拉取E9定时去第三方系统拉待办第三方系统不方便对外开放调用但能提供查询接口分钟级延迟第三方需要写分页查询接口分页游标、已拉取数据的去重推送第三方系统调用E9接口写入待办第三方有服务端能拿到E9的接口地址和凭证秒级第三方写推送逻辑幂等、重复待办、状态同步混合新增用推送已办用回写业务需要闭环待办推进来审批完再通知E9转已办秒级最高状态一致性、回调失败补偿拉取方式适合“E9只做展示”的场景E9不落业务数据但定时任务会消耗性能。推送方式是目前主流因为实时性好且第三方系统是业务源头推完后自己知道改状态。混合模式最贴近真实业务第三方工单审批推一条待办给审批人审批人在E9里点开跳回第三方处理处理完第三方再调用“办结”接口那条待办就从待办列表消失。我一般建议项目组优先选推送除非第三方系统连一个服务端接口都拿不出来。原因很实在拉取的定时任务出了问题你排查的是两个系统的时钟、网络、分页问题链路太长推送失败日志里一眼能看到哪一步断了。2.3 拿到文档先确认四件事不要一上来就把接口文档通读一遍E9的集成待办接口文档少则几十页多则上百页。我拿到文档先找四个问题的答案第一鉴权方式是什么。E9对外接口主流做法是appid加secret换token后续请求带token。如果文档里说“不用鉴权”你反而要警惕说明这是一个内网接口部署架构上会有额外要求。第二业务主键怎么传。E9靠什么识别“同一条待办”是你要传一个唯一标识还是E9自己生成这决定了你能不能安全地重复推送。没有业务主键的接口做幂等会非常痛苦。第三更新和撤销叫法是什么。有的文档里更新叫“修改待办”撤销叫“作废待办”办结叫“完成待办”。动词不同参数结构差不多但你不确认写代码时容易调错接口。第四流程id到底要不要。这里我要重点说后台常有人搜“泛微获取流程id”其实在集成待办场景里你需要区分“E9流程实例的requestid”和“第三方业务ID”。如果只是把外部待办展示在E9待办中心流程id不是必填如果你想从E9流程里同步待办到第三方系统那才需要真正拿到流程id。这一点我在第4章展开讲。前两件事决定你能不能打通后两件事决定你搭出来的东西会不会返工。3. 先换Token再调接口鉴权链路与最小可运行代码3.1 用curl验证Token接口路径以集成中心页面为准E9的对外接口鉴权常见做法是“客户端凭证模式”拿appid和secret换access_tokentoken在有效期内重复使用。不同E9版本的Token接口路径不完全一致你登录E9后台找到“集成中心”或“接口管理”页面上会显示接入地址。不要凭记忆手写路径直接复制页面上的地址最保险。先用curl验证能不能换到token这是最快排错的一步。接口路径形如/api/ec/dev/auth/applytoken但以你环境里页面展示的为准curl -s -X POST http://oa.example.com/api/ec/dev/auth/applytoken \ -H Content-Type: application/json; charsetutf-8 \ -d { appid: todo_center_app, secret: 你的secret, grantType: client_credentials }正常返回里会有access_token和expires_in两个关键字段expires_in告诉你有多少秒有效期。如果你的环境返回字段名不一样比如叫data.token或者result.accessToken以文档为准接口风格差异在后端框架里很常见。这部分最容易踩的坑有两个。第一个是secret抄漏了字符E9生成的secret往往带大小写字母混合复制到Linux终端时注意别被换行符截断。第二个是grantType写错有些版本不要求这个参数有些版本要求小写你先看文档里示例怎么写的。curl通了之后再拿这个token去调业务接口如果返回“token无效”多半是token没放进请求头或者放入的位置不对。3.2 Token有效期与客户端缓存Python示例生产环境不能每次都重新换tokenE9的Token接口同样有频率限制和性能开销。我一般写一个Token管理器缓存token在过期前一分钟自动刷新。这里有一个细节你拿到的expires_in如果是7200秒不要真的等到7200秒才刷新提前60秒刷新能避免边界情况下的401报错。import time import requests class E9TokenManager: def __init__(self, base_url, appid, secret): self.base_url base_url self.appid appid self.secret secret self.token None self.expire_at 0 def get_access_token(self): # 如果token还没有过期直接复用 if self.token and time.time() self.expire_at - 60: return self.token resp requests.post( f{self.base_url}/api/ec/dev/auth/applytoken, json{ appid: self.appid, secret: self.secret, grantType: client_credentials }, timeout5 ) resp.raise_for_status() data resp.json() expires_in int(data.get(expires_in, 7200)) self.token data.get(access_token) self.expire_at time.time() expires_in return self.token这套逻辑里get_access_token被重复调用时如果token还在有效期内不会发起网络请求直接返回内存里的token。expires_in取不到时默认按7200秒处理这是一个保守策略宁可多换一次也不要用一个已经失效的token去调正式接口。代码跑通后把token打出来看一次确认它不是空字符串。接着去调待办推送接口之前先准备一个简单的异常捕获请求失败时打印响应体。E9的接口返回错误时响应体里一般会有错误码和错误描述这两行信息比抓包还直接。4. 推送一条待办到待办中心请求结构、字段映射与状态变更4.1 创建待办最小请求体怎么组织拿到Token下一步是推送一条真实待办。以创建待办接口为例路径形如/api/ec/dev/todo/open实际以文档为准。最小请求体大概是这个结构curl -X POST http://oa.example.com/api/ec/dev/todo/open \ -H Content-Type: application/json; charsetutf-8 \ -H accesstoken: 上一步拿到的token \ -d { bizId: SRM20250120-001, title: 采购合同审批A类备件采购需评审, body: 申请部门设备部金额86,500元请于下班前完成审批。, url: http://srm.example.com/todo/detail?idSRM20250120-001, receiver: zhangsan, sourceSystem: SRM, todoType: approval, deadline: 2025-01-20 18:00:00 }这个请求体里的字段我按优先级拆开解释。bizId是第三方系统的业务主键用于幂等你重复推同一条bizId的待办E9应该视为同一件事而不是创建两条。receiver是接收人账号这里到底传登录名、工号还是用户ID不同E9版本有差异文档里会写明。最稳妥的做法是先用一个你知道的登录名试通再去研究用户ID映射。todoType是待办类型它决定这条记录出现在“待办”还是“消息”里。我遇到过项目把待办推成了站内信用户找不到待办就是这个字段漏了或者值不对。deadline用“yyyy-MM-dd HH:mm:ss”格式不要用带“T”和“Z”的ISO格式E9对时间字符串的解析比较传统。字段是否必填说明bizId必填第三方业务主键决定幂等与后续更新title必填待办标题建议能直接看出业务内容body选填正文详情支持简单文本url必填点击待办后跳转的第三方页面地址receiver必填接收人按文档要求传登录名或用户IDsourceSystem选填来源系统标识便于在列表里区分数据来源todoType建议必填待办类型影响展示位置deadline选填超时时间传了之后E9可以按到期时间排序4.2 状态变更更新、撤销、办结三个动词别混用创建待办只是第一步。第三方业务里标题变了要改审核人变了要换人流程撤回了要撤销审批通过了要转已办。这些操作对应三个接口参数差异不大关键在业务语义。更新接口一般传bizId加需要修改的字段未传的字段保持原值curl -X POST http://oa.example.com/api/ec/dev/todo/update \ -H Content-Type: application/json; charsetutf-8 \ -H accesstoken: 你的token \ -d { bizId: SRM20250120-001, title: 采购合同审批A类备件采购已追加预算, deadline: 2025-01-21 18:00:00 }撤销接口用于业务取消撤销后这条记录不应再出现在待办列表curl -X POST http://oa.example.com/api/ec/dev/todo/cancel \ -H Content-Type: application/json; charsetutf-8 \ -H accesstoken: 你的token \ -d {bizId: SRM20250120-001}办结接口用于审批完成调用后待办应从待办区移到已办区curl -X POST http://oa.example.com/api/ec/dev/todo/complete \ -H Content-Type: application/json; charsetutf-8 \ -H accesstoken: 你的token \ -d { bizId: SRM20250120-001, result: approved, opinion: 同意 }这三个状态变更接口我建议在联调阶段做成一个状态机来测创建后去查询列表确认待办出现办结后去查询列表确认待办消失且已办区出现撤销后再确认不会回弹。E9的待办中心页面有“集成待办”查询入口配合页面查询能直观看到每个动作的效果。4.3 流程id和requestid什么时候必须填从哪拿这是集成待办里最容易糊涂的地方。很多人在对接时纠结“泛微获取流程id”这个问题其实要先分清两个概念E9流程实例IDrequestid和第三方业务ID。如果第三方系统的待办只是“借用”E9的待办中心做展示和跳转那你不需要requestid只需保证bizId唯一就行。E9不关心你的业务数据从哪来它只是替你展示了一个入口。如果需求反过来你要把E9本身的流程待办同步到第三方系统这时候才需要拿到requestid。常见做法是在E9流程设计器里于流程节点事件或表单保存事件中写代码requestid会作为事件参数直接传进来把它写入一张中间表再给第三方系统调用。泛微E9实施手册里通常把这个过程放在“流程集成”章节而不是“统一集成待办中心”章节。还有一种场景你希望用户从第三方系统点进E9流程详情页去审批。这时你需要在推送待办时把E9流程实例ID和第三方业务ID做关联映射。我的建议不要在推送接口里临时去找requestid而是先各自落库推送时只传关联ID减少接口间的硬依赖。5. 避坑与排查5个高频翻车点按现象找原因5.1 推送接口返回成功待办中心却没有记录现象HTTP 200业务返回码也是成功但用户登录E9后待办列表空空如也。这个问题排在翻车榜第一位。原因有两类。第一类是接收人字段传错比如E9文档要求传用户ID你传了登录名系统找不到接收人请求被静默丢弃第二类是todoType或默认接收人配置不对导致数据进了消息列表而不是待办列表。解决先登录E9后台在“集成待办”或“对外接口日志”里查这条请求的处理结果。日志里如果显示“接收人不存在”去用户管理里确认账号状态。再用一个你确定存在的用户ID重推一次排除账号问题。如果日志显示成功但仍不显示检查todoType换成文档示例里的标准值再试。5.2 能取到Token业务接口却报无权限现象Token接口调用成功access_token也能拿到但调创建待办接口时返回“接口无权访问”或“应用未授权”。原因你在集成中心注册了应用但没有给这个应用分配“统一集成待办中心”相关接口的调用权限。泛微E9的接口权限是应用粒度的不是所有接口默认开放。解决去集成中心或接口管理里找到应用详情把待办中心相关的接口权限勾上保存后重新发布应用。注意重新授权后token可能变化重试时换一个新token。5.3 待办可见但点击跳转打不开业务页面现象E9待办列表能看到这条待办点击后页面一直转圈或者白屏。原因url字段传了内网地址比如http://localhost:8080或者http://192.168.x.xE9门户部署在外网或另一个网段访问不了。另一个常见原因是E9对跳转地址有可信域名限制未配置的域名会被拦截。解决url传完整公网可访问地址并在E9的“可信域名”或“安全设置”里加上跳转域名。手机端验证时还要确认域名证书是https且没有过期。我的习惯是联调第一天就测跳转不要等全部推完再测。5.4 重复待办和重复推送没有幂等现象同一个第三方业务ID被推送了两次E9待办列表出现两条标题一模一样的待办。原因推送逻辑没有对bizId做幂等处理或者调用方重试机制太粗暴失败一次就整体重跑。如果接口设计是“按bizId更新”重复推送不会新增如果设计是“无脑插入”就会重复。解决优先使用更新语义。推送前先调用查询接口判断bizId是否已存在存在则走更新不存在才走创建。更稳妥的做法是让E9侧对bizId建立唯一索引重复推送时返回错误码而不是插入新数据。这个要看现场接口实现能力但无论如何调用方必须记录推送状态和返回错误码。5.5 时间字段报错、字符集乱码现象推送时报日期格式错误或者标题里的中文变成乱码偶尔还有emoji导致整个请求失败。原因时间字段传了带时区的ISO字符串E9解析不了字符集不是UTF-8或者HTTP请求头里没标注charsetutf-8。某些版本的接口对表情符号支持也不完整。解决时间统一转成“yyyy-MM-dd HH:mm:ss”在代码里做好格式转换HTTP请求头固定带上Content-Type: application/json; charsetutf-8。如果你用Java的RestTemplate或HttpClient注意String编码不要用系统默认编码。另外有一点容易忽略E9和E10实施手册中接口路径和参数命名并不完全一致对照手册先确认版本别拿E10的示例直接复制到E9环境。6. 上线前自测用一条TEST待办把整条链路走通正式联调前我建议先按“最小闭环”做一次自测不要急着接全量数据。用时间成本最低的方式验证四个环节Token能拿到、待办能推送、列表能显示、跳转能打开。第一步推一条标题里带TEST标记的待办接收人选你自己。推送成功后到个人待办列表里看这条待办应该出现在待办区。第二步点开这条待办确认能跳转到第三方系统且页面能正常操作。第三步在第三方系统里完成审批动作调用办结接口回到E9刷新确认待办区消失、已办区出现。这个闭环里任何一个环节断了都不要急着继续推第二批。排查顺序是先看第三方调用日志确认请求发出、响应结果再看E9接口日志确认E9接收后的处理状态最后看用户端效果。泛微的后台日志里一般有请求ID或traceId前后端用同一个ID串起来省去很多沟通成本。我自己的习惯是留一个调试专用的测试账号和一条测试业务数据任何时候想验证环境推一条就能判断问题出在E9还是第三方。以前做SAP对接第一批发过去的待办全是“未读消息”而不是“待办”查了一下午才发现是todoType漏传。从那以后任何集成现场第一件事先推TEST待办确认展示位置再谈别的。另一个实用技巧是在第三方系统的推送程序里每次请求都把返回的完整报文写进日志。E9的接口返回可能包含错误码、错误描述、提示信息这些内容在你排查翻车时会告诉你准确方向。就算你在代码里已经做了异常捕获“日志里没有完整响应体”也会让排查时间翻倍。这套方法反复用下来集成待办中心这件事儿的玄学成分会越来越少剩下的都是能复现、能定位、能修复的确定问题。希望帮到你。本文还有配套的精品资源点击获取