吉客云退款单查询接口字段手册权威教程

这个接口解决什么问题

在吉客云与金蝶云·旗舰版的供应链集成场景中，退款单的同步常被忽视但风险极高——若补偿退款数据未及时回传金蝶，会导致销售订单金额不平、应收账款挂账错误、退款凭证缺失。本接口（ass-business.refund.listRefundInfo）专门用于查询吉客云侧的退款单全量数据，与退换货（returnchange）接口区分，专做纯退款场景的补偿拉取，为下游生成金蝶红字销售单或退款凭证提供数据源。

接口能力总览

• 认证方式：吉客云开放平台 OAuth/AppKey 签名鉴权，私有化部署需使用内网网关地址。
• 请求结构：POST 请求 Body 传 JSON，核心参数为 pageIndex（默认 0）、pageSize（默认 200，最大 1000）、tradeNo、refundNoList、refundStatusList、startTime/endTime、startModified/endModified。
• 响应结构：返回数据包装在 refundList 数组中，每个元素包含主表字段及 payInfo、receiverInfo、refundGoodsItems、customColumnInfo 四个嵌套对象。
• 分页与增量：支持 pageIndex 分页与按 gmtModified 增量；增量建议使用 startModified/endModified 而非创建时间，避免漏单。
• 操作类型：纯查询（QUERY_ONLY），Target 配置为写入空操作，常用于定时调度拉取。

典型字段映射

在轻易云上如何配置

在轻易云数据集成平台中，该接口已封装为标准适配器。配置路径通常为：集成源 → 吉客云 → 选择「查询退款单」模板。平台会自动注入请求参数模板与分页器，工程师只需在元数据中确认 refundId 为 id、refundNo 为 number 即可。

针对金蝶侧的销售订单关联，轻易云的字段映射器支持 _findCollection 表达式：按 tradeNo 在金蝶销售订单集合中反查 billno，自动写入 salesOrderId。对于嵌套对象 payInfo.returnTotal 这类带点路径的字段，轻易云的字段映射面板可直接展开嵌套结构，无需写脚本即可完成映射。

调度方面，平台默认推荐 crontab */30 * * * * 每 30 分钟拉取一次，结合 gmtModified 水位字段实现增量。若出现跨时区问题，可在平台时区配置中将源系统时区设为 Asia/Shanghai。

跨方案实战要点

1. 退款单与退换单必须分开建模：退款单主键是 refundId，退换单主键是 tradeAfterNo，混用会导致金额字段语义错乱。
2. 关联销售单号是连接金蝶的桥梁：吉客云的 tradeNo 对应金蝶销售订单的 billno，跨系统对账的核心就是这一映射。
3. 嵌套对象 payInfo 是金额校验的关键：payInfo.returnTotal 应等于 refundGoodsItems 中 refundFee 之和，做对账校验时务必加上。
4. 增量字段必须用 gmtModified 而非 gmtCreate：退款单存在多次修改（审核、状态变更），仅按创建时间拉取会漏掉状态更新。
5. 店铺维度需要单独处理：多店铺/多渠道场景下，shopCode 应当作为数据隔离维度，避免不同渠道退款单混淆。
6. 退款明细行数量可能为 0：纯退款不退货场景下 refundGoodsItems 可能为空数组，写入下游时要做空数组兼容。

踩坑复盘

• 翻车一：用 tradeNo 做主键导致重复入库：tradeNo 是销售单号，同一销售单可能产生多条退款补偿记录，主键必须用 refundId。稳的做法是在 metadata 中显式声明 id 字段为 refundId。
• 翻车二：时区不一致导致增量漏单：gmtModified 在源系统是 UTC+8，集成平台若按 UTC 解析，会把 8 小时窗口内的单子漏掉。一定要确认源系统时区并配置水位转换。
• 翻车三：refundGoodsItems 与 goodslist 重复：两个字段可能携带同一货品明细的不同序列化形式，只映射其中一个即可，否则下游去重逻辑混乱。
• 翻车四：枚举值未确认就过滤：refundStatusList 若按猜测的枚举值传参，会导致状态过滤后无数据。建议前 1-2 个调度周期先拉全量，确认枚举后再启用过滤。
• 翻车五：payInfo 内银行字段缺失：部分退款单的 payInfo.bankName、bankCode 为空，映射到金蝶时若字段非空校验过严会写入失败。应在映射器中加默认值或允许空值。

何时选用

该接口适用于吉客云作为电商中台、与金蝶云·旗舰版做供应链财务一体化的私有化集成场景，特别是需要按退款单生成红字销售单或退款凭证、且需与原始销售订单强关联对账的业务。当业务场景是退货/换货收货时，应改用退换单接口而非退款单接口。