金蝶云星辰物料查询接口权威教程：从字段映射到轻易云集成实战

这个接口解决什么问题

在零售与电商集成场景里，物料主数据是采购、销售、库存、出入库所有业务链路的基石。/jdy/v2/bd/material 是金蝶云星辰 V2 提供的物料分页查询 WebAPI，支持按修改时间增量拉取。在多个真实客户项目中，我们用它把金蝶物料同步到轻易云数据集成平台，与旺店通货品做编码对照、销售订单字段映射、库存校验、商品主数据同步等。一个干净的物料主数据流，后续所有单据流转才不会翻车。

接口能力总览

• 认证方式：金蝶云星辰 V2 WebAPI 标准鉴权，凭证由轻易云连接器统一托管。
• 请求方法：GET /jdy/v2/bd/material
• 策略类型：QUERY_ONLY（纯查询，Target 端配置为空操作，不回写目标系统）
• 分页参数：page（默认 1）、page_size（默认 100 条）。
• 增量参数：modify_start_time / modify_end_time，毫秒级时间戳，对应轻易云变量 LAST_SYNC_TIME、CURRENT_TIME。
• 定时调度：典型配置为每日 02:03 执行（crontab 3 2 * * *），避开业务高峰期。
• 响应结构：分页返回物料列表，主键 id、业务编码 number，辅以层级、品牌、计量单位、批次/保质期等扩展属性。

典型字段映射

在轻易云上如何配置

在轻易云数据集成平台里，金蝶云星辰物料查询接口通常通过以下方式封装：

1. 适配器选择：源系统选「金蝶云星辰 V2」，轻易云内置了 /jdy/v2/bd/material 的请求模板，直接填入连接器凭证即可。
2. 策略类型：选 QUERY_ONLY，Target 端配置「写入空操作」，平台只把数据落到中间库供其他策略消费。
3. 增量配置：轻易云的调度变量 LAST_SYNC_TIME、CURRENT_TIME 自动注入到 modify_start_time / modify_end_time，毫秒级时间戳无需手工转换。
4. 分页控制：page_size 默认为 100，轻易云的字段映射器会自动翻页并合并结果，无需写循环脚本。
5. 字段映射器：id/number 直接映射为 material_id/material_code；object 类型的 units、mul_label 在轻易云里可用 JSON 展开器按子字段映射到旺店通对应字段。
6. 依赖编排：本策略常作为「查询旺店通货品」的对码前置任务，通过 depends_on 编排先后顺序。

跨方案实战要点

1. number 是跨系统对码的生命线：所有客户方案里，number 都是金蝶物料 ↔ 旺店通货品/规格的主关联键，轻易云的字段映射器默认把它标为业务编码字段。
2. 增量窗口别跨天：多个方案验证过，把 modify_end_time 设为 CURRENT_TIME - 缓冲值（如 5 分钟）比直接用 CURRENT_TIME 更稳，避免边界数据漏拉。
3. page_size 100 是性价比甜点：实测 100 条/页在金蝶限流内最稳；超过 200 易触发接口限流。
4. object 字段提前展平：units、mul_label 这种 object 在轻易云里务必先展开，否则下游策略拿不到换算率和标签值。
5. check_type=2 的套装物料要拆解：多个零售客户都遇到过套装物料直接对码导致库存错乱，需要在轻易云里加一条转换器拆成子件。
6. 定时任务放在凌晨：客户实测 02:03 跑批时金蝶侧负载最低，避开业务高峰降低限流概率。

踩坑复盘

1. 毫秒 vs 秒时间戳混用：金蝶要毫秒，但有些客户的旧脚本传了秒级时间戳，导致增量窗口错位——这里容易翻车，稳妥的做法是在轻易云的变量映射里强制乘 1000。
2. parent_id 为空字符串：金蝶根级物料 parent_id 不是 null 而是空字符串，映射到旺店通类目时会变成空值，记得在轻易云里做空串归一化。
3. units 换算率反向理解：units 里的换算率方向不是固定的，客户实战中遇到过反的，稳妥的做法是同步后跑一次抽样校验。
4. barcode 多条码只返回主码：金蝶只回主条码，多条码在辅助属性里——需要打开 is_show_aux_barcode 配合辅助属性全量拉取。
5. 批次/保质期字段是开关不是值：is_batch、is_kf_period 只是启用标志，具体批号和到期日在库存接口里——别在物料同步阶段去解析它们。

何时选用

适用于旺店通/电商前端 ↔ 金蝶云星辰 ERP 的物料主数据同步、编码对照、基础资料分发场景；当需要按修改时间增量拉取、做对码映射、为后续订单与库存业务打底时，本接口是首选。若需实时库存或批号明细，应走库存查询接口而非物料接口。