金蝶云星辰商品查询接口(获取单位)字段手册权威教程
聚水潭金蝶云星辰商品主数据单位换算聚水潭集成供应链集成字段手册
这个接口解决什么问题
在聚水潭与金蝶云星辰的供应链集成中,商品主数据是后续库存、订单、采购单据流转的基石。金蝶云星辰的商品档案承载了丰富的多单位、辅助属性、保质期等业务维度。本接口专门用于批量查询商品主数据并带回计量单位信息,为跨系统商品编码对齐、单位换算、套装拆解提供权威数据源。
接口能力总览
- 认证方式:采用金蝶云星辰开放平台 OAuth2.0 授权码模式,需提前申请应用 AppKey/AppSecret 并完成租户授权。
- 请求结构:HTTP POST,入参支持
org_id(组织ID)、page(页码)、page_size(每页条数)、last_modified_time(增量时间戳)等过滤条件。 - 响应结构:JSON,顶层包含
data(商品列表)与total(总条数);每条商品包含基础字段、单位对象与扩展属性。 - 分页/增量模式:支持传统分页与
last_modified_time增量拉取,推荐每页 100~200 条。
典型字段映射
| 字段名 | 类型 | 含义 | 实战注意事项 |
|---|---|---|---|
| id | string | 商品唯一标识 | 主键,跨系统比对必须 |
| number | string | 商品编码 | 聚水潭 SKU 映射主依据 |
| name | string | 商品名称 | 注意特殊字符转义 |
| base_unit_id / base_unit_number / base_unit_name | string | 基础计量单位 | 单位映射三件套,需建立对照表 |
| units | object | 多单位配置 | 含换算比例,核心字段 |
| is_multi_unit | string | 是否多单位 | 决定是否解析 units |
| check_type | string | 商品类别 | 1=普通 2=套装 3=服务 |
| barcode | string | 主条形码 | 扫码场景必备 |
| is_serial / is_batch / is_kf_period | string | 序列号/批次/保质期 | 库存与批次集成关键开关 |
| kf_period_type / kf_period | string/int | 保质期单位与数值 | 1=天 2=月 3=年 |
| brand_id / brand_number / brand_name | string | 品牌维度 | 商品分析常用 |
| parent_id / parent_number | string | 上级分类 | 用于搭建商品层级 |
| price_cost_price | float | 参考成本 | 价格策略集成参考 |
| model / help_code / remark | string | 规格/助记码/备注 | 检索与展示辅助 |
在轻易云上如何配置
在轻易云数据集成平台中,金蝶云星辰商品查询接口已被封装为可视化适配器,只需在「数据源」中选择「金蝶云星辰 V2」并完成授权即可使用。平台默认提供分页迭代器与增量时间戳管理,无需手写循环逻辑。字段映射器会自动将 units 这种嵌套对象展开为多行结构,便于下游聚水潭商品表的写入。平台还内置单位映射转换节点,可将 base_unit_number 与聚水潭单位体系做一次对照,完成单位自动换算。
跨方案实战要点
- 编码为主,名称为辅:跨系统对账务必以
number作为唯一键,名称易出现空格、全半角差异。 - 单位映射先建表:在项目启动期就整理出「金蝶单位 ↔ 聚水潭单位」对照表,避免下游换算时数据错位。
- 多单位按需展开:
is_multi_unit=true时才解析units,否则直接取base_unit_*,减少冗余数据写入。 - 增量字段统一:
last_modified_time建议以 UTC 存储,避免跨时区漏单。 - 套装商品另走通道:
check_type=2的套装商品建议拆分单条策略处理,避免与普通商品混跑导致子件错配。 - 批次/保质期开关联动:启用了
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