聚水潭供应商查询接口字段手册权威教程

这个接口解决什么问题

在零售与分销场景里，供应商主数据是采购订单、采购入库、采购退货等供应链单据的基础资料。我们在做聚水潭与金蝶云星空的供应链集成时，常常需要把聚水潭的供应商档案拉取到中间层，与金蝶的 BD_Supplier 建立编码对照，从而支撑后续采购单据的字段映射与档案同步校验。该接口正是用于按修改时间增量查询聚水潭供应商主数据，是供应链集成中「供应商联动查询」的标准入口。

接口能力总览

聚水潭供应商查询接口 /open/supplier/query 为 POST 请求，策略类型为 QUERY（纯查询，不写入目标系统）。

• 认证方式：聚水潭开放平台标准的 AppKey + 签名机制，请求体内携带业务参数与分页参数。
• 请求结构：核心参数包括 modified_begin、modified_end（修改时间区间）、page_index（页码，默认 1）、page_size（每页大小，默认 50）。
• 响应结构：返回供应商列表，单条记录包含 supplier_id、supplier_code、name、modified、group、enabled 等字段。
• 分页模式：基于 page_index + page_size 的传统分页，需循环翻页直至返回空数组。
• 增量模式：通过 modified_begin / modified_end 配合定时任务按窗口抓取变更数据，定时周期每 3 分钟一次（crontab */3 * * * *）。

典型字段映射

在轻易云上如何配置

在轻易云数据集成平台里，调用该接口通常采用「聚水潭适配器 + 字段映射器」的组合：

• 数据源配置：选择聚水潭适配器，填入 AppKey 与签名信息，接口路径选 /open/supplier/query，策略类型选 QUERY，Target 配置为「写入空操作」表明纯查询。
• 元数据配置：把 supplier_id 同时设为 id（主键）与 number（编码），便于后续单据引用与对照。
• 增量配置：在轻易云的「时间窗口」参数里绑定 modified_begin 与 modified_end，模板使用 {{LAST_SYNC_TIME|datetime}} 与 {{CURRENT_TIME|datetime}}，平台会自动维护增量游标。
• 分页配置：把 page_index 绑定为循环变量，page_size 默认设为 50；轻易云的循环器会在返回空页时自动停止。
• 字段映射器：轻易云的字段映射器会自动把 supplier_id、supplier_code、name、modified、group、enabled 暴露为下游可引用的输出列，便于和金蝶云星空的 FNumber、FName 等做一对一映射。

跨方案实战要点

从多个客户方案的实战里，我们提炼出以下共性经验：

1. supplier_id 双角色：聚水潭的 supplier_id 同时承担主键与编码两个角色，这是它与很多 ERP 不同的地方，metadata 里 id 与 number 都指向同一字段，跨系统映射时要保持一致。
2. 增量锚点必须用 modified：modified 是供应商档案变更的唯一时间锚点，不能用创建时间，否则漏更新；定时周期建议 3 分钟一次。
3. 分页与增量要联动：只按页码翻页会把历史数据反复拉取，正确做法是先按 modified 区间过滤，再在该区间内翻页，轻易云的循环器会按这个顺序执行。
4. enabled 字段要做过滤：未启用的供应商不应同步到下游，建议在轻易云映射器里加一道判断，只把 enabled=true 的记录输出。
5. 编码对照要建独立映射表：supplier_id 与金蝶 FNumber 的对照建议单独维护一张映射表，避免在字段映射器里硬编码。
6. Target 设为空操作：该策略是纯查询，不写入目标系统，Target 配置一定要是「写入空操作」，否则会污染下游。

踩坑复盘

• 踩坑 1：分页没翻完就退出——只请求了第一页就误以为数据拉完了，结果下游供应商档案缺失。这里容易翻车，稳妥的做法是在轻易云循环器里判断返回数组是否为空，空则跳出。
• 踩坑 2：增量时间用了本地时区——modified_begin/modified_end 传了本地时间，导致与服务端 UTC 偏移，漏数据或重复拉取。正确做法是统一用 UTC 或聚水潭服务端时区。
• 踩坑 3：把 supplier_id 当成纯编码——metadata 只配了 id 没配 number，导致下游单据引用编码时取不到值。这里一定要把 id 与 number 都配成 supplier_id。
• 踩坑 4：未启用供应商也同步了过去——enabled=false 的供应商被推到金蝶，造成档案污染。建议在映射器前置一道过滤。
• 踩坑 5：Target 误配成写入——把纯查询策略的 Target 配成了实际写入接口，导致数据被错误推送到下游。务必确认 Target 是「写入空操作」。

何时选用

该接口适用于聚水潭与金蝶云星空（或类似 ERP）供应链集成中的供应商主数据联动查询场景，特别是需要按修改时间做增量同步、做编码对照、以及为采购单据提供供应商字段引用的场合。不适用于需要写入或修改供应商档案的场景，也不适合对实时性要求低于 3 分钟的业务。