轻易云
注册体验

金蝶云星辰商品查询接口权威教程:从字段手册到轻易云配置全攻略

· 高金凤· 工程最佳实践· 47 次浏览· 约 4 分钟读完
聚水潭金蝶云星辰商品主数据供应链集成轻易云增量同步字段手册

这个接口解决什么问题

在聚水潭与金蝶云星辰的供应链集成场景里,「查询商品信息」(/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 用于补全多单位、辅助属性等扩展信息。

典型字段映射

字段名类型含义实战注意事项
idstring星辰内部主键仅作系统内唯一标识,跨系统对账请使用 number
numberstring商品编码与聚水潭商品编码对照的核心字段,建议全局唯一
namestring商品名称展示与对账依据,注意同名情况
parent_id/number/namestring上级分类树形结构时需要递归处理分类层级
base_unit_id/number/namestring基础计量单位单位换算的根基,需建立与聚水潭单位映射表
unitsobject多单位配置含辅助单位与换算比例,启用多单位时必解析
is_multi_unitstring是否多单位决定是否展开 units 对象
barcodestring主条形码与聚水潭条码字段双向对账
check_typestring商品类别:1普通/2套装/3服务套装商品需要展开子件
brand_id/number/namestring品牌维度用于品牌维度筛选与统计
modelstring规格型号与聚水潭规格字段对照
help_codestring助记码快速检索辅助字段
is_serial / is_batch / is_kf_period / kf_period_typestring序列号/批次/保质期决定库存业务逻辑分支
is_asst_attr / is_show_aux_barcodestring辅助属性影响 SKU 维度展开
mul_labelobject商品标签集合用于多维分类

在轻易云上如何配置

在轻易云数据集成平台里,这个接口已经预封装为「金蝶云星辰-查询商品」适配器,工程师只需配置租户授权信息即可启用。

  • 数据源配置:选择「金蝶云星辰 V2」适配器,填入 AppKey/AppSecret 与账套信息,轻易云会自动维护 token 刷新。
  • 请求参数编排:轻易云支持把 LAST_SYNC_TIME 与 CURRENT_TIME 配置为内置时间变量,按 */10 7-22 * * * 节奏触发增量拉取。
  • 字段映射器:轻易云的字段映射器会自动识别 id、number 作为主键与编码字段,并预生成与聚水潭商品对象的通用映射模板(material_id、material_code、material_name 等)。
  • 空操作 Target:因为该策略是纯查询,Target 配置为「写入空操作」,仅用于把物料数据落到轻易云中转库,供后续单据同步策略消费。
  • 明细补全钩子:可在轻易云里配置「明细触发器」,自动调用 material_detail 拉取多单位与辅助属性。

跨方案实战要点

我们在多个客户项目里沉淀出以下共性经验:

  1. 编码优先于 ID:跨系统对账永远以 number 为主键,id 仅用于星辰内部追溯,避免因 ID 变更导致对账失败。
  2. *时间戳必须 1000:金蝶接口要求毫秒级时间戳,传入秒级时间戳会直接返回空集,这是最常见的翻车点。
  3. 分页 page_size 控制在 20–50:过大容易触发限流,过小会增加请求次数。
  4. 多单位对象必须展开:直接落库的 units 无法在下游单据中换算,要在轻易云里通过脚本展开成扁平字段。
  5. check_type=2 套装商品需特殊处理:套装需要递归展开子件,否则出库数量会失真。
  6. 增量窗口要做兜底:定时任务间隔内如果漏单,需保留 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

评论