金蝶云星辰商品分类查询接口字段手册权威教程(聚水潭集成视角)

这个接口解决什么问题

在零售 ERP 集成中,商品分类是商品主数据的两大支柱之一。我们在做聚水潭与金蝶云星辰的对接时,商品分类映射往往先于商品本身——分类没对齐,SKU 同步无从谈起。/jdy/v2/bd/material_group 接口正是用来按修改时间分页批量拉取金蝶云星辰的物料分组(商品分类),它支持增量查询与树形层级识别,是构建分类映射表、初始化分类体系以及下游商品同步的前置依赖。

接口能力总览

• 认证方式:金蝶云星辰 V2 WebAPI 标准 OAuth/应用授权,需先通过授权策略换取 access_token。
• 请求结构:GET 请求 /jdy/v2/bd/material_group,支持时间窗过滤(modify_start_time、modify_end_time,格式 yyyy-MM-dd HH:mm:ss)与分页参数(page 默认 1,page_size 默认 50,建议调至 100-200 以减少请求次数)。
• 响应结构:返回 JSON 数组,每条记录即一个分类;字段在 data[] 中平铺,主键 id、编码 number 在 metadata 中单独标注。
• 明细接口:/jdy/v2/bd/material_group_detail 可按 id 拉取单条详情,排查字段含义时常用。
• 分页与增量:标准页码分页;增量依赖 modify_start_time / modify_end_time 时间戳,业务时段通常配 8:00–20:00 每 5 分钟一轮(*/5 8-20 * * *)。
• 策略类型:纯 QUERY(写入空操作),目标端不落库,仅作为其他写入策略的映射数据源。

典型字段映射

在轻易云上如何配置

在轻易云数据集成平台里,该接口通常以「金蝶云星辰适配器」封装:在源系统组件中选定 Kingdee.YXC / bd.material_group,平台会自动注入授权头与分页器。modify_start_time 默认取上一次成功调用的截止时间,无需手动维护游标。

字段映射器会自动将 id/number/name/level/is_leaf 暴露为标准输出列,若目标是聚水潭,可在可视化画布上直接拖拽到「商品分类」目标字段。Target 配置选择「写入空操作」即代表纯查询策略,数据只进轻易云的中间表,供后续写入策略(如「金蝶星辰商品→聚水潭商品」)按 id 关联引用。

调度方面,建议把 crontab 设为 */5 8-20 * * *,与上游商品写入策略错峰,避免授权刷新与大批量查询撞车。

跨方案实战要点

1. id 与 number 都要保留:id 稳定但跨系统不可读,number 可读但可能被运维调整;两者并存最稳妥。
2. 分页阈值不要拉满:金蝶星辰 V2 单页 200 条以上时偶发超时,真实场景中我们通常把 page_size 设在 100。
3. 增量时间窗要预留重叠:每轮查询的 modify_start_time 比上一轮截止时间提前 1-2 分钟,防止边界记录被漏掉。
4. 树形结构用 is_leaf 驱动:不要依赖 level 数值判断是否还有下级,层级深度可能不连续,is_leaf 更可靠。
5. 授权先行:跨方案都把「获取星辰最新授权」作为 sequence=A 的前置策略,后续查询依赖其输出的 token,务必先调度它。
6. 依赖关系要显式声明:商品写入策略通常 depends_on 商品分类查询,否则会出现「分类未到、商品先写」的脏数据。

踩坑复盘

• 这里容易翻车——同名分类合并错误:两个 id 不同但 name 相同的分类被误判为同一记录,导致下游聚水潭分类被覆盖。稳妥做法是始终以 id 为对账键。
• 时间时区漂移:增量漏单的常见原因是金蝶返回的 modify_time 与轻易云传入的 modify_start_time 时区不一致,务必统一为北京时间。
• is_leaf 大小写陷阱:某客户项目里,金蝶在批量接口返回大写 True/False,字符串比较直接翻车,这里一定要做 str(...).lower() 归一化。
• 授权过期导致静默失败:token 默认 2 小时过期,若授权策略未先于查询策略执行,查询会拿到 401 但轻易云默认不重试,需要把授权策略纳入 DAG 依赖。
• page_size 过大触发限流:某零售企业曾把 page_size 调到 500,触发金蝶侧 QPS 限流,整批任务挂起。回到 100 后稳定运行。

何时选用

该接口适用于「分类先行」的零售 ERP 集成场景,典型如某零售企业将金蝶云星辰作为商品主数据中心、聚水潭作为前端店铺系统时的初始化与日常同步。不适用于需要写入分类的场景——它是纯查询,若要回写金蝶,需另选 save 接口并配套授权与字段映射。