轻易云
注册体验

金蝶云星辰商品查询接口(获取单位)字段手册权威教程

· 谢锴斌· 工程最佳实践· 7 次浏览· 约 4 分钟读完
聚水潭金蝶云星辰商品主数据单位换算聚水潭集成供应链集成字段手册

这个接口解决什么问题

在聚水潭与金蝶云星辰的供应链集成中,商品主数据是后续库存、订单、采购单据流转的基石。金蝶云星辰的商品档案承载了丰富的多单位、辅助属性、保质期等业务维度。本接口专门用于批量查询商品主数据并带回计量单位信息,为跨系统商品编码对齐、单位换算、套装拆解提供权威数据源。

接口能力总览

  • 认证方式:采用金蝶云星辰开放平台 OAuth2.0 授权码模式,需提前申请应用 AppKey/AppSecret 并完成租户授权。
  • 请求结构:HTTP POST,入参支持 org_id(组织ID)、page(页码)、page_size(每页条数)、last_modified_time(增量时间戳)等过滤条件。
  • 响应结构:JSON,顶层包含 data(商品列表)与 total(总条数);每条商品包含基础字段、单位对象与扩展属性。
  • 分页/增量模式:支持传统分页与 last_modified_time 增量拉取,推荐每页 100~200 条。

典型字段映射

字段名类型含义实战注意事项
idstring商品唯一标识主键,跨系统比对必须
numberstring商品编码聚水潭 SKU 映射主依据
namestring商品名称注意特殊字符转义
base_unit_id / base_unit_number / base_unit_namestring基础计量单位单位映射三件套,需建立对照表
unitsobject多单位配置含换算比例,核心字段
is_multi_unitstring是否多单位决定是否解析 units
check_typestring商品类别1=普通 2=套装 3=服务
barcodestring主条形码扫码场景必备
is_serial / is_batch / is_kf_periodstring序列号/批次/保质期库存与批次集成关键开关
kf_period_type / kf_periodstring/int保质期单位与数值1=天 2=月 3=年
brand_id / brand_number / brand_namestring品牌维度商品分析常用
parent_id / parent_numberstring上级分类用于搭建商品层级
price_cost_pricefloat参考成本价格策略集成参考
model / help_code / remarkstring规格/助记码/备注检索与展示辅助

在轻易云上如何配置

在轻易云数据集成平台中,金蝶云星辰商品查询接口已被封装为可视化适配器,只需在「数据源」中选择「金蝶云星辰 V2」并完成授权即可使用。平台默认提供分页迭代器与增量时间戳管理,无需手写循环逻辑。字段映射器会自动将 units 这种嵌套对象展开为多行结构,便于下游聚水潭商品表的写入。平台还内置单位映射转换节点,可将 base_unit_number 与聚水潭单位体系做一次对照,完成单位自动换算。

跨方案实战要点

  1. 编码为主,名称为辅:跨系统对账务必以 number 作为唯一键,名称易出现空格、全半角差异。
  2. 单位映射先建表:在项目启动期就整理出「金蝶单位 ↔ 聚水潭单位」对照表,避免下游换算时数据错位。
  3. 多单位按需展开:is_multi_unit=true 时才解析 units,否则直接取 base_unit_*,减少冗余数据写入。
  4. 增量字段统一:last_modified_time 建议以 UTC 存储,避免跨时区漏单。
  5. 套装商品另走通道:check_type=2 的套装商品建议拆分单条策略处理,避免与普通商品混跑导致子件错配。
  6. 批次/保质期开关联动:启用了 is_batch 或 is_kf_period 的商品,下游库存模块必须同步开启对应能力,否则会出现库存冻结异常。

踩坑复盘

  • 单位换算比例丢失:某零售企业初次集成时只同步了基础单位,忽略了 units 中的换算比例,导致整箱发货时被聚水潭按个计价。稳妥做法是:多单位字段必须全量下发,换算比例写入自定义字段。
  • 增量时间戳格式不一致:金蝶返回的是本地时间字符串,聚水潭写入使用 UTC 时间戳,这里容易翻车。务必在中间层做一次时间标准化。
  • 套装商品子件为空:check_type=2 时,若 units 内子件数组缺失,会在聚水潭端造成「空 SKU」。处理时需在轻易云里加一条兜底规则,空数组则跳过并告警。
  • 商品类别字段类型错位:部分金蝶版本把 check_type 返回为 int,部分为 string,平台字段映射器建议统一转 string 再做枚举比对。
  • 组织隔离失效:多组织账号下未传 org_id 会返回全部组织的商品,引发越权同步。务必显式传参。

何时选用

本接口适用于「聚水潭 ↔ 金蝶云星辰」双向供应链集成中的商品主数据初始化与日常同步,尤其是需要单位换算、套装拆解、批次与保质期同步的场景。对于纯订单数据流转、且不涉及单位换算的轻量集成,可直接调用订单接口,不必引入商品主数据全量同步。

本文为原创内容,转载请注明出处:https://www.qeasy.cloud/insights/engineering/hb-p2-226-5e5f

评论