金蝶云星空收料通知单(PUR_ReceiveBill)接口字段手册与实战教程

这个接口解决什么问题

在零售与分销行业的供应链集成里,采购到货是最容易对不齐的一环:供应商送货、收料验收、入库核销往往分散在 ERP 与电商系统之间。PUR_ReceiveBill(收料通知单/采购收料单)接口让我们按分页批量拉取金蝶云星空中的收料明细,与旺店通等前端系统的采购单、送货单进行对账和状态同步,是构建「采购到货—验收—入库」链路的事实基础。

接口能力总览

• 认证方式:金蝶云星空 WebAPI,需在请求头传入应用票据/签名,具体由租户身份服务颁发。
• 请求结构:POST executeBillQuery,表单 ID 为 PUR_ReceiveBill,支持字段过滤(默认 FApproveDate>='{{LAST_SYNC_TIME}}' and FDocumentStatus='C')、分页(Limit/StartRow)、字段选择。
• 响应结构:返回「表头+分录」拍扁后的行集,每条记录对应一个收料明细行,表头字段(如 FBillNo、FSupplierId)在每行重复。
• 分页/增量:以审批日期作为增量游标(FApproveDate),配合单据状态 C(已审核)过滤,避免取到暂存或作废单据;高频场景下常以 3 分钟为轮询粒度。

典型字段映射

在轻易云上如何配置

在轻易云数据集成平台中,金蝶云星空 WebAPI 通常以「适配器 + 字段映射器」组合方式接入:

• 适配器层:选择金蝶云星空 WebAPI 适配器,填入租户接入地址、票据信息,选择 executeBillQuery 动作,表单 ID 写入 PUR_ReceiveBill。
• 字段映射器:轻易云的字段映射器会按 metadata.id(FDetailEntity_FEntryID)与 metadata.number(FBillNo)自动生成主键字段,无需手工拼装;过滤条件面板可直接生成 FApproveDate>='{{LAST_SYNC_TIME}}' and FDocumentStatus='C'。
• 写入端:Target 配置为「写入空操作」,表示这是纯查询策略,仅把数据落到中台或推送给下游监听者(如旺店通对账任务)。
• 调度:平台内可直接配置 crontab(如 1-59/3 7-23 * * *),轻易云会按策略记录水位并防止重复消费。

跨方案实战要点

1. 明细级主键优先于表头主键:多个客户项目里都出现过「表头一致、分录错位」的对账差异,统一以 FDetailEntity_FEntryID 作为幂等键最稳。
2. 增量必须用审批日期 + 状态双过滤:单独按 FModifyDate 会漏掉已审核但未修改的反向场景;带 FDocumentStatus='C' 能保证只取到生效单据。
3. 多组织场景按 FStockOrgId/FPurOrgId 切片:不少零售客户存在多账套,跨组织拉取会出现「数量翻倍」。
4. 数量字段四件套要分清语义:FActlandQty(实到)、FActReceiveQty(交货)、FInStockQty(入库)、FInStockJoinQty(合格入库),错用会导致库存虚增/虚减。
5. 价格字段注意含税与本位币:FTaxPrice/FAllAmount_LC 是与下游结算对账的关键,忽略本位币会在跨币种项目里翻车。
6. 送货单号是供应商对账的最后一根稻草:FSendBillNo 在纸质单据争议时往往是唯一锚点,务必保留并写入日志。

踩坑复盘

• 坑 1:取到暂存/作废单据——只用了 FModifyDate 做过滤,导致对账出现幽灵单。稳妥做法是固定带 FDocumentStatus='C',并在写入侧做状态二次校验。
• 坑 2:分页越界丢数据——金蝶分页对总条数变化敏感,长周期增量里最后一页可能重复。轻易云会基于水位做幂等补偿,工程上也要写 id+number 联合去重。
• 坑 3:多计量单位数量错位——只用了 FInStockQty 与下游匹配,忽略 FAuxUnitQty,导致辅助单位物料对账失败。
• 坑 4:供应商编码口径不一致——FSupplierId 在不同账套里长短不一,直接当字符串拼接会错位,要做主数据映射。
• 坑 5:本位币金额被忽略——跨境/多币种项目只看 FAmount,本位币字段 FAmount_LC 没参与计算,月底对账才发现差额。

何时选用

适用于需要从金蝶云星空按明细粒度批量拉取采购收料单、并与外部电商/仓配系统做对账或状态同步的场景;不适合需要写入或回写金蝶的流程——该接口为纯查询,需配合其他写入策略完成完整业务闭环。