旺店通店铺查询（shop WebAPI）字段手册与跨方案实战教程

这个接口解决什么问题

在电商多店铺运营场景下，店铺是订单归集、库存分仓、物流策略、电子发票的核心主数据维度。旺店通店铺查询接口（shop WebAPI）用于按分页批量拉取店铺基础资料，支撑店铺主数据同步、与金蝶云星辰组织/客户映射、以及订单/出库单按店铺维度的精准匹配，是供应链集成链路上的「源头主数据策略」。

接口能力总览

• 认证方式：基于 app_key（JSON 含 key、secret、token）及 refresh_token 的授权体系，需关注 auth_state、pay_auth_state、expire_time、re_expire_time 四个授权生命周期字段。
• 请求结构：POST 请求，Body 支持按 platform（平台ID）、shop_no（店铺编码）筛选。
• 响应结构：返回店铺对象数组，单条记录约 60+ 字段，涵盖基础资料、平台授权、行政区划、联系信息、物流策略、业务开关。
• 分页模式：page_no 默认从 0 开始，page_size 默认 40，取值范围 1100。建议生产环境设为 5080，平衡吞吐与稳定性。
• 增量模式：API 本身未原生支持按 modified 增量拉取，常见做法是先用全量铺底，再结合本地变更时间戳做差量。

典型字段映射

在轻易云上如何配置

在轻易云数据集成平台里，旺店通店铺查询通常采用源系统适配器 + QUERY_ONLY 策略的组合。源端选择旺店通·企业版适配器，配置 app_key 与 token 后，在策略编辑器里选中 shop 接口。轻易云的字段映射器会自动读取返回的元数据，把 shop_id 识别为 id、shop_no 识别为 number，省去手动标注。Target 端选择「写入空操作」即可完成纯查询策略；如需把店铺同步到金蝶云星辰，再加一个下游写入策略，轻易云的可视化字段映射支持拖拽式把旺店通字段映射到星辰的组织/客户档案。定时调度可直接使用 crontab */10 7-23 * * *，对应平台里的「每日 7:00–23:00 每 10 分钟」配置。

跨方案实战要点

1. shop_id 与 shop_no 双键策略：跨系统映射时主键用 shop_id 保证唯一，业务引用用 shop_no 提升可读性，两个方案都验证过稳定性。
2. 授权状态前置过滤：在轻易云的源端过滤器里直接丢弃 auth_state != 1 的店铺，避免无效数据污染下游。
3. 分页 size 不要拉满：尽管接口支持到 100，但真实场景里 60~80 更稳，遇到过 100 触发限流的情况。
4. 行政区划冗余存储：ID 与名称同时落库，省去下游再查一次基础资料的 N+1 调用。
5. 停用字段做反向映射：旺店通 is_disabled 与金蝶 enable 语义相反，映射器里记得勾「取反」。
6. 物流策略字段谨慎映射：logistics_id=0 代表「按策略计算」，不能盲目映射成具体物流公司。

踩坑复盘

• 踩坑一：refresh_token 过期导致全量拉空。集成跑得好好的，某天突然返回空集，最后发现是 re_expire_time 过期触发了鉴权失败。应对：轻易云的源端连接器里有 token 自动刷新机制，但要确认上游已开启，且在监控里加一个「连续 2 个周期返回 0 条」的告警。
• 踩坑二：店铺编码在 ERP 自定义后冲突出错。shop_no 虽说是编码字段，但 ERP 端允许用户手动改，结果两个不同平台的店铺被改成了同一个 shop_no，映射时撞车。应对：稳妥的做法是用 shop_id 作为最终主键，shop_no 仅作辅助展示。
• 踩坑三：forbidden_logistics_list 解析炸掉下游。该字段是 JSON 数组字符串，遇到空字符串或非法 JSON 时下游解析器直接抛异常。应对：在轻易云的字段映射器里给该字段配置「安全解析」+「异常默认值」。
• 踩坑四：行政区划 ID 与名称不同步。旺店通改了省份名称后，ID 没变但名称变了，下游按 ID 匹配时展示成了旧名字。应对：建议名称字段也存一份，ID 仅做关联键。
• 踩坑五：is_disabled 反向映射漏配。旺店通停用的店铺同步到金蝶后仍然 enable，导致出库单仍然下推。应对：映射器里这个字段务必勾「布尔取反」。

何时选用

适用于电商多店铺场景下，需要把旺店通店铺主数据同步到金蝶云星辰、或其他 ERP/CRM 作为组织/客户档案，并以此支撑订单归集、库存分仓、物流策略、电子发票等供应链下游业务的场景。边界：当店铺数据量极大（万级以上）且需要近实时变更时，建议改用旺店通的推送机制（push_rds_id）而非轮询。