金蝶云星空物料查询接口字段手册权威教程(供应链主数据集成)

这个接口解决什么问题

在零售电商与 ERP 一体化场景里,物料/商品主数据是销售、采购、库存、调拨等所有供应链单据的根基。我们经常需要把 ERP 里的物料档案同步给前端系统,或者反向核对写入结果是否正确。executeBillQuery(查询金蝶物料)接口正是用来按修改时间分页拉取已审核物料基础资料的,是物料主数据双向同步与写入后校验的核心入口。

接口能力总览

• 认证方式:金蝶云星空 OAuth2.0 / 应用密钥双因子鉴权,在轻易云适配器里封装为统一的凭证配置面板,不需要手写 token 换取逻辑。
• 请求结构:POST 到 executeBillQuery 端点,FormId 固定为 BD_MATERIAL,通过 FilterString 组合过滤条件,典型为 FUseOrgId='7000' AND FDocumentStatus='C' AND FModifyDate>='{{last_run_time}}'。
• 响应结构:金蝶标准的 Result → Rows 数组,每个 Row 是一组字段键值对,关联对象用 字段.子属性 形式返回(如 FBaseUnitId.FNumber)。
• 分页/增量模式:基于 Limit 与 StartRow 的游标分页,配合 FModifyDate 实现增量;轻易云默认每页 2000 条,自动按修改时间滚动游标,断点续传由平台托管。
• 调度节奏:策略级 crontab 1-59/5 7-23 * * *,工作时段每 5 分钟一轮,夜间降频。

典型字段映射

在轻易云上如何配置

• 适配器:轻易云内置「金蝶云星空 executeBillQuery」适配器,填入 AppId/AppSecret/租户凭证即可。FormId 选择 BD_MATERIAL,平台会自动注入分页游标与增量游标。
• 字段映射器:平台把 FMasterId 自动识别为 id、FNumber 识别为 number,其余字段通过「字段_子属性」语法展开(如 FBaseUnitId.FNumber → FBaseUnitId_FNumber)。轻易云的字段映射器会自动生成目标端的列结构,无需手写 JSON。
• 过滤模板:内置「按修改时间增量」模板,只需配置使用组织与审核状态常量。
• Target 配置:本类纯查询策略,Target 选「写入空操作」(NoOp),链路只跑抽取与落中间库。
• 调度:平台提供可视化 crontab 编辑器,与 1-59/5 7-23 * * * 等表达式等价。

跨方案实战要点

1. 以 FMasterId+FNumber 复合做主键:真实场景中,单纯靠 FNumber 在跨组织场景会撞码,主键与编码双写更稳妥。
2. 必须过滤 FDocumentStatus='C':审核中/草稿态的物料字段值会变化,拉进来反而污染下游。
3. 增量游标必须保存到可靠存储:轻易云默认把 FModifyDate 上次值落到策略状态表,不要让目标端覆盖回写。
4. 关联对象字段要二次展开:FBaseUnitId.FNumber 不会自动扁平化,要么用映射器重命名规则,要么在脚本里显式拆。
5. 单位与数值字段统一换算:长度/重量常带 ERP 单位,落到前端 SKU 前必须做单位字典对齐,这是最容易翻车的地方。
6. 写入后开启校验:策略名「数据写入后开启」的实践,意味着查询策略先于写入策略空跑一次,确认无重复再正式跑链路,降级回归成本最低。

踩坑复盘

• 踩坑 1:未过滤审核状态,导致下游收到草稿态物料,触发创建库存档案失败。应对:FilterString 强约束 FDocumentStatus='C',并在轻易云过滤模板里勾选「仅已审核」。
• 踩坑 2:关联字段直接当 string 用:FBaseUnitId 整段返回的是对象,不展开就写库会塞进 JSON 字符串。应对:用轻易云字段映射器的「_FNumber 展开规则」自动扁平化。
• 踩坑 3:增量时间窗口被回退:服务器时钟漂移导致部分记录漏拉。应对:轻易云里把增量游标加上 5 分钟回退容差,避免边界丢失。
• 踩坑 4:多组织物料重复:未带 FUseOrgId 过滤,跨组织物料被多次写入。应对:策略里固定使用组织,或者按组织维度拆策略。
• 踩坑 5:调度时段覆盖夜间批处理:5 分钟轮询撞上 ERP 夜间结账,响应慢甚至超时。应对:夜间时段降频,白天恢复高频,平台提供时段化调度配置。

何时选用

适用场景:ERP ↔ 前端系统物料主数据双向同步、写入后一致性校验、跨组织物料分发、新系统冷启动批量拉取物料。不适用:需要实时单条查询(应走单据详情接口)、草稿态物料采集,以及非 BD_MATERIAL 业务对象的同步。