这个接口解决什么问题

在零售与分销场景里,采购订单是 ERP 与电商仓配系统之间最常见的协同单据。旺店通·旗舰版的 purchase.PurchaseOrder.queryWithDetail 接口专门用于一次性拉取采购订单主表与全部明细行,典型用途是把采购订单同步到金蝶云星空形成采购订单/收料通知单,或驱动采购入库与结算流程。

接口能力总览

认证方式:旺店通·旗舰版采用应用级 AppKey/Secret 签名,header 携带 token,轻易云的旺店通连接器已封装鉴权流程。
请求结构:purchase.PurchaseOrder.queryWithDetail 接收 params(业务条件,如时间区间、状态、仓库、供应商)与 pager(分页参数,通常 page_size 100~200)两部分。
响应结构:主表 + 明细行拍扁返回,每行对应一条采购明细,主表字段在每行重复出现,因此聚合时务必按 purchase_id 去重回写主表,再以 detail_list_purchase_id 关联明细。
分页/增量模式:支持分页;增量通常用 start_time / end_time(修改时间)结合 modified 字段,轻易云任务默认每 7 分钟调度一次。

典型字段映射

字段名	类型	含义	实战注意事项
purchase_id	string	源系统内键主键	用作主键去重与跨系统对照
purchase_no	string	采购单业务编号	metadata 中 number/id 均挂此字段,用于增量游标
provider_no / provider_name	string	供应商编码/名称	与金蝶 FSupplierId_FNumber 匹配
warehouse_no / warehouse_name	string	仓库编码/名称	映射金蝶 FStockOrgId/FDestStockID
status / stockin_status / settle_status	string	业务/入库/结算状态	状态字典需提前维护,轻易云字段映射器可做枚举转换
goods_fee / post_fee / tax_fee / total_fee	string	金额汇总	字符串类型,需 `to_decimal` 后再做汇总
detail_list_spec_no / detail_list_goods_no	string	SKU/商品编码	与金蝶 FMaterialId_FNumber 关联
detail_list_num / detail_list_tax_price / detail_list_tax_amount	string	数量与含税金额	注意是基本单位数量,辅助单位用 num2
detail_list_new_price	string	反算单价	表达式 tax_amount*unit_ratio/num,集成时按需重算
created / modified / check_time / expect_arrive_time	string	各类时间戳	格式 yyyy-MM-dd HH:mm:ss,作为增量起点

在轻易云上如何配置

在轻易云数据集成平台里,该接口通常以"查询源"形态出现:

新建数据查询策略,选择旺店通·旗舰版适配器,API 选 purchase.PurchaseOrder.queryWithDetail;
在轻易云的字段映射器里,把 purchase_no 同时配置到 number 与 id 字段,作为后续去重与跨系统对照锚点;
入参 params 用 ${LAST_MODIFIED_TIME} 变量做增量窗口,pager.page_size 建议 100~200;
Target 配置为"写入空操作",表示这是一个纯查询策略,数据落到中间库供其他同步策略消费;
调度使用 */7 * * * *,轻易云的运行时自动处理分页合并与失败重试。

跨方案实战要点

拍扁结构一定要还原:聚合时先按 purchase_id 取首行作主表,再按 detail_list_purchase_id 拉明细,避免一行一单导致下游金蝶写入失败。
增量字段选 modified,不要选 created:审核/反审/修改都会改变 modified,选 created 会漏单。
状态字典必须前置维护:旺店通的状态值(待审核/已审核/部分到货/已到货等)与金蝶单据状态不一一对应,提前在轻易云的字段映射器里建立转换表。
金额字段全是字符串:所有 fee 类字段类型是 string,务必先转 decimal 再做汇总或四则运算,否则会出现拼接错误。
单位换算易踩坑:detail_list_num 是基本单位数量,num2 是辅助单位,unit_ratio 是换算系数;同步到金蝶前要确认目标单据用的是哪个单位。
detail_list_new_price 是计算字段:不要把它当源数据直接落库,稳妥的做法是按需重算,避免源系统计算口径变化时数据对不上。

踩坑复盘

坑 1:把拍扁数据当成一对一主从写入。结果是金蝶侧生成 N 张采购订单,只对应一张旺店通单据。
坑 2:增量起点用 created 导致漏单。某零售企业上线首周发现历史已审核但仍在变更的采购订单全部漏掉,改成 modified 增量后恢复。
坑 3:tax_price 与 tax_amount 含税/不含税口径混淆。源系统不同账套配置不一致,务必在中间库落一个快照字段,集成时统一口径再下发。
坑 4:状态值变更未通知。源系统升级后状态字典新增了"部分到货",金蝶侧一直收到旧状态,导致收料通知单生成时机错乱。
坑 5:purchase_no 重复。极小概率源系统会出现同一业务编号对应多张单据的情况,务必以 purchase_id 为主键、purchase_no 为业务键双保险。

何时选用

适用场景:旺店通作为采购订单源头,需要把订单与明细完整同步到金蝶云星空等下游 ERP,做采购订单、收料通知单、采购入库与结算的链路协同。边界:这是纯查询接口,不做回写;若需要把金蝶的审核/结算状态反推回旺店通,需另配写入策略。

旺店通采购订单查询接口字段手册:queryWithDetail 实战权威教程