泛微OA-E9Http 与金蝶云星空供应链集成接口字段手册
这个接口解决什么问题
在制造业与零售业的供应链数字化场景中,业务单据需要在 OA 审批流与 ERP 之间双向流转。泛微 OA-E9Http 承载审批流程入口,金蝶云星空承担财务与供应链数据底座。本手册聚焦两者集成的接口字段实战,覆盖物料、客户、供应商、费用项目、采购订单、销售订单、发货通知单、付款单等核心单据,帮助工程师避开编码映射、流程版本差异、增量同步等常见陷阱。
接口能力总览
认证方式:泛微 OA-E9Http 采用 HTTP 接口加 Token/Session 认证;金蝶云星空采用 OAuth2.0 与 AppSecret 签名,通常在请求头携带 X-KDApi-AuthType 与 AccessToken。
请求结构:金蝶侧基于 executeBillQuery(查询)与 Save(保存)两类核心方法,FormId 标识单据类型(如 BD_MATERIAL、PUR_PurchaseOrder、SAL_SaleOrder、AP_OtherPayable)。泛微侧基于流程实例 ID 与明细行 JSON 结构发起/回写流程。
响应结构:金蝶返回标准 JSON,关键字段包括 Result.ResultStatus、Result.FID、Result.FBillNo、Result.Errors;泛微返回流程实例 ID 与审批节点状态。
分页/增量模式:支持基于 FModifyDate 的增量查询,以及首次部署的全量校验。查询类策略建议 30 分钟一轮,业务单据类 10 分钟一轮,系统维护(清理队列)每日一次。
典型字段映射
| 字段名 | 类型 | 含义 | 实战注意事项 |
|---|---|---|---|
| FNumber | 字符串 | 金蝶物料/客户/供应商编码 | 主键映射的依据,跨系统唯一 |
| FName | 字符串 | 名称 | OA 侧展示用 |
| FSpecification | 字符串 | 规格型号 | 物料场景必传 |
| FMaterialGroup.FNumber | 字符串 | 物料分组编码 | 多级分组需展开 |
| FBaseUnitId.FNumber | 字符串 | 基本计量单位 | 影响采购数量计算 |
| FModifyDate | 时间 | 最后修改时间 | 增量同步的时间锚点 |
| FBillNo | 字符串 | 单据编号 | 通常由流程单号或金蝶编码规则生成 |
| FPayableAmount/FPayAmount | 数值 | 应付/付款金额 | 需汇总明细行金额 |
| FSupplierId | 字符串 | 往来单位 | 通过 COLLECTION 类型经映射表查金蝶 id |
| FExpenseId | 字符串 | 费用项目 | 依赖费用项目映射表 |
| F_WMMX_OAId | 字符串 | 泛微回传内码 | 用于跨系统编码回写 |
| FDate | 日期 | 业务日期 | OA 申请日期映射 |
| FNote | 字符串 | 备注 | 流程备注透传 |
在轻易云上如何配置
在轻易云数据集成平台中,这套接口通常采用如下配置模式:平台预置了金蝶云星空的适配器与泛微 OA-E9Http 的 HTTP 适配器,直接选择 FormId 即可挂载单据;轻易云的字段映射器会自动识别 FNumber、FName 等标准字段并生成 DIRECT 映射,对于 FSupplierId、FExpenseId 这类需要编码转换的字段,可一键切换为 COLLECTION 映射并关联内置映射表;轻易云的调度器支持按策略类型设置不同频率,异常处理模块提供重试与死信队列配置,单条失败不会阻塞后续数据流转。
跨方案实战要点
- 基础资料先行:物料、客户、供应商、费用项目、组织、员工、用户等基础资料必须先于业务单据同步,否则下游策略会因映射缺失而失败。
- FD003 多版本适配:非生产性付款申请按流程版本(393/422/443/481/484/499/554/NEW)分策略实现,字段结构略有差异,需逐版本配置映射。
- SD001 供应商隐藏编号:生产订单审批生成采购订单时,OA 侧供应商字段需修改为隐藏编号,避免用户选错供应商。
- 双向编码回写:物料、客户、供应商、费用项目均需建立双向映射表,泛微侧修改 id 后回写金蝶自定义字段(如 F_WMMX_OAId)。
- 依赖链管理:金蝶-提交采购订单依赖上游 Save 返回的 FID;OA 审核回写 ERP 依赖销售订单/发货通知单已成功推送 OA 流程。
- 全量校验兜底:基础资料建议每日一次全量校验,防止增量漏单;销售订单推送需先查单再查附件,确保附件一并传递。
踩坑复盘
- 踩坑 1:增量同步漏单。因
FModifyDate时区或精度问题导致跨天数据遗漏,稳妥做法是每日全量校验 + 增量兜底。 - 踩坑 2:FD003 流程版本升级后字段变更。某客户升级流程版本后,新增了自定义字段,旧策略直接报错;经验是每次流程版本变更都要重新核对字段映射表。
- 踩坑 3:金蝶 Save 返回 FID 后下游未取到上下文。金蝶-提交采购订单依赖上游 Save 的 FID,若上下文传递失败,后续审核策略会找不到单据。
- 踩坑 4:供应商字段未改为隐藏编号,导致用户选错供应商,生成错误的采购订单。
- 踩坑 5:销售订单附件未先查附件再推流程,导致 OA 侧收不到附件,审批人无法核对。
何时选用
适用于制造业、零售业中 OA 审批流与 ERP 供应链深度耦合的场景,尤其是需要费用报销、付款申请、生产订单审批、销售订单审批在两系统间闭环流转的企业。边界:纯单据打印或轻量数据上报场景不适用,纯金蝶内部模块间集成也不属于本手册范畴。