采购退料单同步实战:金蝶云星空到吉客云采购退-其他出库单
这个策略解决什么问题
某零售企业在供应链集成项目中,把金蝶云星空作为 ERP 主干,把吉客云作为 WMS 与全渠道中台。采购退料场景下,金蝶负责财务记账与应付冲减,吉客云负责出库执行与物流。当一张采购退料单在金蝶审核后,WMS 侧的实退出库必须同步发生,否则库存账与实物会偏离。本策略将金蝶 PUR_MRB 采购退料单(单据类型 TLD10_SYS、TLD09_SYS)增量同步至吉客云 采购退-其他出库单(outType=205),实现两系统退货业务一致。
数据流向与字段映射
数据流向:金蝶云星空 → 轻易云数据集成平台 → 吉客云。源端经 executeBillQuery 拉取扁平化数据,按 FBillNo 分组构建主表 + 明细行结构,再写入吉客云 erp.storage.stockoutcreate。
主表关键字段对照
| 源字段(金蝶) | 目标字段(吉客云) | 映射类型 | 说明 |
|---|---|---|---|
| FSupplierID_FNumber | vendCode | DIRECT | 供应商编码 → 往来单位编码 |
| details_list.FSTOCKID_FNumber | outWarehouseCode | COLLECTION | 仓库取自明细行 |
| — | outType | CONSTANT | 固定 205(采购退) |
| FBillNo | relDataId | DIRECT | 单据编号 → 关联单据编号 |
| FDate | applyDate | DIRECT | 退料日期 → 申请时间 |
| FCreatorId | applyUserName / operator | DIRECT | 创建人 |
| — | source | CONSTANT | OPEN(开放平台标识) |
| details_list | stockOutDetailViews | COLLECTION | 明细数组 |
| — | logisticName | CONSTANT | 自提 |
明细行字段对照
| 源字段 | 目标字段 | 说明 |
|---|---|---|
| FMATERIALID_FNumber | goodsNo | 物料编码 → 货品编号 |
| FRMREALQTY | quantity | 实退数量(注意是实退,不是应退) |
| FPrice | cuPrice | 单价 |
| FAmount | cuValue | 行金额 |
| FNOTE | rowRemark | 行备注 |
| FMATERIALID_FBARCODE | 条码/备用 | 物料条码 |
源端编码映射(物料→货品、供应商→往来单位、仓库→仓库)在轻易云上做集中管理,两系统编码必须已建立对照或同步,否则同步会失败。
在轻易云上如何配置
在轻易云数据集成平台,进入策略配置页,按以下要点配置:
源端(金蝶):API 选 executeBillQuery,FormId 固定 PUR_MRB,metadata 中按 FBillNo 设置主键,明细 ID 取 FPURMRBENTRY_FEntryID。buildModel 设为 true,平台会自动按 FBillNo 分组,主表字段重复保留一次,明细行归入 details_list。
FilterString:FApproveDate>='{{LAST_SYNC_TIME|dateTime}}' and FBillTypeID.FNUMBER in('TLD10_SYS','TLD09_SYS') and FSTOCKID.FNumber = 'RR-FZ1A',按审核日期增量、单据类型过滤、限定仓库。
目标端(吉客云):API 选 erp.storage.stockoutcreate,stockOutDetailViews 的 value 显式配置为 details_list,与盘亏单、调拨单策略保持一致。明细行通过行级字段映射对应 goodsNo、quantity、cuPrice、cuValue。
调度错峰:源端 0-59/8 7-22 * * *,目标端 2-59/8 7-22 * * *,错开两分钟,避免同一时间窗内上下游同时打满。
实施步骤
第一阶段:全量初始化。在策略上线前,手动跑一次全量任务(去掉 FApproveDate 增量条件),把历史采购退料单一次性同步至吉客云,便于核对两边数据基线。
第二阶段:增量起点设置。全量完成后,记录本次执行时间作为 LAST_SYNC_TIME 初值,之后调度按 FApproveDate 增量拉取。增量与全量双轨是轻易云客户常见的应对模式,全量用来对账,增量用来跟新。
第三阶段:常态化调度。按上述 cron 进入 7–22 点的 8 分钟一周期调度,重点观察审核日期触发的单据是否都能在两分钟内到达吉客云。
第四阶段:异常兜底。配置失败重试与告警,配合轻易云日志排查 ID 写重复、字段缺失、编码未映射等典型问题。
踩坑复盘
坑一:stockOutDetailViews target value 留空。素材里 value 为空字符串,结果明细数组引用不上,吉客云侧收到的是空明细。这里容易翻车。稳妥的做法是显式配置 details_list,与盘亏单、调拨单策略保持一致。
坑二:buildModel 关闭导致分组失败。源端 executeBillQuery 返回扁平化数据,同一张单据多行明细被拍平。buildModel=false 时,details_list 不存在,目标端引用就为空。务必把 buildModel 打开,让平台按 FBillNo 自动聚合。
坑三:仓库从明细取数,多行多仓库未拆分。outWarehouseCode 取自 details_list.FSTOCKID_FNumber,若一张采购退料单多行对应不同仓库,目前策略是取首行仓库,业务上需提前与客户确认是按仓库拆单,还是取首行仓库。
坑四:实退 vs 应退数量搞混。明细数量应取 FRMREALQTY(实退数量),不是 FRMMUSTQTY(应退数量)。两者在部分退货场景下数值不同,典型错误是直接复制盘亏单或调拨单的 FQty/FLossQty 字段。
坑五:编码未集中映射。物料、供应商、仓库编码在两系统不一致时,吉客云会直接拒收。轻易云客户常见的应对模式是把编码映射集中管理在平台层,做统一对照表,任何编码变更先在对照表生效。
适用场景与不适用场景
适用:金蝶作为 ERP 主干、吉客云作为 WMS 与全渠道中台,需要把采购退货业务自动同步,且单据类型、仓库、退货数量、退货日期可结构化映射。
不适用:金蝶与吉客云编码尚未做主数据对照、单据需要复杂审批流跨系统协同、或者采购退料需要按多仓库拆单而策略尚未支持的场景。