金蝶云星空·采购退料申请查询接口字段手册：从分录到退料类型，一次讲透

这个接口解决什么问题

「采购退料申请单」是金蝶云星空供应链域的核心单据之一，承载企业向供应商退货/补料/扣款的业务过程。该接口主要用于把金蝶中的退料申请数据拉取到电商或供应链协同系统（如旺店通），用于状态同步、对账、库存回冲与供应商结算，是采购退货闭环的关键数据源。

接口能力总览

• 所属系统：金蝶云星空（公有云部署）。
• 请求方式：通常基于金蝶云星空的 QueryService（WebAPI/BOS 查询服务），传入 FormId 与过滤条件。
• 认证方式：金蝶云星空采用第三方应用授权 + 接口密钥签名；通过轻易云调用时，平台会自动维护 Token 刷新与会话续期。
• 响应结构：主从扁平结构，单据头字段（如 FBillNo、FID、FDate）与明细行字段（如 FEntity_FEntryID、FMATERIALID_Fnumber、FMRQTY）同层返回，一条记录 = 一个明细行。
• 分页/增量：金蝶云星空 QueryService 支持分页参数（页号、页大小）与增量时间戳过滤，集成时通常以 FModifyDate 作为增量游标，按 Top > LastModifyTime 顺序轮询。

典型字段映射

在轻易云上如何配置

在轻易云数据集成平台里，这个接口通常通过金蝶云星空适配器调用，配置分四步：

1. 新建数据源：选择金蝶云星空，填入租户信息与接口密钥，平台会自动完成 OAuth 授权与会话管理。
2. 选择业务对象：在「采购退料申请单」模板上拖拽式建模，平台已预置 FormId、字段类型与枚举值字典。
3. 配置字段映射器：轻易云的字段映射器会按字段名自动匹配 Fxxx 系列字段到目标系统（如旺店通）。对于多套数量单位（库存/基本/采购/计价），建议先在「数量单位转换」算子里固定一套基准单位，再做映射，避免下游因单位不同产生数量漂移。
4. 配置增量与调度：以 FModifyDate > ${lastSyncTime} 作为增量条件，配合轻易云的内置调度即可实现准实时轮询。

跨方案实战要点

在多个零售/电商客户项目里，我们反复验证了以下经验：

1. 只同步已审核单：A/B 状态的退料申请在金蝶侧仍可修改，下游收到后极易产生数据抖动，建议在过滤条件中强制 FDocumentStatus='C'。
2. 业务类型先路由再映射：CG/标准采购、WW/委外、VMI 三种业务的下游仓库与结算逻辑差异巨大，集成时必须先按 FBusinessType 分流，再各自映射。
3. 退料 vs 补料 vs 扣款的数量三套制：FMRQTY（实际退料）、FREPLENISHQTY（补料）、FKEAPAMTQTY（扣款）三者根据 FRMMODE 取舍，不要把三者相加做合计。
4. 用 FPOORDERENTRYID 做关联键：比 FORDERNO 更稳定，避免单据编号重复或被改单时丢关联。
5. 单位换算提前固化：同一物料在金蝶里有库存单位、基本单位、采购单位、计价单位四种，建议在轻易云里先做一次「统一基本单位」转换，下游只认一个数。
6. 增量游标必须含 FModifyDate 而非 FCreateDate：退料单会反复修改（补充备注、补料改单），用创建时间会漏数据。

踩坑复盘

• 坑 1：审核后又修改的单据拉不到。金蝶云星空的 QueryService 默认按修改时间排序没问题，但若在过滤条件里加了 FDate，会导致审核后修改的单据漏拉。稳妥做法是只按 FModifyDate 过滤。
• 坑 2：扣款数量误读为退货数量。FRMMODE=B（退料并扣款）时，FKEAPAMTQTY 才是真正影响供应商结算的字段，而 FMRQTY 只是物理退货量。集成时务必根据 FRMMODE 取数。
• 坑 3：套件父项/子项混传。FRowType=Parent 的明细行会把子项数量汇总在一起，直接同步会重复计算。应在映射时跳过 Parent 行，只同步 Son/Standard 行。
• 坑 4：仓位 FSTOCKLOCID 为空导致下游报错。金蝶里仓位是非必填，但部分下游系统强制要求非空。建议在轻易云里加一个默认仓位兜底规则。
• 坑 5：分页越界抛异常。金蝶 QueryService 在最后一页不足 pageSize 时会返回空数组，而非错误码；调度器若按异常重试会陷入死循环。稳妥的做法是：轻易云的调度器已内置「空响应即认为完成」逻辑，无需额外处理。

何时选用

该接口适用于「金蝶云星空 → 电商/供应链协同系统」的单向退料数据同步场景，尤其在多组织、多业务类型（标准采购/委外/VMI）的零售与制造企业。当企业同时存在质检退料与库存退料、且退料后续涉及补料或扣款结算时，本接口几乎是唯一权威来源。仅做库存台账同步或单据存档的场景，则不必启用。