金蝶云星辰商品查询接口权威教程:从字段手册到轻易云配置全攻略
聚水潭金蝶云星辰商品主数据供应链集成轻易云增量同步字段手册
这个接口解决什么问题
在聚水潭与金蝶云星辰的供应链集成场景里,「查询商品信息」(/jdy/v2/bd/material)承担了商品主数据枢纽的角色。它负责把星辰侧的物料档案拉出来,与聚水潭商品编码建立对照,从而支撑销售出库、采购入库、盘点等业务单据的物料映射与对账,是整个集成链路上的「字典表」来源。
接口能力总览
- 认证方式:金蝶云星辰开放平台 OAuth2.0 授权,使用 AppKey/AppSecret 换取 access_token 后带入请求头。
- 请求结构:GET 请求,路径
/jdy/v2/bd/material,参数支持modify_start_time、modify_end_time(毫秒时间戳)、page、page_size。 - 响应结构:外层
data数组承载商品列表,每条记录包含 id、number、name 等字段;分页信息由total_count体现。 - 分页/增量模式:基于修改时间窗口的增量拉取 + 标准分页;通常结合
LAST_SYNC_TIME与CURRENT_TIME变量实现。 - 明细接口:
/jdy/v2/bd/material_detail用于补全多单位、辅助属性等扩展信息。
典型字段映射
| 字段名 | 类型 | 含义 | 实战注意事项 |
|---|---|---|---|
| id | string | 星辰内部主键 | 仅作系统内唯一标识,跨系统对账请使用 number |
| number | string | 商品编码 | 与聚水潭商品编码对照的核心字段,建议全局唯一 |
| name | string | 商品名称 | 展示与对账依据,注意同名情况 |
| parent_id/number/name | string | 上级分类 | 树形结构时需要递归处理分类层级 |
| base_unit_id/number/name | string | 基础计量单位 | 单位换算的根基,需建立与聚水潭单位映射表 |
| units | object | 多单位配置 | 含辅助单位与换算比例,启用多单位时必解析 |
| is_multi_unit | string | 是否多单位 | 决定是否展开 units 对象 |
| barcode | string | 主条形码 | 与聚水潭条码字段双向对账 |
| check_type | string | 商品类别:1普通/2套装/3服务 | 套装商品需要展开子件 |
| brand_id/number/name | string | 品牌维度 | 用于品牌维度筛选与统计 |
| model | string | 规格型号 | 与聚水潭规格字段对照 |
| help_code | string | 助记码 | 快速检索辅助字段 |
| is_serial / is_batch / is_kf_period / kf_period_type | string | 序列号/批次/保质期 | 决定库存业务逻辑分支 |
| is_asst_attr / is_show_aux_barcode | string | 辅助属性 | 影响 SKU 维度展开 |
| mul_label | object | 商品标签集合 | 用于多维分类 |
在轻易云上如何配置
在轻易云数据集成平台里,这个接口已经预封装为「金蝶云星辰-查询商品」适配器,工程师只需配置租户授权信息即可启用。
- 数据源配置:选择「金蝶云星辰 V2」适配器,填入 AppKey/AppSecret 与账套信息,轻易云会自动维护 token 刷新。
- 请求参数编排:轻易云支持把
LAST_SYNC_TIME与CURRENT_TIME配置为内置时间变量,按*/10 7-22 * * *节奏触发增量拉取。 - 字段映射器:轻易云的字段映射器会自动识别
id、number作为主键与编码字段,并预生成与聚水潭商品对象的通用映射模板(material_id、material_code、material_name 等)。 - 空操作 Target:因为该策略是纯查询,Target 配置为「写入空操作」,仅用于把物料数据落到轻易云中转库,供后续单据同步策略消费。
- 明细补全钩子:可在轻易云里配置「明细触发器」,自动调用
material_detail拉取多单位与辅助属性。
跨方案实战要点
我们在多个客户项目里沉淀出以下共性经验:
- 编码优先于 ID:跨系统对账永远以
number为主键,id仅用于星辰内部追溯,避免因 ID 变更导致对账失败。 - *时间戳必须 1000:金蝶接口要求毫秒级时间戳,传入秒级时间戳会直接返回空集,这是最常见的翻车点。
- 分页 page_size 控制在 20–50:过大容易触发限流,过小会增加请求次数。
- 多单位对象必须展开:直接落库的
units无法在下游单据中换算,要在轻易云里通过脚本展开成扁平字段。 - check_type=2 套装商品需特殊处理:套装需要递归展开子件,否则出库数量会失真。
- 增量窗口要做兜底:定时任务间隔内如果漏单,需保留 5–10 分钟重叠窗口,避免边界数据丢失。
踩坑复盘
- 时间戳单位错误:误传秒级时间戳导致接口返回空数据。稳妥的做法是在轻易云变量里统一
*1000后再下发。 - page_size 过大触发限流:曾有项目设置为 200,频繁收到 429。在轻易云里调整到 50 后稳定运行。
- 多单位字段未展开导致库存失真:units 对象直接进单据后,下游系统无法换算。务必在轻易云脚本节点做扁平化处理。
- 增量边界漏单:每 10 分钟一跑,相邻窗口无重叠时存在边界漏数风险。建议保留 5 分钟重叠并用
modify_end_time兜底。 - 套装商品未递归:check_type=2 的套装仅拉了主件,销售出库时数量对不上。应在轻易云里加一层子件展开逻辑。
何时选用
该接口适用于以金蝶云星辰为商品主数据源、与聚水潭等前端系统进行供应链集成的场景,特别是需要高频增量同步物料档案、支撑销售/采购/库存单据映射的业务。若星辰不是物料主数据源,或仅需一次性全量导入,则不必启用该增量策略。
本文为原创内容,转载请注明出处:https://www.qeasy.cloud/insights/engineering/hb-p2-397-e1cf