1. 寒暄篇：为什么这一篇专门聊E9的“接口凭证”
做了七年泛微OA实施，前前后后对接过ERP、CRM、合同系统、MES、SRM，我越来越觉得，泛微OA-E9与第三方系统集成开发这件事，难度不在写代码，而在“把两边的人对齐”。E9这一代产品和E8最大的区别就是接口能力又重构过一轮，很多老伙伴还在按E8的思路写WebService，过来一调E9的Restful接口，直接懵了。
这个系列我一直在记录真实项目里那些“查文档查不到、问售后又得等半天”的细节。第八篇我准备集中把集成开发的整个链路——从拿凭证、调token、传单据、发起流程，再到等回调、查审批结果、处理超时和幂等——串成一个可以照抄的实战样本，把这些年在E9上踩过的坑一次性讲透。
如果你正在做以下任何一件事：把第三方系统的单据推进E9发起审批流、把E9审批结果回传给业务系统、做组织架构单向同步、或者只是想搞清楚E9开放接口到底怎么玩，那这篇应该能帮你省下两三个晚上的排查时间。我尽量用“换位成第三方系统开发人员”的角度来写，你不用是泛微专家，只要懂HTTP请求和JSON，就能跟着把这套链路搭起来。
2. 整体设计思路：先用一张“接口全景图”定位自己的集成类型
2.1 三种主流集成模式，先对号入座
和E9做对接，首先别急着写代码。你要先分清楚自己属于哪种集成模式，因为模式决定了你后面用哪个接口、走什么鉴权、数据流方向是什么。我一般在项目kickoff时就让双方确认这张表：
| 集成模式 | 典型场景 | E9侧主要接口 | 数据流向 |
|---|---|---|---|
| 流程集成 | 第三方单据发起OA审批，或OA审批结果回写 | 流程启动、待办发送、审批动作回调 | 第三方→E9→第三方 |
| 数据集成 | 组织架构、人员、客户档案等主数据同步 | 数据字典、组织机构增删改查接口 | 业务系统→E9，或E9→业务系统 |
| 消息集成 | OA待办、通知推送到钉钉/企微/自研App | 消息推送接口、事件回调 | E9→第三方 |
我个人的经验是，绝大多数企业做的所谓“集成开发”，本质都是流程集成外加一部分组织同步。所以这一篇我重点把流程集成讲透，组织同步会作为一个延伸章节提关键点，消息集成涉及的复杂度不高，但坑不少，放在常见问题里讲。
这里有个很容易被忽略的设计决策：谁为主，谁为从？我见过太多项目，一开始说好“业务系统发起，OA只负责审批”，结果做到一半，业务方又要求OA能主动也能发起，双向漫游，最后两边都是主，数据冲突得一塌糊涂。建议尽早定下来一条原则——数据源唯一，发起方唯一，审批结果以OA为准回传。后面所有设计都围着这条原则走。
2.2 E9的Restful接口体系，和E8/Weaver老接口的本质区别
E9时代的接口体系已经全面转向Restful风格，相比E8时代的WorkflowService、HrmService那一堆SOAP WebService，最核心的几个变化我列在这儿：
- 鉴权方式变了：不再是占位符登录或数字证书SOAP头，而是基于AppId + SecretKey换取AccessToken。
- 接口路径更统一：基本上以
/api/...或/ecode/...开头，参数和返回都走JSON。 - 返回值标准化：错误信息不再是一句“Sorry，系统错误”，而是一个标准错误码结构体，方便程序侧直接按错误码做分支处理。
- 支持access_token接口级别鉴权：你可以控制每个第三方应用能访问哪些接口，粒度比E8细得多。
知道这些差异，你就不用走弯路了。我见过有同事拿着E8的js包直接塞进E9项目里调，调了半天报404，其实根本不是路径问题，是整个接口体系都换了。
顺带说一个选型经验：如果你们的E9上了Ecode平台，优先看Ecode平台提供的开放接口文档；如果没上Ecode，那就用系统自带的标准Restful接口。两套东西在鉴权和返回格式上略微不同，但设计思想是一样的。千万别混着用——同一个集成，要么全走Ecode，要么全走标准接口，混用会把运维的同学搞疯。
3. 核心前置工作：凭证配置与Token换取，这是所有集成的第一步
3.1 在E9后台把“第三方应用”的真实位置找到并配好
先说一个很多新手会卡住的问题：E9后台到底在哪里配置第三方应用的AppId和SecretKey？
我以泛微E9的常见版本为例（9.0.2及以上），路径大致在：后端应用中心→集成中心→接口管理→第三方应用（不同版本菜单名可能略有差异，有的叫“应用注册”，有的叫“开放平台”）。
点进去之后，你要做的是新建一个应用，填应用名称、应用描述、回调地址（如果用到事件回调就必须填）。提交后系统会生成一对AppId和SecretKey，这个SecretKey只展示一次，建议复制到自己的密码管理器里，别截图发群里——我就亲眼见过有人把SecretKey直接发到企业微信群里，后面整改时后台重置，所有对接方一起断线，惨烈。
另外有个细节：每个第三方系统建议单独注册一个应用，不要多个系统共用一个AppId。原因是排查问题时你需要知道是哪个系统在调、调了哪些接口、频率多少，共用一个AppId你只能看到一个笼统的调用总量，出了问题连是哪边半夜在跑批都分不清。
3.2 Token获取的正确姿势：缓存起来，别每次都去换
E9的接口鉴权和大多数开放平台一样，拿到了AppId和SecretKey之后，你首先要调用一个token接口换取访问令牌。调用方式大致是这样的（以Java为例，第三方用别的语言思路一样）：
public class E9TokenManager { private static String accessToken; private static long expireTime = 0; public static synchronized String getToken() { // 如果还没过期，直接返回缓存的token if (accessToken != null && System.currentTimeMillis() < expireTime) { return accessToken; } // 调用E9的token接口 String url = "https://oa.example.com:8443/api/ecode/token"; Map<String, String> params = new HashMap<>(); params.put("appId", "your_app_id"); params.put("secretKey", "your_secret_key"); params.put("timestamp", String.valueOf(System.currentTimeMillis() / 1000)); // 注：具体参数名以实际接口文档为准，这里用大家最熟悉的命名方式演示 String response = HttpUtil.postForm(url, params); JSONObject json = JSONObject.parseObject(response); if (json.getIntValue("code") == 1) { accessToken = json.getString("access_token"); // 一般token有效期是7200秒，我们提前5分钟过期 expireTime = System.currentTimeMillis() + (7200 - 300) * 1000; return accessToken; } throw new RuntimeException("获取E9 token失败：" + response); } }注意几点：
- 一定做本地缓存。别每次请求都去换token，你换一次就多一次网络开销，而且E9端对token接口一般有频率限制，高频调用会被限流。
- 提前几分钟过期。我习惯在有效期基础上减掉5分钟，这样哪怕本地时钟和OA服务器时钟有个几十秒偏差，也不会出现“刚拿到就过期”的尴尬。
- 时钟偏差问题是真实存在的。我遇到过客户E9的服务器时间比北京时间快了3分钟，第三方应用拿服务器时间戳去换token，E9直接判定时间戳无效，排查了整整半天。后来统一约定：所有时间戳以E9服务器时间为准，通过一个简单的时间接口做校准，或者干脆在运维侧彻底修正服务器时间。
3.3 接口调用的统一封装：请求头与错误码处理
拿到token之后，所有业务接口调用都要在请求头里带上它。我封装了一个简单的客户端工具，核心就两点：自动在Header里塞token，统一解析返回结构。
public class E9ApiClient { private static final String BASE_URL = "https://oa.example.com:8443"; public static JSONObject post(String path, JSONObject body) { String url = BASE_URL + path; String token = E9TokenManager.getToken(); // 添加请求头：Authorization（有的版本是access_token，以文档为准） Map<String, String> headers = new HashMap<>(); headers.put("Authorization", "Bearer " + token); // 发送POST请求 String response = HttpUtil.postJson(url, headers, body.toJSONString()); JSONObject result = JSONObject.parseObject(response); // 统一处理错误码，比如token失效时自动重试一次 if (result.getIntValue("code") == 401 || "token_expired".equals(result.getString("msg"))) { E9TokenManager.forceRefresh(); return post(path, body); } return result; } }这里有个很实用的技巧：token失效时自动重试。E9的token在极端情况下会被后台重置（比如管理员手动踢人），你如果不做重试，业务系统里就会时不时冒出一堆鉴权失败报警。做好自动重试之后，这种偶发问题一次都不用人工介入。
还有一点关于HTTP端口和SSL证书：E9默认HTTPS端口通常是8443，但很多企业私有化部署会改端口。还有的人会用自签名证书，第三方系统调的时候报SSL证书错误。我的做法是：让网络组把E9接口域名统一走反向代理出去，用正式域名和正式证书。不然你调接口前还得先解决Java的信任库问题，完全是浪费时间。
4. 实战核心环节：从第三方系统发起流程审批的完整链路
4.1 场景设定：合同系统发起“合同审批”流程到E9
为了让这一章不打空炮，我选一个最典型的场景：自研合同管理系统发起一份合同审批，推到E9走审批流，审批结束后把结果回传给合同系统。
这个场景几乎是每家企业做E9集成时都会遇到的，它同时覆盖了写数据、读数据、回调三个维度，非常适合当模板用。整体数据链路是这样的：
合同系统 →（构造表单JSON）→ E9流程启动接口 → 生成流程实例 → 审批人处理 → E9事件回调 → 合同系统收到审批结果你只需要关注三件事：发起时怎么把数据写进去、发起后怎么跟踪进度、结束时怎么拿到结果。这三件事串起来，整个链路就通了。
4.2 步骤一：发起流程前，先搞清“表单字段”是怎么映射的
最容易出错的地方，就是你根本不知道E9表单里的字段叫什么名字。我们开发人员习惯用JSON的字段名，但E9表单设计器里的字段是“表单HTML控件名”，长得完全不像数据库字段名。
我踩过一次大坑：合同系统那边传来contractAmount，我照猫画虎在E9流程启动接口里传了contractAmount，结果E9返回“参数错误”，过了好久才发现E9表单里那个金额控件的字段名是jine，拼音缩写。从那以后，每次做集成前我都要求甲方把“表单字段对照表”先做出来，表单上有哪些字段、字段名是什么、类型是什么、必填还是选填，一列一列写清楚。
表单映射表大概长这样：
| 业务含义 | 合同系统字段 | E9表单控件名 | 类型 | 必填 |
|---|---|---|---|---|
| 合同编号 | contractNo | htbh | 文本框 | 是 |
| 合同金额 | amount | jine | 数字 | 是 |
| 供应商名称 | supplier | gysmc | 文本框 | 是 |
| 合同正文附件 | attachmentUrl | fujian | 附件控件 | 否 |
这张表出来之后，代码里做字段映射就非常简单了：第三方系统的JSON字段名和E9表单控件名，在Service层做一个Map映射，别在JSP或者前端做，所有字段映射只发生在后端，出问题方便审计。
4.3 步骤二：调用流程启动接口，构造完整的请求载荷
E9的流程启动接口，通常传参结构包括：流程模板编码、发起人、表单数据、以及可选的节点处理人。我给出一个经过实战调通的请求体示例（脱敏处理过）：
{ "workflowCode": "HTSP", "creator": "wangxiaoming", "requestName": "采购合同审批-合同编号HT2025001", "formData": { "htbh": "HT2025001", "jine": 125000.50, "gysmc": "某某科技股份有限公司", "fujian": "http://contractsystem.local/files/ht2025001.pdf" } }各字段的含义大概是这样：
workflowCode：你在E9流程建模器里设置的流程编码，不是流程名称。找流程编码时看流程属性，别用中文名去调。creator：流程发起人，必须是E9里存在的有效账号，一般是单据的提交人，代码里用登录工号映射，比如wangxiaoming。requestName：流程标题。这个很重要，因为审批人打开待办时第一眼看到的就是这个标题，建议把关键业务信息拼进去，别只写“审批”。formData：表单数据，key就是前面说的控件名。
发送请求之后，E9返回的结果里会带上一个requestId（流程实例ID），这个ID是后续查审批状态和关联回调的关键，一定要持久化保存下来，最好直接存到合同系统那张单据表里。
4.4 步骤三：审批结果怎么拿？轮询不如回调
流程发给审批人之后，接下来怎么知道审批最终“通过”还是“驳回”？
第一版我做过轮询：合同系统每隔5分钟调一次E9的流程状态查询接口，判断流程实例是否结束。后来被生产环境教做人了——几百个合同一起审批时，轮询的请求量和接口压力都不小；更重要的是审批结果有时间差，合同系统显示的还是“审批中”，领导那边早就批完了。
所以正确做法是回调。E9后台配置好回调地址之后，当流程实例走到“流程结束”这个节点时，E9会往你配置的URL推送一条消息，内容包括requestId、审批结果、审批意见、处理时间等。你只需要做两件事：
- 在E9的第三方应用配置里把回调地址填好，比如
https://contractsystem.example.com/api/e9/callback。 - 在合同系统里写一个回调接收接口，收到消息后核对requestId，更新单据状态。
回调的重要经验有三条：
- 回调要做验签。回调地址暴露在公网的话，任何人都可能往你这里POST假消息，至少要做签名校验或IP白名单。E9一般支持配置一个回调密钥，你在接收端校验一下。
- 回调要支持幂等。同一个审批结果，E9可能会因为网络重试发多次。你的接收接口不能一收到回调就把单据状态改成“已通过”，你得先用requestId查一下，如果已经是最终状态就直接忽略。
- 回调接收接口要快速应答。E9发送回调时通常会等待你的HTTP响应，如果你处理太久，E9可能超时重试。所以接口内尽量只做收消息、落库、异步处理，别在接口里同步调用一堆外部服务。
4.5 步骤四：中途被驳回或转办，如何感知业务变化
很多人以为只要盯住“流程结束”这个节点就够了，其实还有个常见需求：流程被驳回时，最好能通知合同系统改单重推。
E9的驳回分为“驳回到发起人”和“驳回到上一步”两种情况。如果驳回到发起人，流程实例并没有结束，它处于“等待发起人重新提交”的状态，你的流程状态查询接口会看到状态码是revoked而不是end。产品经理如果没提前约定好这个语义，合同系统里就会出现“状态未知”的脏数据，用户反馈“我的合同到底批没批”，非常尴尬。
我的建议是：在集成设计阶段就定义好三档状态：
| 业务状态 | E9流程状态 | 合同系统动作 |
|---|---|---|
| 审批中 | 运行中 | 展示“审批中” |
| 已通过 | 流程已结束且审批结果为通过 | 展示“通过”，允许后续操作 |
| 已驳回 | 流程被驳回到发起人，或驳回后流程终止 | 展示“已驳回”，并提供“编辑后重新提交”入口 |
如果产品上允许“驳回后重新提交”，你还要处理一个问题：同一份合同重新提交时，是发起一个新流程实例，还是继续原来的流程实例？我倾向于重新发起一个新流程实例，然后把旧流程实例在合同系统里标记为“已作废”，这样整个审批链路清晰，不会出现多个实例混在一个业务单据下。
5. 数据同步场景延伸：组织架构对接的三种玩法与避坑
5.1 从业务系统单向同步到E9，还是反向拉取？
集成做到后期，大家就会发现流程集成的背后一定躲着组织架构同步。合同系统要发起审批，发起人必须是E9有效账号，那合同系统的一个新员工怎么成为E9的合法用户？答案是需要做组织同步。
大多数企业选择的方案是：以HR系统为源，向E9单向同步。E9提供了一套组织机构的外部接口，第三方可以调用它来创建部门、新增用户、更新用户状态、禁用离职人员。这里我提醒一句：E9的接口做增量更新没问题，但部门上下级关系的调整，用接口做很容易出错，尤其是把A部门整体挪到B部门下面这种操作，E9内部还会联动处理人员归属。
我见过最稳的方案是：部门结构变更这种低频操作走后台手工调整，用户增删改这种高频操作走接口同步。别想着做一个全自动化的大而全同步工具，维护成本远高于收益。
5.2 用户同步接口里最容易忽略的字段
用户同步接口涉及的字段挺多，但大多数都不是“改名字”那么简单：
- 登录名：一般用工号，务必保证唯一，E9里如果重复会直接冲突。
- 密码策略：第三方建的用户如果没有设置初始密码，用户首次登录OA会卡在“密码不对”上。实际项目中我们一般让HR系统传一个初始密码过来，或者约定一个统一的初始密码并强制首次修改。
- 状态字段：离职人员不是“删掉”，而是“禁用”或者“离职”。直接删除用户会导致既往流程实例里的人员关联信息损坏，禁止随意删。
- 手机号和邮箱：这是E9做短信和邮件通知的基础。你不同步这两个字段，后面流程待办通知根本发不出去，用户天天抱怨收不到消息。
5.3 组织同步的失败重试机制：别把错误数据留给OA
做同步时，最大的风险不是同步失败，而是同步失败后的脏数据。E9的组织机构接口对脏数据容忍度很低，比如你同步一个没有部门编码的用户过去，它会直接报错，这个用户就留在系统外了。
我的做法是搭一个“同步任务重试三步走”：
- 单条失败不入库，记录到一个同步错误表里，包括请求报文和错误信息。
- 每5分钟重试一次，重试3次都失败就转人工。
- 同步错误表提供一个后台管理页面，管理员可以单独点“重跑”按钮，把这个用户重新同步一遍。
这套机制几乎是集成开发里的标配，我建议你不管做流程集成还是数据集成，都尽早把“错误记录+重试+人工介入”这套底座建好，不然后面每次出问题都要去翻OA后台日志，效率太低。
6. 常见问题与排查技巧实录：这些坑我每个都踩过
6.1 问题速查表：从现象直接定位根因
把这几年的问题收集到一起，整理出下面这张表，你以后遇到类似问题直接对着查：
| 现象 | 最可能的原因 | 排查方向 |
|---|---|---|
| 调用token接口返回错误 | AppId或SecretKey写错，或时钟偏差过大 | 核对应用配置，对比服务器时间 |
| token无效或过期 | token缓存逻辑错误，或服务端重置了SecretKey | 查看token过期时间，检查缓存刷新逻辑 |
| 流程启动返回“参数错误” | 表单控件名和实际不一致 | 对照表单字段映射表逐个核对 |
| 流程启动了但审批人看不到待办 | creator不是有效E9账号，或流程模板未配置审批节点 | 检查creator对应人员是否存在、流程是否带出处理人 |
| 回调没收到 | 回调地址不通、E9后台没配置、或回调被防火墙拦截 | 先测回调地址连通性，再查E9接口日志 |
| 回调收到但数据对不上 | requestId未持久化或关联错误 | 检查合同系统单据表和requestId的关联逻辑 |
| 表单附件打不开 | 附件地址是内网地址，审批人在公网访问不了 | 附件地址统一走文件服务或外网映射 |
| 审批结束后合同系统状态未更新 | 回调处理异常或幂等逻辑跳过了更新 | 看回调日志，看单据状态更新代码 |
6.2 排查工具与日志方法：怎么快速定位是E9的问题还是自己的问题
集成联调阶段，最让人头疼的是两边互相甩锅。我常用的定位策略是“抓包三看”：
- 一看请求报文：是不是该传的参数没传、格式对不对。用Postman先手动调通，再让代码走一遍。
- 二看E9侧日志：E9的日志一般在
/home/weaver/ecology/log下，接口调用有记录，能看到它收到你的请求后发生了什么。关键是E9日志能看到接口调用方IP，你能判断出到底是请求没到E9，还是到了但被拦截。 - 三看返回报文：E9的报错信息虽然没有特别友好，但code字段是有规律的。通常
401是鉴权问题、404是接口路径问题、500才是真的服务器内部错误。
我在本地调试时还习惯用ngrok或者内网穿透工具把本地接口暴露给E9回调，这样开发阶段就能实时收到回调并调试代码，不用每次改代码都重新部署到测试服务器。不过要注意，如果公司有安全要求，建议只在联调环境用，生产不搞这套。
6.3 接口性能优化：大数据量同步怎么避免把OA拉垮
最后说一下性能问题。做组织同步或大批量单据推送时，很多人上来就搞一个for循环，一次性把几百条数据逐条调E9接口。E9本身又不是设计来承受高频调用的，几千条数据会把OA的数据库连接池直接打满，导致正常用户上OA都卡。
我摸索出来的稳妥节奏是：
- 批量接口优先：E9同一个业务域一般会提供批量创建/更新接口，比如批量建用户、批量提交表单。优先用批量，性能好很多。
- 没有批量接口时，限速串行：每条之间至少间隔200毫秒，一批100条大概耗时20秒，这个速度大部分E9环境都能扛住。
- 并发度绝对不要超过3：我见过有人写个并发5的线程池去同步，结果E9直接把他的IP限流了。你要是真着急，并发压到3，跑完再说。
还有一个容易被忽略的点：凡涉及大批量数据推送，尽量白天业务低峰期跑。虽然听起来像废话，但真有人把组织同步设在工作日上午9点自动跑批，结果整个OA卡了半小时，全公司都在骂。我现在都习惯把同步时间默认设到晚上10点以后，省心。
7. 一些经验沉淀与进阶建议（这段是写给长期维护的人看的）
走到这儿，一个完整的“第三方系统发起E9流程审批、审批结果回传”的闭环已经打通了，组织同步的常用玩法也算有了眉目。不过项目上线只是开始，真正的考验是后面几个月。
我在实际项目里学到的最大教训是：集成接口的维护成本远高于开发成本。上线那一刻大家都觉得搞定了，但半年后某个字段变了、某个流程模板被管理员改了、回调地址被防火墙策略误伤，都会让集成悄悄失效。所以从上线的第一天起，就要把监控和可观测性做进去。
具体来讲，我自己现在接的每个E9集成项目都会要求加三样东西：
- 调用流水日志：每个接口请求和响应都要有完整日志，至少保留30天。这个日志平时没人在意，一旦出问题就是唯一线索。
- 定时健康检查：用一个简单的定时任务，每隔几分钟调一次E9的token接口和业务流程状态接口，如果连续几次失败就告警。这样E9出问题时你不用等用户在群里报“OA又不通”。
- 自动化测试脚本：把“发起流程-查询状态-接收回调”这条主链路写成一个可重复跑的测试脚本，每次OA升级、接口调整后都能自动验证一遍。
补充一句关于对接文档的建议：签字确认的接口文档一定要落到纸面上。我见过太多了，口头说得好好的“字段不变”，结果过了三个月对方改了一个字段名，导致所有对接方一起崩。把字段对照表、接口清单、回调说明、变更流程白纸黑字确认下来，后面扯皮都少很多。
我个人这几年做E9集成，最欣慰的时刻就是看到两个系统之间数据流得干干净净、两边同事都不用手工搬运数据和反复电话确认。做集成开发的成就感不在代码多漂亮，而在业务真的因为你的工作少折腾了一些。希望这篇记录能帮你把路走直一点，少熬几个夜。
