查询金蝶物料接口字段手册权威教程:跨方案实战聚合

这个接口解决什么问题

在供应链集成中,物料主数据是采购、销售、库存等所有下游流转的根基。我们需要把金蝶云星空的物料持续、稳定地同步到外部业务系统(管易商品、聚水潭商品等),用于编码对照、单据行物料映射、价格与库存信息获取。本接口承担"金蝶物料统一出口"的角色:通过一个查询策略即可支撑多个目标系统的二次消费,避免每个下游重复拉数。

接口能力总览

• 认证方式:金蝶云星空 WebAPI 鉴权(AppId + AppSecret + 账套编码),需在轻易云连接器中预先配置。
• API: executeBillQuery,HTTP POST,语义为 QUERY(只读)。
• 表单 ID(FormId):固定为 BD_MATERIAL,即物料基础资料。
• 请求参数: FieldKeys(字段白名单)、FormId、FilterString(过滤条件)、Limit(默认 2000)、StartRow(分页起始行,通常取 {{PAGINATION_START_ROW}})、TopRowCount(默认 0 表示返回总行数)。
• 响应结构:JSON 数组,每行包含 FieldKeys 指定的字段;系统会自动补齐 FMasterId、FNumber 等元数据关键字段。
• 分页与增量:基于 Limit + StartRow 分页;增量同步依赖 FilterString,模板形如 FModifyDate>='{{LAST_SYNC_TIME|dateTime}}'。
• 定时策略:常见两种节奏——*/5 7-23 * * *(高频,每 5 分钟)与 */10 8-21 * * *(业务时段,每 10 分钟),按业务量与下游承载力取舍。
• 目标端:Target 配为「写入空操作」(WriteEmpty),属纯查询策略,数据由下游策略消费。

典型字段映射

在轻易云上如何配置

在轻易云数据集成平台里,该接口通常用「金蝶云星空查询适配器」封装为可视化数据源:

1. 连接器:填入金蝶应用 ID/密钥、账套编码、内网域名(私有化环境);支持私有化部署的网关代理。
2. 数据源(Strategy Source):选择适配器 kingdee.executeBillQuery,FormId 选 BD_MATERIAL。
3. 字段映射器:平台会自动读取响应结构,生成 FieldKeys 默认列表;轻易云的字段映射器支持可视化勾选/剔除字段,自动把 FMasterId 注入到 id、FNumber 注入到 number。
4. 过滤与分页:FilterString 模板直接复用 {{LAST_SYNC_TIME|dateTime}};分页参数 StartRow 绑定 {{PAGINATION_START_ROW}}。
5. 元数据:将 metadata.id = FMasterId、metadata.number = FNumber、idCheck = false、autoFillResponse = true 写入 source metadata,后续写入策略可零成本消费。
6. Target 选「写入空操作(WriteEmpty)」,标记本策略为查询型,不写目标端。
7. 调度:在策略时间表里粘 */5 7-23 * * * 或 */10 8-21 * * * 即可。

跨方案实战要点

1. 查询策略与写入策略分层:在多个客户项目里,我们都将"金蝶物料查询"独立成一条策略,Target 写空;下游按需订阅消费,避免反复打金蝶。
2. 必填字段统一封装:FMaterialGroup_FNumber、FErpClsID、FCategoryID、FUseOrgId_FNumber 等必填条件应在轻易云数据源默认参数集中预先绑定,降低脚本出错概率。
3. FilterString 即增量水位:稳的做法是把 FModifyDate 作为增量键,并在轻易云里维护 LAST_SYNC_TIME 状态;遇到历史数据补传时切换为条件拉取而非依赖增量。
4. 多组织隔离优先:金蝶多组织架构下,务必把 FUseOrgId_FNumber 作为查询条件传入,防止跨组织串数据。
5. 跨系统主匹配键选择:B2C 场景(管易/聚水潭)优先用 FNumber;若历史系统迁移可用 FOldNumber 兜底;扩展字段 F_UQRW_Text 适合做幂等关联码。
6. 电商扩展字段要走通:F_PAEZ_Base2(旺店通库存组织)、FBARCODE、FMnemonicCode 等字段在不同客户里差异较大,在轻易云字段映射器中应根据目标系统逐项勾选。

踩坑复盘

1. 必填字段漏传导致 0 行返回:FilterString 中 FUseOrgId_FNumber、FErpClsID 等任一必填项缺位,金蝶会直接返回空集而非报错,排查时极易误判。这里容易翻车,稳妥做法是在轻易云数据源里把它们放进默认参数,避免脚本层遗漏。
2. Limit 与分页边界:默认 2000 看似够用,但物料过万时会触发多次往返;若 StartRow 未取自 {{PAGINATION_START_ROW}},会陷入死循环或漏页,务必使用平台分页变量。
3. idCheck = false 的代价:不校验主键时,一旦上游字段重命名或返回空,平台会去重失败。短期可接受,但生产环境建议显式开启。
4. 增量时间字段时区漂移:FModifyDate 与 LAST_SYNC_TIME 时区不一致时会出现漏数或重复。真实场景中,我们用 UTC 偏移或金蝶服务端时区对齐来规避。
5. 电商扩展字段在不同客户方案中命名不一:F_PAEZ_Base2、F_UQRW_Text 在某零售企业里是私有扩展,迁移到其他客户必须重新对字段映射。轻易云的字段映射器可一键重命名,这里别硬编码。

何时选用

当业务涉及金蝶云星空物料主数据对外分发(电商、商品/仓库对照、销售出库/采购入库单据映射)且需高频增量同步时,本接口是首选。边界:仅做一次性初始化可改用全量导出;若目标系统实时性要求毫秒级,应改走金蝶数据库 CDC 而非 WebAPI 轮询。

接口能力总览

• Authentication: Kingdee WebAPI (AppId + AppSecret + AcctID).
• API: executeBillQuery (POST, QUERY semantics).
• FormId: BD_MATERIAL.
• Request params: FieldKeys, FormId, FilterString, Limit (default 2000), StartRow ({{PAGINATION_START_ROW}}), TopRowCount (default 0).
• Response: JSON array; autoFillResponse: true.
• Pagination: Limit + StartRow; incremental: FilterString with FModifyDate>='{{LAST_SYNC_TIME|dateTime}}'.
• Schedules: */5 7-23 * * * or */10 8-21 * * *.
• Target: WriteEmpty (query-only).