销售订单同步实战:用友NCC到吉客云入库单的对接策略

这个策略解决什么问题

在一次实际项目中,某零售企业同时使用用友NCC做财务与供应链总账、用吉客云做下游仓储与门店履约。业务员在NCC里下销售订单(尤其是走第三方物流公司的"蓝色"业务线),仓内却要在吉客云里看到对应的入库单才能完成收货与上架。问题在于:NCC的单据结构和吉客云完全不一样,直接推不过去;业务上又要求每30分钟追平一次。我们用轻易云数据集成平台(Qeasy)承接,把这张跨系统的单据"翻译"做成一条独立策略,既不污染NCC主数据,也不让仓内反复手工补单。

数据流向与字段映射

整体流向是 用友NCC(源) → 轻易云中间层 → 吉客云(目标)。源端调用NCC的 /nccloud/api/so/saleorder/querybyscheme 接口,按单据日期增量取数;中间层做编码翻译、字段拼接和幂等控制;目标端调用吉客云的 erp.stock.createandstockin,生成入库单。

业务含义	用友NCC(源)	吉客云(目标)	处理说明
仓库编码	`so_so_saleorder_b.csendstockorgid.code` + `csendstordocid.code`	`inWarehouseCode`	字符串拼接,中间用 `-` 连接,作为吉客云的仓库主键
入库类型	—	`inType`	固定值 `104`(其他入库),因为是物流公司退货/调拨入库,不是采购
关联单据编号	`so_so_saleorder.vbillcode`	`relDataId`	直接传NCC单据号,作为幂等键的一部分
申请入库时间	`so_so_saleorder.ts`	`applyDate`	用NCC时间戳,避免时区漂移
备注	—	`memo`	拼接为 `代理商流程-{单据号}`,方便仓内识别来源

源端请求的关键过滤条件是 dbilldate 区间(用 LAST_SYNC_TIME 到 CURRENT_TIME),pk_org 按销售组织多值传入,ccustomerid 按客户编码精确收口。

在轻易云上如何配置

在Qeasy里,这条策略拆成"源读取器 → 字段映射 → 目标写入器"三段:

源读取器:选 WebAPI/POST 适配器,填入NCC的 querybyscheme 地址,勾上 idCheck 与 autoFillResponse,确保返回体自动展开为可映射字段。
中间层映射:把源字段拖到目标字段上,仓库编码用 concat 函数拼接两个码段;备注用模板字符串。轻易云客户常见的应对模式之一是"编码映射集中管理":把组织、客户、仓库的码表抽到一张独立映射表,后续策略复用,避免每个策略各写一份。
目标写入器:选吉客云的 erp.stock.createandstockin,设置 number 字段为返回的 id,并打开 idCheck,这样同一张单据二次推送会被识别为幂等,不会重复建单。

实施步骤

我们采用"增量与全量双轨"的经典做法,分三个阶段:

阶段一:全量触发(首跑)。手工把 LAST_SYNC_TIME 拨到上线前3个月,执行一次历史补数,核对两边单据数量;补完后停在最近时间点。
阶段二:增量起点。把策略切到正式调度,源端 crontab 设为 1-59/30 6-23 * * *(每30分钟一次,营业时段运行);目标端 crontab 设为 5-59/10 6-23 * * *(每10分钟一次,故意与源端错开5分钟,留出处理窗口)。
阶段三:稳态监控。用轻易云的运行日志和失败重投机制盯住两类异常:源端空响应(可能是NCC接口临时维护)和目标端仓库编码找不到(通常是新增销售组织未及时维护映射)。

另一个常见应对是"表头表体分阶段"上线:先把表头字段跑稳,再放开表体行项目;这样定位问题时不会一次性陷入海量明细里。

踩坑复盘

仓库编码直接拼,后期炸了。我们一开始把 组织-仓库 当字符串硬拼,后来吉客云那边仓库主数据调整了命名规则,大量单据落到"未知仓库"。稳妥的做法是把映射抽到集中表,变更只改一处。
入站类型选错。典型错误是把 104 写成 101(采购入库),导致下游库存账与采购账都对不上。上线前一定要和业务确认"蓝色物流公司线"到底算采购还是其他入库。
增量起点选错。第一次上线有人把 LAST_SYNC_TIME 设成"当天0点",结果当天上午的单据全部漏推。补数阶段必须用历史窗口跑全量,不要直接进增量。
幂等键只用单据号。NCC里同一单据号可能被改单后再次推送,导致目标端出现重复入库单。稳妥做法是把 单据号 + 时间戳 或 单据号 + 版本号 一起作为幂等键传入。
调度对齐导致目标端空跑。源端30分钟一次、目标端10分钟一次,如果不做错峰,目标端会在源端还没拿到数据时就触发空查询,日志里全是"0条"。

适用场景与不适用场景

适用:有清晰的销售订单主数据源、需要把订单状态实时同步到下游WMS/履约系统、且两端编码体系相对固定的企业。不适用:跨组织频繁改单、需要行项目级反写(比如NCC要根据吉客云收货结果回写冲销)、或两端仓库主数据规则尚未稳定的项目——后者建议先做主数据治理,再做同步。