聚水潭退货退款查询接口字段手册权威教程（非奇门版）

这个接口解决什么问题

聚水潭的「退货退款查询」接口用于把电商平台产生的售后单（含退货、仅退款、换货、补发等）从聚水潭拉回到本地数据仓库，常见于某零售企业的售后数据本地化、退换货分析、财务对账与库存回冲场景。落地到 MySQL 后，可与销售订单、库存流水关联分析，闭环整条供应链售后链路。

接口能力总览

• 接口路径：/open/refund/single/query（非奇门直连版本，与奇门版 P2-010 字段有差异）
• 认证方式：聚水潭开放平台 Access Token，应用级授权
• 请求结构：POST + 表单/JSON，modified_begin / modified_end 为修改时间区间，date_type 控制时间字段类型（0=modified，2=io_date 出库时间），与线上单号不能同时为空，且区间不超过 7 天
• 分页/增量：基于修改时间增量；多条策略普遍按 1 小时周期（15 */1 * * *）调度，按 as_id 去重写入
• 响应结构：单层售后单对象，主表字段平铺，items 为明细数组，需扁平化写入
• 写入方式：MySQL 端普遍采用 REPLACE INTO 按主键去重，AfterTargetGenerate 阶段做空值转 null、过滤 emoji 与超 BMP 字符

典型字段映射

主表（表头）核心字段

明细行（items_*）核心字段

在轻易云上如何配置

在轻易云数据集成平台里，配置这个接口通常分四步：

1. 适配器选择：在「聚水潭·非奇门」适配器下选 /open/refund/single/query，平台已经预置了鉴权与时间区间封装。
2. 字段映射器：主表字段按 1:1 映射，items 明细通过「明细扁平化」节点自动加 items_ 前缀落到目标表。
3. 增量策略：用「按 modified 增量」组件，把上一次成功的 modified_end 落到调度变量，时间窗自动滑动且不超过 7 天上限。
4. 写入后处理：平台自带的 AfterTargetGenerate 钩子会做空值归一、emoji 与超 BMP 字符过滤，写入目标 MySQL 时默认走 REPLACE INTO，避免重复主键导致任务中断。

跨方案实战要点

1. 时间窗 7 天上限是硬约束：拆分长周期回溯任务时，必须按 7 天分片，不能一次拉一个月。
2. date_type 决定增量基准：默认 0（modified）覆盖大多数售后状态变更场景；若按 io_date 拉，需注意「Confirmed 之后 modified 不再变化」的边界。
3. 明细必须扁平化：items 不展开直接写库会导致结构错乱和查询性能塌方。
4. 状态字段是财务触发器：status 从 WaitConfirm → Confirmed 是库存回冲的真正信号，Cancelled 要单独剔除。
5. 金额字段分得很细：refund/payment/buyer_apply_refund/buyer_receive_refund/urefund 不能混用，对账脚本要明确各自语义。
6. 多组织维度必带：owner_co_id、drp_co_id_from/to 在分销/多组织客户里几乎一定会用上，提前建索引。

踩坑复盘

1. 时间区间超过 7 天直接报错：某客户一次性传 30 天范围，接口返回「时间间隔超限」。稳妥做法是在轻易云的调度器里加一个「7 天分片」组件。
2. emoji 与特殊字符让 MySQL 写入失败：买家昵称、备注里夹带 emoji 会触发 utf8 报错，必须在 AfterTargetGenerate 阶段过滤。
3. 明细 items 没展开导致查询返回空：直接读主表 items 字段是 JSON 字符串，业务侧以为没拉到数据。务必走扁平化。
4. Cancelled 单据被错误回冲库存：忽略了 Cancelled 状态，把所有售后单都做了库存扣减，结果产生负库存。加一层 status='Confirmed' 过滤即可。
5. as_id 重复插入失败：偶发重复推送 + INSERT 而不是 REPLACE INTO，任务直接挂掉。改成 REPLACE INTO 并加唯一键即可。

何时选用

该接口适用于：电商零售需要本地化售后数据、与 ERP/WMS 对账、做退换货分析与库存回冲的场景。注意边界：若需要平台实时推送，建议走奇门/消息推送；本接口仅做按修改时间的轮询增量，且单次时间窗不能超 7 天。