金蝶其他入库单同步至吉客云：基于轻易云的实战配置教程

这个策略解决什么问题

某零售企业的仓库里,每天都会发生一批"说不清归哪一类"的入库:赠品、样品、零星采购退货、活动物料补回……这些业务既不算采购入库,也不走调拨或盘盈,只能记入"其他入库单"。该企业同时使用金蝶云星空做财务与库存核算、吉客云做仓储与门店管理,两套系统各自维护一份其他入库单。3 个月后盘点,两边数量对不上,财务追不到货,门店又报缺货——典型的"主数据分散+单据孤岛"问题。

我们的做法是:用轻易云数据集成平台(Qeasy)把金蝶的其他入库单按审核日期增量推送到吉客云,以金蝶单据编号作为关联键,在吉客云侧创建 inType=104 的其他入库单,统一库存入口。这一策略的真正价值不是"把单据搬过去",而是把库存语义在两套系统之间对齐。

数据流向与字段映射

数据流向:金蝶云星空(STK_MISCELLANEOUS / QTRKD02_SYS)→ 轻易云中间层 → 吉客云(erp.storage.stockincreate / inType=104)。

主表关键字段对照

源字段(金蝶)	目标字段(吉客云)	映射类型	说明
FSTOCKID.FNumber	inWarehouseCode	DIRECT	收货仓库编码
—	inType	CONSTANT	固定 104(其他入库)
FBillNo	relDataId	DIRECT	金蝶单据编号作为业务追溯键
FDate	applyDate	DIRECT	申请时间
FCreatorId.FName	operator / applyUserName	DIRECT	制单人、申请人
—	source	CONSTANT	OPEN(开放平台标识)

明细行关键字段对照

源字段	目标字段	映射类型	说明
FMATERIALID.FNumber	goodsNo / skuCode	DIRECT	物料编码需与吉客云货品主数据一致
FQty	inQty	DIRECT	实收数量(注意区别于盘盈单的 FGainQty)
FPrice	price	DIRECT	成本价
FAmount	amount	DIRECT	总成本
FLOT.fnumber	batchNo	DIRECT	批次管理物料需传
FPRODUCEDATE	productionDate	DIRECT	生产日期
FEXPIRYDATE	expirationDate	DIRECT	有效期
FCMKBarCode	barcode	DIRECT	零售条形码

在轻易云上如何配置

在轻易云平台创建一个策略,源端选"金蝶云星空",目标端选"吉客云",按以下要点配置:

源端元数据:API 选 executeBillQuery(QUERY / POST),FormId 填 STK_MISCELLANEOUS,number 字段填 FBillNo,明细 id 填 FEntity_FEntryID。把 FSTOCKID.FNumber、FMATERIALID.FNumber 这类对象路径写入 FieldKeys,平台会按 . 解析子字段。
目标端元数据:API 选 erp.storage.stockincreate(EXECUTE / POST),id 用吉客云返回的 id,relDataId 接 {{FBillNo}},inType 写死 104。
映射规则:按上表逐项填写,常量(inType、source)直接写值;集合型(stockInDetailViews)引用源端分组后的 details_list。
源端过滤:FilterString 设为 FApproveDate>='{{LAST_SYNC_TIME|dateTime}}' and FBillTypeID.FNUMBER='QTRKD02_SYS' and FSTOCKID.FNumber in ('RR-FZ1A','RR-FZ-JDZY','RR-FZ2Q')——按审核日期增量,锁定单据类型,限定仓库。
校验:开启 idCheck,保证同一 FBillNo 不会被重复创建。

实施步骤

我们把上线拆成三个阶段:

阶段一:编码映射集中管理。先做物料→货品、仓库→仓库的主数据对照(可在轻易云中用 _findCollection 联查),这是后续单据同步能跑通的"地基"。
阶段二:全量触发。上线当天,把 LAST_SYNC_TIME 调到一个早于实际业务的日期,手动触发一次,把历史单据补齐;同时把 idCheck 打开,避免重复创建。
阶段三:调度频率。源端 cron 设为 5-59/20 7-22 * * *(业务时段每 20 分钟),目标端错开 5 分钟设为 10-59/20 7-22 * * *,避免两端同时拉取造成拥塞。下班时段不调度,减轻数据库压力。

踩坑复盘

扁平化数据没分组。金蝶 executeBillQuery 返回扁平行,主表字段在每条明细行都重复。如果不在数据流层按 FBillNo 分组构建 details_list,目标端收到的明细数量就是 1 行,库存数量直接对不上。这里容易翻车,稳妥做法是在平台数据流层显式配置分组逻辑。
仓库编码直接用对象路径。{{FSTOCKID}} 在某些版本下会返回对象而不是字符串,导致吉客云侧报"仓库不存在"。需要确认源端 FieldKeys 是否启用了对象字段扁平化,或者把映射写成 {{FSTOCKID_FNumber}}。
入库数量取错字段。其他入库应该取 FQty(实收数量),不要照搬盘盈单的 FGainQty 或采购入库的 FRealQty。把字段语义写在映射备注里,后续维护少踩雷。
批次与有效期漏传。批次管理物料如果不传 batchNo,吉客云会按无批次入库,后续拣货、效期预警全失效。建议在物料主数据上标注"是否批次管理",做条件映射。
增量起点错配。LAST_SYNC_TIME 如果写成服务器时区,跨时区部署时会少拉或多拉数据。统一存 UTC、在平台表达式里转本地时间,是更稳妥的做法。

适用场景与不适用场景

适用:多组织多仓的零售/分销企业,金蝶做财务库存、吉客云做仓储 WMS,需要把其他入库、盘盈、零星补货等非标库存变动统一在吉客云侧落账。

不适用:纯金蝶或纯吉客云的单仓场景(直接用系统自带功能即可);需要双向实时同步的高频业务(建议改用事件驱动而非 20 分钟轮询);跨法人主体、库存组织不一致的复杂集团架构(需先做组织映射再谈单据)。