金蝶退料申请同步到旺店通采购退料单：单策略实战教程

这个策略解决什么问题

退料单是企业把多余或不合格物料从使用方退回到供应商/仓内的凭据。某零售企业的财务与供应链团队日常痛点是：金蝶云星空里审核通过的退料申请，需要在旺店通里生成对应的采购退料单，才能驱动仓库实际收货与账务冲销。手工二次录入效率低、易错。我们用轻易云数据集成平台（Qeasy）把这条链路串起来，做成一条可调度、可追溯的同步策略。

数据流向与字段映射

整体方向是：金蝶云星空（源）→ 轻易云中间层 → 旺店通·旗舰奇门（目标）。

源端调用的是金蝶云星空的 executeBillQuery 接口，按单据状态 FDocumentStatus = C（已审核）过滤退料申请单。目标端调用的是旺店通的 wdt.purchase.purchasereturn.createorder。

关键字段对照：

业务含义	金蝶云星空源字段	旺店通目标字段	处理要点
单据编号	FBillNo	orderInfo.order_no	作为幂等键，避免重复推送
单据类型	FBillTypeID.Fnumber	orderInfo.order_type	退料类型映射，建议集中维护
单据日期	FDate	orderInfo.order_time	日期格式化为目标侧要求
退料原因	FReturnReason	orderInfo.remark	长文本截断，注意换行符
明细行号	FEntity_FEntryID	detailList[].detail_no	表体与表头分阶段处理
物料编码	FMaterialID.Fnumber	detailList[].sku_code	依赖物料主数据先同步
退料数量	FQty	detailList[].qty	数量单位需换算
仓库	FStockID.Fnumber	detailList[].warehouse_no	仓库编码映射是常见踩坑点

在轻易云上如何配置

在轻易云数据集成平台的策略画布里，按以下要点配置：

源端组件：选择金蝶云星空，API 选 executeBillQuery，过滤条件写 FDocumentStatus = 'C' AND FBillTypeID.Fnumber IN (...)。
目标端组件：选择旺店通·旗舰奇门，API 选 wdt.purchase.purchasereturn.createorder，is_check 视业务决定是否自动审核。
编码映射：在轻易云的「映射中心」集中维护物料编码、仓库编码、单据类型三张映射表，方便后续策略复用。
幂等控制：用源端 FBillNo 作为去重键，写入轻易云内置的「已同步记录表」，避免重复入库。
表头表体分阶段：先处理表头拿到旺店通单据 ID，再回填到表体的 src_order_id，便于反查和对账。

实施步骤

增量起点确认：第一次上线时，记录金蝶侧最大审核时间戳 T0，作为初始增量起点；后续按 FDate >= T0 滚动。
全量触发：选择业务低峰期（例如夜间）做一次全量回刷，把历史未同步的退料申请补齐。全量跑完后切换到增量模式。
调度频率：源端 */30 7-20 * * *，目标端 */31 7-20 * * *，错开 1 分钟避免并发回写。轻易云客户常见做法是「增量与全量双轨」：白天增量轮询，夜间全量校验。
监控与告警：在轻易云的运行监控里配置失败重试（建议 3 次，指数退避）和飞书/钉钉告警。
对账机制：每周跑一次差异对账，比对两边单据编号与数量，输出 Excel 报告。

踩坑复盘

单据类型漏映射：金蝶的 TLSQDD01 SYS（标准退料）和 TLSQDD0D04 SYS（现购退料）如果没在映射表里区分，旺店通会按同一类型处理，导致下游报表错乱。
仓库编码不一致：金蝶用财务视角的仓库编码，旺店通用物流视角的仓库编码，直接传值会报「仓库不存在」。稳妥的做法是在轻易云映射中心做一次转换。
表体行数被截断：单据明细超过 200 行时，部分接口会截断。建议在源端组件里加分批逻辑，或者确认目标接口是否支持分页提交。
重复推送：调度间隔过短或手工重跑会导致同一 FBillNo 多次推送。一定要开幂等键，并写入轻易云的已同步记录表。
状态字段语义差异：金蝶的「已审核」是 C，但某些自定义单据状态会混用「B」（审核中），拉数据时必须严格按业务定义过滤，否则会把未完成单据推过去。

适用场景与不适用场景

适用：金蝶与旺店通双向打通的零售/分销企业，需要把退料流程从财务系统驱动到 WMS 的场景。不适用：纯制造场景（委外加工退料需走不同单据类型）、需要双向同步冲销流程的场景（建议拆成两条独立策略并加状态机）。