这个接口解决什么问题

在零售与电商供应链集成场景里,商品主数据是连接 ERP 与前端业务系统的中枢。我们常需要把金蝶云星辰里的物料(商品)主数据,与旺店通、电商平台等系统的商品/SKU 做编码对照与字段映射,为后续销售订单、采购订单、库存同步提供基础资料校验支撑。/jdy/v2/bd/material 这个查询接口正是为此而生,支持按修改时间增量拉取、分页遍历,是商品主数据联动的核心入口。

接口能力总览

所属系统:金蝶云星辰 V2 WebAPI,基础资料-物料
接口路径:/jdy/v2/bd/material(列表查询)、/jdy/v2/bd/material_detail(按 id 详情查询)
请求方法:GET
策略类型:QUERY 纯查询,Target 端写入空操作,不落库目标系统
认证方式:金蝶云星辰 OpenAPI 标准的 access_token 鉴权(需通过 /jdy/v2/auth/login 获取)
增量参数:modify_start_time、modify_end_time,均为毫秒级时间戳
分页参数:page(默认 1)、page_size(默认 20,实测建议单次不超过 100)
主键字段:id
编码字段:number
定时任务:典型配置每日凌晨 3:15 执行,错峰跑批避免业务高峰期

典型字段映射

字段名	类型	含义	实战注意事项
id	string	物料主键 ID	跨系统映射的唯一锚点,务必作为对照表主键保存
number	string	物料业务编码	与旺店通 SKU 编码、销售订单商品编码做映射,前端常用
name	string	物料名称	显示用,注意特殊字符与空格清洗
parent_id / parent_number / parent_name	string	上级物料/分类	构建商品树形层级,与类目映射时使用
model	string	规格型号	与旺店通规格字段一一对应
barcode	string	主条形码	扫码场景关键字段,空值需在映射中兜底
url	string	商品主图 URL	注意防盗链,部分 CDN 域名需配白名单
help_code	string	助记码	检索加速,可忽略但保留
remark	string	描述/备注	长文本字段,注意长度截断
check_type	string	商品类别:1 普通 2 套装 3 服务	区分业务类型,套装商品拆单时需特别注意
brand_id / brand_number / brand_name	string	品牌三件套	品牌维度统计与筛选依赖
producing_pace	string	产地	部分行业合规必填
base_unit_id / base_unit_number / base_unit_name	string	基本计量单位	与旺店通计量单位映射,多单位场景需展开 units
is_multi_unit	string	是否多单位	true 时 units 字段才有值,需做空值防御
is_serial / is_batch / is_kf_period / is_weight	string	序列号/批次/保质期/称重开关	决定后续库存与订单业务逻辑分支
is_asst_attr / is_show_aux_barcode	string	辅助属性开关	颜色尺码等多 SKU 场景需关注
kf_period_type	string	保质期单位:1 天 2 月 3 年	食品/药品行业必看
mul_label	object	商品标签对象/列表	复杂结构,映射时建议 JSON 化落库
units	object	多计量单位配置	含换算率,跨单位换算的关键

在轻易云上如何配置

在轻易云数据集成平台里,这个接口的调用通常采用「金蝶云星辰 V2 适配器」进行封装。我们只需在适配器中选择「物料查询」动作,填入租户授权信息(access_token 自动托管),即可直接拉取数据。

字段映射方面,轻易云的字段映射器会自动把金蝶的 id、number、name 等标准字段映射到目标表的标准列,对于 units、mul_label 这类 object 复杂字段,平台提供 JSON 解析节点,可一键展开为明细行。增量同步只需在调度配置里勾选「按修改时间增量」,平台会自动管理游标水位,无需手动维护时间戳。Target 端选择「写入空操作」即可实现纯查询策略,数据可走轻易云的「数据预览」或「日志中心」做即时校验。

跨方案实战要点

主键先行,先建对照表再谈业务:任何跨系统集成,先用 id + number 把商品对照表跑通,后续订单、库存同步都基于这张表。在多个客户项目里,这一步偷懒几乎都会在后期翻车。
增量 + 全量组合:首次全量拉取建立基线,之后按 modify_start_time / modify_end_time 做日级增量。稳妥的做法是保留近 7 天的回溯窗口,防止漏单。
分页大小控制:金蝶 API 单页默认 20 条,实测 page_size 设到 100 性能最优,过大会触发限流。建议轻易云调度里固定 page_size=100。
object 字段预处理:units、mul_label 这类嵌套对象,不要直接当成字符串落库,务必在轻易云的转换器里展开成明细行或多值字段。
空值与默认值兜底:barcode、help_code 等字段常为空,在映射到旺店通时必须设默认值(如空字符串),否则下游校验会失败。
跑批时间错峰:金蝶云星辰的物料量级在百万级以下时,凌晨 3:15 跑批通常没问题;但若物料量级到百万以上,建议拆分到多个夜间窗口或启用轻易云的并发分片。

踩坑复盘

坑 1:忽略 page_size 导致漏数据。某客户把 page_size 设为 50,但实际商品总数非 50 的倍数,最后一页未做循环终止判断,导致部分物料漏拉。稳妥做法是按返回 total 字段做循环终止。
坑 2:毫秒时间戳单位搞错。金蝶增量参数要求毫秒,但有的工程师传了秒级时间戳,导致增量窗口永远是过去几十年,全量重拉。务必确认时间戳位数。
坑 3:套装商品 check_type=2 未单独处理。套装商品在旺店通里通常要拆成多个普通商品,若直接 1:1 映射,后续订单同步会出库存不一致。
坑 4:多单位商品 units 字段未展开。金蝶的多单位换算关系藏在 units 对象里,若只取 base_unit_name,后续跨单位销售会算错。
坑 5:access_token 过期未刷新。金蝶云星辰的 token 通常 2 小时过期,长跑批任务到一半 401。在轻易云里通过平台托管 token 自动续期,基本不会踩这个坑。

何时选用

当你需要做旺店通与金蝶云星辰的供应链集成,或电商、零售场景下的商品主数据联动、跨系统编码对照、订单/库存同步前的商品校验时,这个接口是首选。但若目标只是写入金蝶云星辰做商品新增/修改,应改用物料保存接口;若要查询库存,应走库存查询接口,本接口只覆盖主数据维度。

金蝶云星辰商品查询接口字段手册权威教程（P2-173/P2-287）