简介：面向泛微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_token，token在有效期内重复使用。不同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; charset=utf-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示例
生产环境不能每次都重新换token，E9的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" }, timeout=5 ) 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; charset=utf-8" \ -H "accesstoken: 上一步拿到的token" \ -d '{ "bizId": "SRM20250120-001", "title": "采购合同审批：A类备件采购（需评审）", "body": "申请部门：设备部；金额：86,500元；请于下班前完成审批。", "url": "http://srm.example.com/todo/detail?id=SRM20250120-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 | 必填 | 接收人，按文档要求传登录名或用户ID |
| sourceSystem | 选填 | 来源系统标识，便于在列表里区分数据来源 |
| todoType | 建议必填 | 待办类型，影响展示位置 |
| deadline | 选填 | 超时时间，传了之后E9可以按到期时间排序 |
4.2 状态变更：更新、撤销、办结，三个动词别混用
创建待办只是第一步。第三方业务里，标题变了要改，审核人变了要换人，流程撤回了要撤销，审批通过了要转已办。这些操作对应三个接口，参数差异不大，关键在业务语义。
更新接口一般传bizId加需要修改的字段，未传的字段保持原值：
curl -X POST "http://oa.example.com/api/ec/dev/todo/update" \ -H "Content-Type: application/json; charset=utf-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; charset=utf-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; charset=utf-8" \ -H "accesstoken: 你的token" \ -d '{ "bizId": "SRM20250120-001", "result": "approved", "opinion": "同意" }'这三个状态变更接口，我建议在联调阶段做成一个状态机来测：创建后去查询列表，确认待办出现；办结后去查询列表，确认待办消失且已办区出现；撤销后再确认不会回弹。E9的待办中心页面有“集成待办”查询入口，配合页面查询，能直观看到每个动作的效果。
4.3 流程id和requestid：什么时候必须填，从哪拿
这是集成待办里最容易糊涂的地方。很多人在对接时纠结“泛微获取流程id”这个问题，其实要先分清两个概念：E9流程实例ID（requestid）和第三方业务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.x，E9门户部署在外网或另一个网段，访问不了。另一个常见原因是E9对跳转地址有可信域名限制，未配置的域名会被拦截。
解决：url传完整公网可访问地址，并在E9的“可信域名”或“安全设置”里加上跳转域名。手机端验证时，还要确认域名证书是https且没有过期。我的习惯是联调第一天就测跳转，不要等全部推完再测。
5.4 重复待办和重复推送：没有幂等
现象：同一个第三方业务ID被推送了两次，E9待办列表出现两条标题一模一样的待办。
原因：推送逻辑没有对bizId做幂等处理，或者调用方重试机制太粗暴，失败一次就整体重跑。如果接口设计是“按bizId更新”，重复推送不会新增；如果设计是“无脑插入”，就会重复。
解决：优先使用更新语义。推送前先调用查询接口判断bizId是否已存在，存在则走更新，不存在才走创建。更稳妥的做法是让E9侧对bizId建立唯一索引，重复推送时返回错误码而不是插入新数据。这个要看现场接口实现能力，但无论如何，调用方必须记录推送状态和返回错误码。
5.5 时间字段报错、字符集乱码
现象：推送时报日期格式错误，或者标题里的中文变成乱码，偶尔还有emoji导致整个请求失败。
原因：时间字段传了带时区的ISO字符串，E9解析不了；字符集不是UTF-8，或者HTTP请求头里没标注charset=utf-8。某些版本的接口对表情符号支持也不完整。
解决：时间统一转成“yyyy-MM-dd HH:mm:ss”，在代码里做好格式转换；HTTP请求头固定带上Content-Type: application/json; charset=utf-8。如果你用Java的RestTemplate或HttpClient，注意String编码，不要用系统默认编码。另外有一点容易忽略：E9和E10实施手册中，接口路径和参数命名并不完全一致，对照手册先确认版本，别拿E10的示例直接复制到E9环境。
6. 上线前自测：用一条TEST待办把整条链路走通
正式联调前，我建议先按“最小闭环”做一次自测，不要急着接全量数据。用时间成本最低的方式验证四个环节：Token能拿到、待办能推送、列表能显示、跳转能打开。
第一步，推一条标题里带TEST标记的待办，接收人选你自己。推送成功后到个人待办列表里看，这条待办应该出现在待办区。第二步，点开这条待办，确认能跳转到第三方系统，且页面能正常操作。第三步，在第三方系统里完成审批动作，调用办结接口，回到E9刷新，确认待办区消失、已办区出现。
这个闭环里任何一个环节断了，都不要急着继续推第二批。排查顺序是：先看第三方调用日志，确认请求发出、响应结果；再看E9接口日志，确认E9接收后的处理状态；最后看用户端效果。泛微的后台日志里一般有请求ID或traceId，前后端用同一个ID串起来，省去很多沟通成本。
我自己的习惯是留一个调试专用的测试账号和一条测试业务数据，任何时候想验证环境，推一条就能判断问题出在E9还是第三方。以前做SAP对接，第一批发过去的待办全是“未读消息”而不是“待办”，查了一下午才发现是todoType漏传。从那以后，任何集成现场第一件事先推TEST待办，确认展示位置，再谈别的。
另一个实用技巧是在第三方系统的推送程序里，每次请求都把返回的完整报文写进日志。E9的接口返回可能包含错误码、错误描述、提示信息，这些内容在你排查翻车时会告诉你准确方向。就算你在代码里已经做了异常捕获，“日志里没有完整响应体”也会让排查时间翻倍。这套方法反复用下来，集成待办中心这件事儿的玄学成分会越来越少，剩下的都是能复现、能定位、能修复的确定问题。希望帮到你。
本文还有配套的精品资源，点击获取
