聚水潭仓库查询接口权威教程：从字段映射到跨系统集成的实战手册

这个接口解决什么问题

在电商 ERP 与财务/供应链 ERP 的集成链路里，仓库主数据是最容易被忽视却又最容易出错的一环。聚水潭 WMS 的 /open/wms/partner/query 接口专门用于查询分仓主数据，让我们能把聚水潭侧的分仓编号、分仓名称、主仓归属一次性拉到下游，作为金蝶云星空等系统的仓库映射底座，避免后续出/入库单、调拨单因仓库编码不一致而翻车。

接口能力总览

• 认证方式：聚水潭开放平台标准的 OAuth/AppToken 鉴权，需在请求头携带 access_token。
• 请求结构：POST 或 GET 均可（视具体适配器版本），核心分页参数为 page_index（默认 1）与 page_size（默认 30）。
• 响应结构：返回分仓数组，每个元素包含 wms_co_id、name、co_id、is_main 等字段。
• 分页/增量模式：纯分页拉取，无内建增量游标；实战中通常用定时任务按全量分页扫描，靠 wms_co_id 在下游做幂等去重。
• 执行频率：常见 Cron 配置为 10-59/59 7-23 * * *，即每 59 分钟在 7–23 点之间触发，避开凌晨系统维护窗口。

典型字段映射

在轻易云上如何配置

在轻易云数据集成平台里，这个接口已经被封装为标准的 WMS 适配器组件。我们通常按以下步骤配置：

1. 在「数据源」新建聚水潭连接，填入 AppKey/Secret 后由平台统一维护 token 刷新。
2. 选择 /open/wms/partner/query 适配器模板，自动带入 page_index、page_size 两个分页变量。
3. 在元数据里把 id 指定为 wms_co_id，number 指定为 name，并视场景开启 idCheck。
4. Target 端选「写入空操作」，即声明该策略为纯查询，仅产出中间结果供后续策略引用。
5. 轻易云的字段映射器会自动把 is_main 的字符串布尔值规范化，避免下游金蝶侧类型校验失败。

跨方案实战要点

• 仓库主数据先行：所有出/入库、调拨策略都依赖仓库对照表，务必先跑通仓库查询再启用业务单据策略。
• 主仓-分仓层级不可丢：co_id 必须同步给下游，否则金蝶侧会把分仓误识别为顶层仓，导致库存组织错乱。
• 同名分仓要联合去重：单纯按 name 对照在多公司场景下必然撞车，必须用 wms_co_id + co_id 复合键。
• 分页节奏与限流：聚水潭对单租户有 QPS 限制，page_size 不建议超过 50，定时间隔要预留 token 刷新窗口。
• 纯查询策略的复用价值：把仓库查询结果落到中间表，后续多条业务策略共享同一份主数据，降低维护成本。
• 幂等写入是底线：即使 Target 是空操作，也要保证下游消费方按 wms_co_id 幂等，否则重复推送会污染映射表。

踩坑复盘

1. is_main 被当成布尔字段处理：金蝶侧期望布尔类型，聚水潭返回的是字符串 "true"，直接映射会校验失败。稳妥做法是在映射器里显式转布尔。
2. 忘记带 co_id，下游层级错乱：某零售企业首次集成时只同步了 wms_co_id 与 name，结果金蝶把分仓挂到了错误的主仓下，后续库存调拨全部对不上账。
3. 分页未拉完就启动下游：定时任务刚跑完第一页就触发了金蝶写入，导致一半分仓缺失。建议在轻易云里用「全量完成事件」驱动下游策略。
4. Cron 触发时间撞上 token 过期：默认 token 有效期 2 小时，跨夜任务极易踩到过期窗口。稳妥的做法是把 Cron 起点设在整点后 10 分钟，并开启平台自动续签。
5. 仓库重命名后历史单据失联：聚水潭允许修改分仓名称，若下游只按名称匹配，旧单据会找不到仓库。务必以 wms_co_id 作为唯一关联键。

何时选用

该接口适用于电商 WMS 与财务/供应链 ERP 之间的仓库主数据同步、跨系统仓库对照、出/入库及调拨单的仓库字段转换。不适用于需要实时库存水位查询的场景——库存数据应走专门的库存查询接口，而非这条分仓主数据接口。