这个接口解决什么问题

在聚水潭与金蝶云星辰的供应链集成里,「品牌」是商品主数据的核心维度。该接口(/jdy/v2/bd/material_brand)用于从星辰侧查询品牌主数据,为商品同步提供品牌对照表、映射依据与校验基准,典型场景包括商品同步时的品牌补全、跨系统对账、品牌分类树构建,属于基础资料同步链路的关键一环。

接口能力总览

认证方式:金蝶云星辰开放平台 OAuth 2.0,需 access_token 拼接请求头,Token 通常有 2 小时有效期。
请求方式:GET,接口路径 /jdy/v2/bd/material_brand。
请求参数:modify_start_time(毫秒时间戳,增量起点)、modify_end_time(毫秒时间戳,增量终点)、page(默认 1)、page_size(默认 20,上限需实测)、enable(可用状态)。
分页/增量:支持分页,典型每页 20~100 条;增量模式依赖修改时间窗口,使用 {{LAST_SYNC_TIME}}000 与 {{CURRENT_TIME}}000 模板变量自动计算。
响应结构:JSON 数组,每条记录包含品牌主键、编码、名称、上级品牌、扩展属性等。
策略类型:QUERY(纯查询),Target 配置为「写入空操作」,不写入任何目标系统。

典型字段映射

字段名	类型	含义	实战注意事项
id	string	品牌主键	内部唯一标识,跨系统映射时通常不用 id,而用 number
number	string	品牌编码	跨系统对账与匹配的核心字段,务必保证唯一性
name	string	品牌名称	业务展示与对账依据
parent_id / parent_number / parent_name	string	上级品牌 ID/编码/名称	用于品牌层级树形结构,子品牌引用上级
brand_id / brand_name / brand_number	string	品牌扩展字段	当接口返回物料视图时与 id/name/number 重复,需以实际返回为准
help_code	string	助记码	快速检索辅助
producing_pace	string	产地	商品产地属性
check_type	string	商品类别	1 普通 2 套装 3 服务
is_batch / is_serial / is_kf_period	string	批次/序列号/保质期	反映物料管理维度
base_unit_id / base_unit_name	string	基础计量单位	关联物料多单位配置
mul_label	object	商品标签对象	嵌套结构,字段映射器需展开
units	object	多单位配置	同上,建议预先在元数据中定义 schema

在轻易云上如何配置

在轻易云数据集成平台中,该接口通常以金蝶云星辰 V2 适配器形式提供,无需手写 HTTP 请求:

创建 QUERY 策略:源系统选「金蝶云星辰 V2」,目标系统选「写入空操作」。
配置数据对象:对象名选「物料品牌」,接口路径自动绑定到 /jdy/v2/bd/material_brand。
字段映射器:轻易云会自动加载响应字段,你可以将 number → brand_code、name → brand_name 一键映射,parent_* 三元组自动透传。
增量配置:把 modify_start_time 绑定到 {{LAST_SYNC_TIME}}000,modify_end_time 绑定到 {{CURRENT_TIME}}000,轻易云的调度引擎会按调度记录自动维护时间游标。
定时调度:建议 */10 7-21 * * *,与星辰侧业务高峰错峰,既保证日内变更及时捕获,也避开夜间 API 限流。

跨方案实战要点

从多个客户的商品同步、客户同步、品牌同步方案里,我们提炼出以下共性经验:

以 number 作为业务主键:id 是系统内主键,跨系统集成中稳定性差,number 才是跨平台对账的锚点。
品牌查询必须在商品同步之前:聚水潭的商品同步链路里,品牌数据通常是依赖项,品牌表先就绪,商品同步才能补全 brand_id。
增量窗口不能太小:金蝶的修改时间戳精度有限,过短窗口可能漏单,实战中 10~15 分钟一轮较为稳妥。
autoFillResponse 会让字段表膨胀:模板自动填充会把物料字段也塞进品牌接口的元数据,实施时务必以 Postman 实测返回为准,清理无关字段。
上级品牌三元组要一起落地:只取 parent_id 会在对账时丢上下文,建议把 parent_number 与 parent_name 同时落库,方便后续做品牌树校验。
嵌套对象( mul_label、units )需要展开策略:字段映射器中需配置「对象展开」,否则下游只能拿到 JSON 字符串,无法做精确匹配。

踩坑复盘

字段重复导致下游冲突:brand_id 与 id、brand_name 与 name 在不同返回里可能并存,直接落库会触发唯一约束冲突。这里稳妥的做法是,在轻易云的字段映射器里加一条「优先级规则」,优先取 number/name/id,重复字段打标记不写入。
增量窗口边界丢单:首次跑策略时 LAST_SYNC_TIME 为空,容易把全量数据塞进一次请求导致超时。建议首次先用 enable=1 全量跑一次建立基线,再切增量。
page_size 过大触发限流:金蝶星辰对单次返回体大小敏感,page_size=500 在某些租户里会 500 报错。这里稳妥的做法是从 20 起步,根据接口耗时再放大。
品牌层级成环:parent_id 指向自身或后辈节点,导致下游构建树时死循环。需要在轻易云的数据质量规则里加「环路检测」,对异常数据打标而非直接写入。
时间戳单位混淆:金蝶返回毫秒,但部分旧版本文档写「秒」,字段映射器若不做单位转换会漏掉全部增量。务必在元数据里显式标注 unit: ms。

何时选用

该接口适用于「需要从星辰侧拉取品牌主数据并与聚水潭等系统做品牌对照」的场景,典型边界是:仅做品牌主数据查询与映射,不做商品/客户同步本身。如果你的目标是商品主数据同步,应搭配商品同步策略,并把品牌表作为依赖项先跑。

金蝶云星辰「查询品牌信息」接口字段手册权威教程