这个接口解决什么问题
在零售与分销场景里,采购订单是 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,做采购订单、收料通知单、采购入库与结算的链路协同。边界:这是纯查询接口,不做回写;若需要把金蝶的审核/结算状态反推回旺店通,需另配写入策略。