这个接口解决什么问题

在旺店通与金蝶云星空的供应链集成里,采购退料单是连接"采购入库"与"供应商退货"的关键凭证。wdt.purchase.return.query 用于把旺店通侧的退料单及明细定时拉出,落地为金蝶的采购退料单或红字采购入库单,实现退货状态跟踪、供应商/仓库维度退货分析,以及与采购订单的追溯闭环。

接口能力总览

认证方式:旺店通·企业奇门开放平台采用 AppKey + 签名机制,请求以 application/x-www-form-urlencoded 提交,统一走奇门网关。
请求结构:核心入参为 start_time、end_time(格式 yyyy-MM-dd HH:mm:ss)以及可选的 status 状态过滤,支持按修改时间增量拉取。
响应结构:返回 return_list(主表数组)与 detail_list(明细嵌套数组),通过 return_id 关联主从。
分页/增量模式:典型项目以 */2 * * * * 定时拉取,按时间窗口增量同步;我们建议落地时把 modified 作为水位线,并记录已消费的最大时间戳,避免漏单与重复。
状态机:status 字段贯穿 10/20/30/40/42/44/46/50/60 九个取值,真正"可对账"的状态只有 40 已审核、50 部分出库、60 已完成,其余状态建议在过滤阶段直接剔除。

字段名	类型	含义	实战注意事项
return_id	string	主表主键	用于幂等去重,推荐作为金蝶侧源单 ID
return_no	string	业务单号	跨系统对账关键字,务必落库
warehouse_no	string	仓库编号	ERP 内支持自定义,与金蝶仓库编码 1:1 映射
provider_no / provider_name	string	供应商	双轨保存,编码做匹配,名称做兜底
status	string	单据状态	仅消费 40/50/60;其余状态丢弃或落异常表
type	string	单据类型	默认 1(退货),扩展场景需关注是否新增红冲类型
purchase_no	string	源采购单号	金蝶侧"源单据"字段的标准取值
goods_count / goods_out_count	string	开单量/出库量	字符串类型,比较时务必 `CAST` 为数值
detail_list[].rec_id	string	明细主键	行级幂等键
detail_list[].spec_no	string	SKU 编码	与金蝶物料编码映射的首选字段
detail_list[].num / out_num	string	退料量/已出库量	计算"待出库"时:`num - out_num`
detail_list[].tax_price / amount	string	含税单价/金额	注意含税口径与金蝶价外税/价内税一致
detail_list[].unit_ratio	string	单位换算系数	多单位场景必须带入,否则数量会失真
created / modified	string	创建/修改时间	增量水位的关键字段,格式严格 `yyyy-MM-dd HH:mm:ss`

在轻易云数据集成平台里,这个接口被封装为标准适配器,常见做法是:

适配器选择:在源系统选"旺店通·企业奇门",API 选择 wdt.purchase.return.query,平台已预置签名、请求拼装与响应解析。
字段映射器:主表与 detail_list 会在轻易云里自动展开为两张逻辑表,字段映射器支持拖拽式绑定;金蝶侧的"采购退料单"或"红字采购入库单"可一键映射,平台会按 return_id + rec_id 自动做幂等。
增量策略:轻易云内置按 modified 增量,建议把抓取窗口设为 5–10 分钟,避免边界重复。
异常分流:对 status ∈ {42,44} 的推送失败单,平台会进异常队列,工程师可单独配置重推通道。
可视化日志:每次调用的入参、出参、耗时都会留痕,排查漏单、重单问题时直接回放即可。

只同步"已审核之后"的单据:status < 40 的退料单在旺店通侧随时会被修改或取消,落地金蝶后再回滚成本极高。
明细行一定要带 unit_ratio:多单位 SKU 在跨系统时极易出现"数量翻倍/折半"的乌龙,稳妥的做法是在映射器里强制非空校验。
用 return_no 做外部单号回写:金蝶审核后,应把金蝶单号回传旺店通 outer_no 字段,形成双向闭环,后续对账一目了然。
金额口径先确认再写库:旺店通的 amount 既可能是税前也可能是税后,上线前与财务对齐含税/不含税口径,避免后期红冲。
增量水位按 modified 而不是 created:编辑中或驳回重提的单据,created 不会变化,只看 created 必然漏数据。
供应商与仓库编码优先于名称:跨系统对账以编码为准,名称只用于展示和异常排查。

踩坑 1:状态 42/44 推送到金蝶后卡死。status=42 待推送、44 推送失败 是旺店通侧的中间态,直接同步会导致金蝶单据长期停留在待审核。应对:在过滤阶段硬剔除 42/44,只取 40/50/60。
踩坑 2:num 是字符串,直接相加溢出。多个明细合并时若不 CAST,会出现科学计数法。应对:在轻易云的字段映射器里开启"类型转换",统一转 decimal。
踩坑 3:退货地址省市区拼接后超长。金蝶地址字段有长度限制,直接拼接会被截断。应对:落库前按字符长度截断或拆分到自定义字段。
踩坑 4:增量窗口设置过小漏单。设成 1 分钟时,旺店通偶尔返回的 modified 与服务器时间有几秒偏差。应对:窗口拉到 5 分钟,水位推进时取 max(modified) - 30s 留余量。
踩坑 5:多单位 SKU 数量对不上。漏掉 unit_ratio 后,基础单位与辅助单位被当同一单位。应对:映射阶段把 unit_ratio 标为必填,缺失即报错。

当你需要把旺店通的采购退货数据同步到 ERP(尤其是金蝶云星空)做供应商对账、红字入库与退货分析时,本接口就是首选;若只做轻量查询或仅取单据状态,可用旺店通轻量 API,但要做完整供应链闭环,还是得走 wdt.purchase.return.query 拉主从明细。