这个接口解决什么问题

在电商零售供应链里,销售退货是最容易出乱子的环节:商品从客户退回仓库,需要在 WMS 中生成退货入库单,再把数据同步到 ERP 形成入库凭证、冲减库存、触发退款。我们接触的多个客户场景中,旺店通·旗舰奇门负责前端电商订单与退货履约,金蝶云星空负责后端财务与库存账,二者在退货环节必须打通。该接口(wdt.wms.stockin.refund.querywithdetail)用于从旺店通拉取退货入库单主表与明细,是构建"退货→入库单→库存账"链路的标准入口。

接口能力总览

认证方式:旺店通奇门开放平台采用 AppKey + AppSecret 签名机制,轻易云适配器内置签名拼装与时间戳校验,无需手写加密逻辑。
请求方法:HTTP POST,Body 为 JSON。
请求结构:pager(分页,常用 page_no / page_size)+ params(业务参数,如时间范围、仓库、状态)。
响应结构:外层 response 包裹 data 数组与 total_count,主表字段平铺,明细位于 details_list 数组内,需循环读取。
分页/增量模式:典型 page_size=50~100;增量一般以 check_time 或 modified 作为水印字段,按时间窗口过滤 created_time > last_sync_time。
定时任务:在多个客户方案里,我们通常配置 24,54 * * * *,即每小时执行两次,以平衡数据时效与 API 配额。

典型字段映射

字段名	中文名	类型	含义	实战注意事项
order_no	入库单号	string	退货入库单唯一业务号,主键	与金蝶 FBillNo 直接映射,需做唯一性校验防止重复推送
refund_no	退换单号	string	关联退换货业务单号	用于追溯上游退换申请,跨系统关联键
trade_no_list	订单编号	string	原始销售订单号列表	可能多单拼接,需按分隔符拆分后回查销售订单
warehouse_no	仓库编号	string	仓库业务编码	与金蝶仓库主数据映射,务必先维护好仓库对照表
warehouse_name	仓库名称	string	仓库名称	仅作展示与日志辅助,不要直接写入金蝶
status	入库单状态	string	处理状态	仅同步已审核单据,过滤未审核状态可避免金蝶端单据漂移
check_time	审核时间	string	审核通过时间	推荐作为金蝶 FDate 的来源,比 created_time 更稳定
created_time	创建时间	string	单据创建时间	增量同步的常用起始水印
modified	最后修改时间	string	最后修改时间	增量兜底字段,捕捉审核后状态变化
customer_no	客户编码	string	退货客户编码	与金蝶客户档案映射,缺失客户需先建档
customer_name	退货人姓名	string	收货人姓名	注意脱敏后再写入日志
shop_no	店铺编号	string	店铺业务编码	映射金蝶销售组织或店铺档案
shop_name	店铺名称	string	店铺名称	展示用,避免作为主数据键
shop_platform_id	店铺平台id	string	电商平台店铺标识	多平台(天猫/抖音/京东)区分依据
logistics_type	物流方式	string	退货物流方式	文本枚举,注意金蝶端对应字段类型
operator_name	退换建单人	string	操作员姓名	通常不映射,仅留痕
goods_count	货品总数	string	退货总数量	与明细求和校验,不一致需告警
total_price	入库单总金额	string	退货总金额	与明细 sum(amount) 对账
actual_refund_amount	退换单实际退款金额	string	实际退款金额	财务对账关键字段,谨慎丢失精度
shop_remark	店铺备注	string	店铺备注	长文本,注意金蝶字段长度
flag_name	标记名称	string	单据标记/颜色	一般不参与映射
details_list	入库单明细	array	退货行项目数组	需展开为金蝶单据体(FEntity)
spec_no	规格编码	string	SKU 编码	与金蝶物料编码一一对应
goods_no	货品编号	string	货品编码	与 SKU 主数据映射
spec_name	规格名称	string	SKU 名称	展示用
num	数量	string	退货数量	注意字符串类型,需转数值
price	单价	string	退货单价	注意精度,建议统一两位小数
amount	金额	string	行金额	与 num*price 对账

在轻易云上如何配置

轻易云数据集成平台已内置旺店通奇门适配器,只需在「数据源」选择 Wangdiantong Qimen,填入 AppKey 与 AppSecret 即可完成鉴权。平台默认封装了 wdt.wms.stockin.refund.querywithdetail 的请求模板,字段映射器会自动展开 details_list 数组,按金蝶 KD_OMS_InBill 表单结构拆分为单据头与单据体。增量策略上,平台支持基于 check_time 的时间水印模式,也支持基于 modified 的偏移量模式,可在策略配置页直接切换。错误重试、断点续传、限流控制由平台统一托管,真实场景中我们通常把批大小设为 50,既能跑满分页又能错开 API 频控。

跨方案实战要点

主键选择:统一以 order_no 作为幂等键,任何同步逻辑都先按 order_no 去重,不要直接用 refund_no——同一退换单可能分批入库产生多张入库单。
审核状态过滤:只同步 status 为「已审核」的单据,否则金蝶端会收到被撤回或修改中的草稿数据。
时间水印兜底:同时记录 check_time 与 modified,前者用于常规增量,后者用于捕获审核后修改的边界场景。
明细行对账:落地前用 sum(details_list.amount) 与 total_price 校验,差额超阈值需写入告警。
主数据预建档:仓库、店铺、客户、SKU 在金蝶侧必须先建好档案,否则单据会因外键缺失被驳回。
多平台区分:通过 shop_platform_id 区分天猫、抖音、京东等渠道,避免下游按渠道统计时串号。

踩坑复盘

明细未展开:源系统 details_list 是 array,直接映射到金蝶会变成单字段 JSON 串,务必在映射器里循环展开为多行 FEntity。
字符串数字求和失真:num、price、amount 均为 string,直接相加会出现 1+2=12,转换前要 parseFloat 并控制小数位。
时区漂移:旺店通时间戳为东八区字符串,导入金蝶后若时区不一致会跨日,稳妥的做法是显式带上时区解析。
退换单 vs 入库单混淆:refund_no 是退换业务单号,order_no 才是入库单号,新手容易把 refund_no 当主键推入金蝶,导致单据重复。
配额与限流:高频全量扫描易触发旺店通 API 限流,稳妥的做法是固定每页 50 条、每小时两次,且失败指数退避。

何时选用

该接口适用于「旺店通做前端履约、金蝶做后端账务」的标准电商零售退货链路;不适用于纯线下零售退货、P2P 调拨退货或无明细需求的轻量汇总场景。若退货不涉及入库(仅退款),应改用退换单查询接口。

销售退货单查询接口字段手册:旺店通与金蝶云星空集成实战权威教程