无忧卡销售退货同步至金蝶云星空应收单:单策略实战教程
这个策略解决什么问题
在零售与分销业务里,「无忧卡销售退货」往往意味着客户把已购买的无忧卡商品退回,系统需要把退货动作翻译成财务侧的应收单红字,才能让销售退货与应收账款联动起来。我们这次在客户现场面对的就是这个场景:前端业务系统(下文统称"源系统")每天会产生无忧卡销售退货单,需要把这些单据按业务日期增量同步到金蝶云星空生成应收单,并自动提交审核。整条链路看似只是「拉单—写单」,但单据编号怎么拼、组织/客户编码怎么对齐、明细行怎么循环传,任何一个细节没设计好,3 个月后两边账就对不上了。我们在轻易云数据集成平台(Qeasy)上用一个独立策略承接了这件事。
数据流向与字段映射
数据流向非常清晰:源系统(无忧卡销售退货单) → 轻易云中间层(字段映射 + 转换) → 金蝶云星空应收单(AR_receivable)。
主表关键字段对照
| 源字段 | 目标字段 | 映射类型 | 转换规则 | 业务说明 |
|---|---|---|---|---|
| FSETTLEORGID | FSETTLEORGID | DIRECT | {{FSETTLEORGID}} | 结算组织 |
| FPAYORGID | FPAYORGID | DIRECT | {{FPAYORGID}} | 付款组织 |
| FSALEORGID | FSALEORGID | DIRECT | {{FSALEORGID}} | 销售组织 |
| FBillTypeID | FBillTypeID | DIRECT | {{FBillTypeID}} | 单据类型 |
| FBillNo + FDATE | FBillNo | TRANSFORM | _function concat('PSARWY', DATE_FORMAT('{{FDATE}}','%Y%m%d'), '{{FBillNo}}') | 唯一单据编号 |
| FDATE | FDATE | DIRECT | {{FDATE}} | 业务日期 |
| FDATE | FENDDATE_H | DIRECT | {{FDATE}} | 到期日与业务日期一致 |
| FCURRENCYID | FCURRENCYID | DIRECT | {{FCURRENCYID}} | 币别 |
| FSALEDEPTID | FSALEDEPTID | DIRECT | {{FSALEDEPTID}} | 销售部门 |
| FISTAX | FISTAX | DIRECT | {{FISTAX}} | 含税标识 |
| — | FCancelStatus | CONSTANT | A | 作废状态固定为正常 |
| FCUSTOMERID | FCUSTOMERID | DIRECT | {{FCUSTOMERID}} | 客户 |
| FAR_Remark | FAR_Remark | DIRECT | {{FAR_Remark}} | 备注 |
| Items | FEntityDetail | COLLECTION | Items | 明细整体引用 |
明细行映射:目标端 FEntityDetail 直接整体引用源端 Items 数组,平台按行循环写入。如果后续发现 Items 子字段名与金蝶应收单明细字段不完全一致,需要在明细层级补 value 表达式,或通过 scripts 做行级转换——这是后话,先按"整体引用"上线。
在轻易云上如何配置
整条策略在一个轻易云策略里完成,源端与目标端分开配置。
源端(Source)
- 接口:
/api/QueryWFStockIn,类型 QUERY,POST。 - 主键字段:
FBillNo,开启idCheck与autoFillResponse。 - 请求参数:PageNo=1、PageSize=500、
FDateFrom={{LAST_SYNC_TIME|datetime}}、FDateTo={{CURRENT_TIME|datetime}},按上次同步时间到当前时间做业务日期范围拉取。 - 响应结构:主表字段(
FBillNo、FDATE、FSETTLEORGID、FCURRENCYID、FBillTypeID、FCUSTOMERID、FPAYORGID、FSALEORGID、FISTAX、FSALEDEPTID、FAR_Remark等),明细数组Items。
目标端(Target)
- 接口:
batchSave,类型 EXECUTE,POST。 - FormId:
AR_receivable,Operation:BatchSave。 - 关键开关:
IsAutoSubmitAndAudit=true自动提交并审核;IsVerifyBaseDataField=false不校验基础资料;ValidateRepeatJson=true开启重复校验;InterationFlags=CRE_ExceptionInfo。 - 字段映射按上表配置,重点是 FBillNo 的拼接函数,以及 FCancelStatus 固定为
A。
编码映射集中管理:FSETTLEORGID/FPAYORGID/FSALEORGID/FCUSTOMERID 这些组织与客户编码,直接取自源端。我们在轻易云里把"组织—客户"编码对照集中维护在一个映射配置里,如果后期出现编码不一致,通过统一改映射就能批量修复,不用每个策略都动。
实施步骤
分阶段推进,避免一上来就跑全量把目标系统压垮。
- 增量起点:源端 crontab 设为
10 */4 * * *(每 4 小时第 10 分钟),首次同步时把LAST_SYNC_TIME调整到一个明确的业务起点日期(例如上线前一天),保证从这一刻开始增量拉取,不会重复拉历史数据。 - 全量触发:上线当天,在业务低峰期手动触发一次全量,把历史无忧卡退货单一次性补齐。轻易云支持手动触发一次 QUERY + EXECUTE 全流程,触发前确认目标端组织、客户主数据已就绪。
- 调度频率:目标端 crontab 设为
*/5 * * * *(每 5 分钟),源端每 4 小时拉一次,目标端每 5 分钟消费一次。这样源端数据有积压时,目标端能快速消化,避免延迟。 - 上线观察:连续观察 3 个调度周期,核对 FBillNo 拼接是否唯一、应收单是否重复创建、明细行是否完整,然后再把频率拉满到生产节奏。
踩坑复盘
- FBillNo 拼接是命门:典型错误是直接拿源端
FBillNo当目标端单据号。结果同一笔退货单在重跑或补传时,会因为目标端校验重复而失败,或者因为多日数据撞号产生脏数据。稳妥的做法是按"固定前缀 + 业务日期 YYYYMMDD + 源单据号"拼接,既唯一又可追溯。 - 组织/客户编码要对齐主数据:FSETTLEORGID、FPAYORGID、FSALEORGID、FCUSTOMERID 都是 DIRECT 直传,但前提是两边主数据编码一致。我们在客户现场第一次跑就翻车:源端客户编码和金蝶不一致,导致应收单创建失败。建议在轻易云里维护一份「编码映射集中表」,由主数据同步策略先行对齐。
- 明细行不要"先跑通再说":FEntityDetail 直接引用 Items 是最快上线的方式,但 Items 子字段一旦与金蝶应收单明细字段名不一致,会出现"主表成功、明细为空"的隐蔽问题。稳妥的做法是上线前用真实 API 响应跑一次 dry-run,把 Items 实际子字段列出来,再补明细映射或脚本。
- 到期日与业务日期一致是有意为之:FENDDATE_H = FDATE 表示按退货日即到期,无账期延后。如果业务侧后期要求按 30 天账期到期,这里必须改表达式,不能想当然。
- 作废状态 FCancelStatus 固定为 A:所有同步过来的应收单都视为正常单,不做作废。如果同步历史退货单时存在已冲销数据,需要单独走作废逻辑,不能直接复用本策略。
适用场景与不适用场景
适用:源系统按业务日期增量产出无忧卡销售退货单,且目标端金蝶云星空已具备组织、客户、物料主数据;退货体量适中,接受每 4 小时拉一次、每 5 分钟写一次的节奏。
不适用:退货单需要走复杂审批流(本策略自动提交审核,不再人工干预);源端 Items 字段与目标端应收单明细差异巨大、需要重度的行级转换;或者组织/客户编码在两边长期不一致、又无法通过主数据同步策略统一的情况。