这个接口解决什么问题

聚水潭售后单查询(非奇门通道)用于把电商平台产生的退货退款单据,从 SaaS 端拉回本地 SQL Server 的 J_shtk 表,服务于售后分析、退换货审计、财务对账与库存回冲。真实场景里,某零售企业每天数千笔售后单,如果只靠人工导出,既不及时也容易丢单;通过该接口定时增量拉取,就能让售后数据与销售订单、库存账实时对齐。

接口能力总览

接口地址:/open/refund/single/query(非奇门通道,与奇门版字段基本一致但鉴权与限流策略不同)。
认证方式:聚水潭开放平台 AppKey 签名,请求体内传 partnerid 与时间戳,在轻易云里我们把它封装成「聚水潭适配器」,只需填一次凭证即可复用。
请求结构:JSON 体,核心参数为 page_index、page_size(默认 50,API 最大 50)、modified_begin/modified_end、date_type(0=修改时间,1=创建时间,2=确认时间)。
分页与增量:必须按时间窗分页拉取,单次时间跨度不能超过 7 天;在轻易云的调度器里,我们通常配 crontab: 1 0,1,2 * * *,每天 0、1、2 点各跑一次,既能错峰又能兜底。
响应结构:JSON,根节点含 datas(售后单数组)与 has_next(是否还有下一页);每条售后单含主表字段与 items、batchs 两个嵌套数组。

典型字段映射

字段名	类型	含义	实战注意事项
as_id	string	聚水潭内部售后单号,主键	metadata 中 `number` 指向它,`id` 一般拼成 `{{as_id}}{{modified}}` 用于增量去重
outer_as_id	string	平台侧退货退款单号	与淘宝/京东对账的关键,务必入库
so_id / o_id	string	线上单号 / 内部订单号	关联销售订单用于追溯原单与库存回冲
shop_id / wh_id / wms_co_id	string	店铺 / 仓库 / 分仓编号	多店多仓场景用于路由与分组
shop_status	string	平台侧售后流程状态	枚举见下表,SUCCESS/CLOSED 是终态
type	string	售后类型	普通退货、拒收退货、仅退款、投诉、补发、换货等
good_status	string	货物状态	BUYER_NOT_RECEIVED / BUYER_RECEIVED / BUYER_RETURNED_GOODS / SELLER_RECEIVED
modified / created / confirm_date	string/datetime	修改/创建/确认时间	增量拉取依据,confirm_date 是售后真正完成的标志
refund / payment / freight	string	退款/补偿/应退运费	都是字符串,记得转 decimal,避免精度丢失
items	array	商品明细	必须在目标表展平为 items_sku_id、items_qty、items_amount 等扁平字段
order_labels	string(数组)	售后单标签	API 实际返回但 metadata 未声明,需要脚本把数组逗号拼接写入 order_label

在轻易云上如何配置

在轻易云数据集成平台里,我们为聚水潭提供了开箱即用的适配器:

数据源:选择「聚水潭·非奇门」通道,填入 AppKey 与 partnerid,平台会自动处理签名与限流。
字段映射器:主表字段通过可视化拖拽一一对应;items 数组使用「数组展开」节点,自动复制父行的关联键(as_id、shop_id、wh_id),并把 SKU、数量、金额、入仓时间等子字段映射到 items_* 列。
增量策略:调度器里把 modified_begin 设为上一次成功结束时间,date_type=0,窗口 7 天,失败自动重试。
目标写入:批量 upsert 到 SQL Server J_shtk,主键冲突时按 modified 覆盖,确保幂等。
脚本钩子:AfterSourceInvoke 钩子用于把 order_labels 数组拼接成字符串,补丁那些 metadata 没声明的字段。

跨方案实战要点

时间窗不能超过 7 天:这是聚水潭接口的硬约束,超过会直接报错,稳妥的做法是在调度器里加一道校验。
modified vs confirm_date:全量对账用 modified 做增量,但「真正完成的售后」要用 confirm_date,二者不能混用。
items 必须展平:目标表是 SQL Server 关系型结构,数组必须拍扁;否则下游 BI 与对账脚本都跑不起来。
主键去重要拼 modified:仅靠 as_id 在售后单被修改后会重复,稳妥的做法是 as_id+modified 联合唯一。
金额字段全是字符串:JSON 解析后记得 CAST AS decimal(18,2),不然会出现 1.00000000001 这种精度问题。
店铺/分仓/仓库三级编码:多仓多店场景必须把 shop_id、wh_id、wms_co_id 都带上,否则库存回冲会错位。

踩坑复盘

翻车 1:窗口超过 7 天直接 400。我们一开始图省事想一次拉一个月,结果接口报错。稳妥的做法是按 7 天分片,多次串行调用。
翻车 2:增量键选错。用 created 做增量时,漏掉了「售后单被客服修改状态」的更新;改成 modified 后才稳。
翻车 3:items 没展平,目标表只有一行脏数据。必须在数组展开节点配置好父键复制,否则明细全丢。
翻车 4:order_labels 数组入库失败。metadata 没声明这个字段,但 API 实际会返回,需要脚本兜底拼接。
翻车 5:金额精度漂移。refund 是 "30.00" 字符串,直接写库变成 30.00000000001;务必显式转 decimal。

何时选用

适用于「电商售后数据本地化」场景:多平台、多店铺、售后量大,需要把退货退款单据回流到自有 ERP/数据仓库做对账与分析。若你只需要奇门通道的轻量同步、或售后量极小无需入库,建议直接走平台后台导出,不必为此搭一条集成链路。

聚水潭售后单查询接口字段手册:从非奇门通道到 SQL Server 的实战权威教程