携客云核价单同步到金蝶云采购价目表:单策略实战教程
这个策略解决什么问题
某制造企业的采购部门长期受困于一个老问题:供应商在外部比价系统里谈好的价格,要在 ERP 里再录一遍。录就录吧,三个月后两边数字一对,又对不上——不是含税单价没更新,就是税率、生效日期漏了。我们用轻易云数据集成平台(Qeasy)承接的「携客云核价单 → 金蝶云采购价目表」这条同步链路,就是要把核价单上的供应商、物料、含税价、税率、生效/失效日期,原原本本推到金蝶云星空的采购价目表里,让采购下单时直接按价目表取价,杜绝双系统手工录入。
数据流向与字段映射
数据流是单向的:携客云(源)→ 轻易云集成平台(中间层,负责字段转换与明细构建)→ 金蝶云星空(目标)。源端接口 /pricingOrder/getDetail.json 是按核价单号 prcXkNo 查询的单笔详情接口,response 里既有主表级字段(核价单号、供应商编码、供应商名称、比价 URL),也有行级字段(物料编码、含税价、税率、生效日期、失效日期)。
主表关键字段对照:
| 业务含义 | 源字段 | 目标字段 | 映射类型 |
|---|---|---|---|
| 核价单号(业务追溯主键) | prcXkNo | F_UQTJ_HJD | DIRECT |
| 供应商编码 | innerVendorCode | FSupplierID | DIRECT |
| 来源单号 | sourceXkNo | F_UQTJ_LYDH | DIRECT |
| 比价 URL | priceUrl | F_UQTJ_URL | DIRECT |
| 单据名称 | innerVendorName + 时间戳 | FName | TRANSFORM |
| 采购组织 | — | FCreateOrgId | CONSTANT=100 |
| 价目表对象 | — | FPriceObject | CONSTANT=A |
| 价格类型 | — | FPriceType | CONSTANT=2 |
| 币别 | — | FCurrencyID | CONSTANT=PRE001 |
| 是否默认价目表 | — | FDefPriceListId | CONSTANT=true |
明细行(FPriceListEntry,value 引用 lineList):
| 业务含义 | 源字段 | 目标字段 | 转换要点 |
|---|---|---|---|
| 物料编码 | productCode | FMaterialId.FNumber | 需与金蝶物料主数据一致 |
| 含税单价 | taxPrice | FTaxPrice | 数值透传 |
| 税率 | taxRate | FTaxRate | 注意百分比/小数形式 |
| 生效日期 | effectiveDate | FEffectiveDate | int 时间戳 → yyyy-MM-dd |
| 失效日期 | invalidDate | FExpiryDate | int 时间戳 → yyyy-MM-dd |
目标端 otherRequest 固定三件套:FormId=PUR_PriceCategory、IsAutoSubmitAndAudit=true、Operation=Save,保存即自动提交审核。
在轻易云上如何配置
在 Qeasy 里,这条策略配成「源端 QUERY + 目标端 EXECUTE」的组合即可。源端 metadata 声明 API /pricingOrder/getDetail.json、方法 POST、主键 prcXkNo;请求参数里 erpCode 取环境变量 {{ERP_CODE}},prcXkNo 由上游调度传入,isCreateViewUrl 固定 1。
目标端 metadata 声明 Save、方法 POST、idCheck=true,业务对象 PUR_PriceCategory。映射层把源端字段按上表规则绑定,重点是明细:源端 response 是扁平结构,需要在数据流里构造一个 lineList 数组,让目标端 FPriceListEntry 通过 value=lineList 引用。这样无论源端返回单行还是多行明细,都能被金蝶侧正确解析成多行价目表条目。
客户现场常见的应对模式有三种:一是编码映射集中管理,把供应商、物料、组织、币别的对照关系抽到一张映射表里,避免散落在各策略中;二是表头表体分阶段,先跑通表头(核价单号、供应商),再补明细行;三是增量与全量双轨,日常按增量跑,首次上线或修复期再触发一次全量补传。
实施步骤
分三阶段推进:
第一阶段:增量起点。从携客云拉取已生效、未失效的核价单(按 prcXkNo 单笔拉取),先只同步表头,确认供应商编码能命中金蝶供应商主数据、FName 拼接无误、目标端 Save 能成功返回。这一阶段目标是「单据能落库」。
第二阶段:全量触发。在确认主数据就位后,打开明细映射,补全 lineList 构建逻辑与日期转换;触发一次全量回填,覆盖近 3–6 个月的核价单,让金蝶侧的价目表与携客云历史数据对齐。这一阶段目标是「历史数据平账」。
第三阶段:调度频率。crontab 建议设为每日凌晨跑一次(1 1 1 1 1 这种五位表达是轻易云私有化环境的标准语法)。日常按增量同步,新增/变更的核价单 T+1 进入金蝶;月底或季度做一次全量校验,核对两边价目表金额与生效日期。
踩坑复盘
1. 编码映射没设计好,3 个月后两边数字对不上。 这是最容易翻车的点。源端 innerVendorCode 和金蝶 FSupplierID 看上去都是编码,直接透传就行;但如果金蝶侧供应商主数据是用内码而非业务编码,源端的业务编码根本落不进去。稳妥的做法是上线前先把供应商、物料对照表对齐,并在数据流里加一道 _findCollection 联查作为兜底。
2. 明细结构误判。 源端 metadata 把 taxPrice、productCode 等行级字段平铺在 response 里,看起来像「单行」。但实际携客云 API 在多物料场景下可能返回嵌套数组(如 details_list),集成时必须用真实数据联调确认。典型错误是按单行写了死映射,结果多物料的核价单只同步了第一条物料的价格。
3. 日期格式。 effectiveDate、invalidDate 在源端是 int 类型,可能是 Unix 秒级、毫秒级,也可能是 yyyyMMdd 整数,三者转换方式完全不同。集成前一定要确认源端字段的真实含义,否则目标端会收到一串 1970-01-01 或者非法日期,导致价目表无法生效。
4. 常量与目标环境不一致。 FCreateOrgId=100、FCurrencyID=PRE001 是固定常量,看起来省事,但如果客户的目标环境不是这套编码,保存就会失败。建议在常量配置处加注释,并允许通过环境变量覆盖。
5. 单据名称重名。 FName 拼接 innerVendorName + 时间戳 能降低重名概率,但时间戳精度不够(如只到分钟)时仍可能撞名。如果客户对单据命名规范有审计要求,建议把时间戳精确到秒,并附上 prcXkNo 后缀。
适用场景与不适用场景
适用:供应商比价结果需要在 ERP 内作为采购价目表取价的场景,特别是制造、零售、贸易类企业;核价单结构稳定、主数据已对齐的成熟系统。不适用:源端核价单频繁作废且无状态字段、目标环境币别/组织未配置、或要求实时取价(秒级)而非 T+1 同步的场景。