这个接口解决什么问题

在多平台电商场景下，企业往往需要在本地维护一份「店铺主数据」副本，用于按店铺拆分订单、库存与报表数据，并校验电商平台的授权有效性。聚水潭店铺查询接口承担的就是这一角色：把聚水潭侧的店铺档案、所属分组/公司、授权会话信息等批量同步至 MySQL 主数据表，作为下游所有业务单据（订单、发货单、退货单、采购入库单等）按店铺归集的关联锚点。

接口能力总览

认证方式：基于聚水潭开放平台的 OAuth 授权机制，授权完成后由会话凭证访问接口。
请求结构：支持 page_index（默认 1）、page_size（默认 100，最大 100）、shop_ids（可选，按店铺编码批量筛选）三类参数。
响应结构：返回店铺列表，单条记录包含店铺编码、名称、简称、主账号、站点、网址、分组、公司、组织、会话用户、授权过期时间、创建时间等字段。
分页模式：标准分页，每页最大 100 条；通常按 page_index 线性递增翻页，直至返回列表为空。
增量模式：在多个客户方案里我们都采用 2 小时周期（crontab: 10 */2 * * *）全量覆盖式拉取，并以 shop_id 作为唯一键写入 MySQL 目标表；店铺主数据体量小、变更频次低，全量替换的代价远小于增量对账。

典型字段映射

字段名	类型	含义	实战注意事项
shop_id	int	店铺唯一编码，主键	与下游订单/库存/发货单强关联，必须先于业务数据到位
shop_name	string	店铺显示名称	用于报表与下拉展示，建议做 UTF-8 校验
short_name	string	店铺简称	报表列宽受限时优先展示
nick	string	电商平台主账号	与 `shop_site` 配合使用，识别平台店铺身份
shop_site	string	销售渠道/平台类型	如「淘宝」「京东」「商家自有商城」，下游分析常按此分组
shop_url	string	店铺访问地址	普通字段，按需落地
group_id	int	店铺所属分组编码	与 `group_name` 一一对应
group_name	string	店铺所属分组名称	便于按品牌/业务线归集
co_id	int	公司编码	多公司/多法人主体场景下必用
organization	string	组织归属	与公司/分组配合用于权限隔离
session_uid	string	当前授权会话用户	与 OAuth 授权流程强相关
session_expired	datetime	授权过期时间	可能为具体时间，也可能为「------永久授权------」字面量，需特殊处理
created	datetime	聚水潭侧创建时间	用于首次同步时的存量判断

在轻易云数据集成平台里，字段映射器会自动把以上字段映射为下划线命名规范的 MySQL 列；平台默认采用 REPLACE INTO 写入策略，以 shop_id 作为唯一键，保证重复拉取时不会产生脏数据。

在轻易云上如何配置

数据源注册：在轻易云「数据源」中新增聚水潭适配器，填入授权凭证并完成 OAuth 授权。
目标源注册：新增 MySQL 数据源，指向业务库，并提前创建目标表 jst_shops_query，主键为 shop_id。
适配器选择：选择「聚水潭·店铺查询」适配器，该适配器已封装分页、增量、限流逻辑。
字段映射：在轻易云可视化映射界面里，把响应字段一一拖拽到目标列，平台会自动处理类型转换与字段命名规范化。
调度配置：将调度策略配置为 10 */2 * * *，每 2 小时执行一次；并开启「全量覆盖写入」开关，使 REPLACE INTO 自动生效。
告警与监控：在轻易云「监控中心」为该任务配置失败重试、限流告警和授权过期提醒。

跨方案实战要点

店铺先于业务单据同步：在多个客户项目里，我们都把店铺同步任务的调度优先级设为高于订单、库存等业务单据——只要 shop_id 没就位，下游所有按店铺归集的数据都会成为「孤儿」。
全量优于增量：店铺主数据体量小（通常数百到数千条），变更频次低，全量 REPLACE INTO 比增量对账省心得多；轻易云的字段映射器天然支持这种模式。
授权过期是隐性雷点：session_expired 字段可能出现「------永久授权------」字面量，需要在映射时做特殊处理或单独落库，便于人工复核。
多公司多店铺必须带 co_id：在多法人主体场景下，co_id 与 group_id 是权限隔离与财务报表归集的关键字段，不能省略。
分页上限别踩：聚水潭每页最大 100 条，超过会被拒；稳妥的做法是在轻易云里固定 page_size=100，让平台自动翻页。
站点（shop_site）即渠道标签：下游分析通常按 shop_site 切分数据，因此站点字段应在清洗阶段就完成标准化。

踩坑复盘

shop_id 与 number/id 三字段同名：接口响应中 number、id 都指向 shop_id，映射时若同时入库会造成主键冲突。稳妥做法是只保留一个目标列。
session_expired 字面量导致时间字段入库失败：聚水潭在永久授权场景下会返回特殊字符串；务必在轻易云的字段清洗规则里加一条「非时间值置 NULL」的规则。
调度周期太密导致限流：有客户把周期设为 5 分钟一次，触发聚水潭侧频控；改为 2 小时后稳定运行。建议最小周期不少于 30 分钟。
目标表缺主键导致重复写入：未建 shop_id 唯一索引时，REPLACE INTO 会退化为普通 INSERT，数据快速膨胀。必须先建主键。
店铺同步晚于订单同步导致报表口径错乱：订单已按未知 shop_id 落入汇总表，店铺同步才到位。务必把店铺任务调度排在业务单据之前。

何时选用

适用于多平台电商业态、需要按店铺维度做数据归集与权限隔离的场景，特别是多公司多店铺、对授权有效性敏感、且下游报表需按渠道/品牌拆分的供应链集成链路。边界在于：若仅有单一店铺且无主数据复用需求，可直接用平台侧能力而无须落地；若店铺体量极大（>10 万条），则需评估全量同步的 IO 代价。

聚水潭店铺查询接口字段手册：从聚水潭到 MySQL 的全链路实战教程