旺店通销售订单明细接口字段手册：从API到MySQL表体的权威实战教程

这个接口解决什么问题

在旺店通到 MySQL 的供应链集成中,销售订单"已完成"状态的明细行是最核心的下游分析数据。表头告诉你"是哪一单",而 detail_list 中的每一行才是真正的商品级明细——SKU、规格、数量、单价、分摊邮费、行级折扣、支付与发货状态等。本接口用于把 status=2 的销售订单明细增量同步至 MySQL 表体,支撑本地化报表、利润核算、库存占用跟踪与平台对账。

接口能力总览

• 认证方式:通过轻易云集成平台封装的 QueryStrategyData 适配器调用,内部已完成旺店通·旗舰奇门的签名与会话管理,用户无需关心 token 与签名细节。
• 请求结构:核心参数为 status=2(已完成)、response_at_begin / response_at_end(10 位 Unix 时间戳窗口)、page_no / page_size(分页参数)。
• 响应结构:返回订单主表对象数组,每个对象内嵌 detail_list 数组;真正需要落库的是 detail_list 中的每一行,主表字段用于上下文传递。
• 分页与增量模式:基于 response_at 的时间窗口增量,典型周期为 15 分钟一轮,跨周期时通过 F_response_at 时间戳做水位线管理,避免漏单与重单。

典型字段映射

主表(表头)关键字段

集成平台扩展字段(F_ 前缀)

明细行(detail_list)关键字段

在轻易云上如何配置

在轻易云数据集成平台里,这个接口的调用通常采用策略化适配器 + 字段映射器的两段式配置:

1. 数据源适配器:选择"旺店通·旗舰奇门"作为源端,启用 QueryStrategyData 策略查询,设置 status=2 与时间窗口参数。平台会自动处理签名、限流与分页。
2. 字段映射器:针对明细行,把 detail_list[*] 展开为扁平结构,逐字段映射到 MySQL 的 wdt_sales_trade_order_detail 表。rec_id 设为 upsert 主键,trade_id 保留用于关联主表。F_ 前缀字段建议原样落库到独立列,便于后续排查。
3. 调度策略:配置 15 分钟一轮的 cron,F_response_at 作为水位线持久化,跨周期自动衔接。

跨方案实战要点

1. 明细才是真同步对象:主表只做上下文,真正的数据量在 detail_list。配置时务必展开数组,否则表体会空。
2. rec_id 必须原样落库:它是表体的唯一主键,轻易云字段映射器默认会原样输出,不要做二次清洗。
3. 时间窗口边界要对齐:response_at_begin 与 response_at_end 要落在已完成订单的 pay_time 或 modified 上,避免漏单。
4. 金额字段全是 string:num/price/order_price/share_amount 等都是字符串,落 MySQL 前需 cast 为 decimal,否则聚合计算会出错。
5. 分摊字段优先于原价:利润核算必须用 share_price / share_amount,而不是 price/order_price,否则会被订单级优惠"漏算"。
6. F_ 字段单独存放:不要混入业务字段表,建一张旁路表或独立列,出问题排查时能快速回溯。

踩坑复盘

• 坑 1:把 detail_list 当成普通字段处理。展开不到位,导致表体只有主表一条记录、明细全丢。稳妥的做法是在字段映射器里显式展开数组。
• 坑 2:用 price 当利润核算单价。订单级优惠分摊后,实际单价是 share_price,直接用 price 会高毛利点。
• 坑 3:时间窗口用错字段。用 trade_time 做增量边界会把未支付订单也拉进来,导致明细与表头状态不一致。应基于 pay_time 或 modified。
• 坑 4:忽略 stock_state。它直接反映库存占用/释放,不参与下游可用库存计算会导致超卖预警。
• 坑 5:F_ 字段被业务逻辑误用。F_status、F_result 是平台内部状态,当成业务状态过滤会出现"全部为空"的乌龙。

何时选用

适用于已完成销售订单明细的本地化存储、利润分析、库存占用跟踪与电商平台对账。若你只需要订单表头或实时订单,应改用表头策略或 status≠2 的查询策略;若涉及退款明细,则需走退货入库的独立链路。