这个接口解决什么问题

付款申请单是金蝶云星空财务供应链的关键单据,承担「谁、付给谁、付多少、何时付」的申请与审批留痕。真实场景中,我们经常需要把它同步到钉钉审批流,或用于应付账款跟踪、报销对账、付款计划分析。executeBillQuery(FormId: CN_PAYAPPLY)就是金蝶官方提供的查询入口,支持按创建日期增量拉取,适合做下游系统的数据源。本节典型场景覆盖:付款审批同步、费用报销对账、付款计划跟踪、应付申请管理。

接口能力总览

协议:金蝶云星空 WebAPI,POST 请求,JSON 入参出参。
表单:CN_PAYAPPLY(付款申请单),支持头行合一扁平化返回。
认证:采用金蝶标准 API 授权(基于数据中心 ID + 应用密钥 + 用户令牌);跨方案中通常用第三方账号或专用集成账号。
分页:金蝶分页参数 Limit/StartRow 与 Kingdee 字段过滤 FilterString 配合,常配合 FieldKeys 显式声明所需字段以提速。
增量:用 FCREATEDATE>='{{LAST_SYNC_TIME|dateTime}}' 作为过滤条件,定时 0-59/10 8-22 * * *。
写入:Target 配「写入空操作」即纯查询策略,可被下游策略依赖。

典型字段映射

字段名	类型	含义	实战注意事项
FID	string	单据头主键	跨系统唯一标识,钉钉侧用做 external_id
FPAYAPPLYENTRY_FEntryID	string	分录行主键	行级对照用,不要与 FID 混淆
FBillNo	string	单据编号	业务可读编号,人肉对账首选
FDOCUMENTSTATUS	string	单据状态(暂存/提交/已审核)	增量下游建议只同步已审核
FCREATEDATE / FMODIFYDATE / FAPPROVEDATE	string	创建/修改/审批时间	增量字段;datetime 严格匹配
FAPPLYORGID / FPAYORGID / FSETTLEORGID / FPURCHASEORGID	string	申请/付款/结算/采购组织	多组织场景必带,影响后续过账
FCONTACTUNIT / FRECTUNIT	string	往来单位/收款单位	对象类型,实际值多在 `.FNumber`
FAPPLYAMOUNTFOR_H / FPAYAMOUNTFOR_H	string	表头申请/付款金额(本位币)	上游系统建议统一用本位币
FAPPLYAMOUNTFOR / FPAYAMOUNTFOR / FREALAPPLYAMOUNTFOR	string	分录行金额(原币)	与汇率联用,做币别折算
FCURRENCYID / FSETTLECUR / FEXCHANGERATE / FSETTLERATE	string	币别/汇率	外币场景务必确认汇率类型
FSRCBILLNO / FSRCROWID / FSOURCETYPE	string	源单编号/行/类型	反查上游单据、采购订单必备
FPAYPURPOSEID / FCOSTID / FEXPENSEDEPTID	string	付款用途/费用项目/费用部门	影响费用归集,别忘了携带
FEACHBANKACCOUNT / FEACHBANKNAME / FEACHCCOUNTNAME	string	收款银行信息	跨境场景同时取 FSwiftCode
FEXPECTPAYDATE / FENDDATE	string	预计/截止付款日期	付款计划看板关键字段
FCANCELSTATUS / FCLOSESTATUS	string	作废/关闭状态	全量同步时务必过滤已作废
FPRESETBASE1/2、FPRESETTEXT1/2	string	扩展预留字段	自定义扩展使用,易被忽略

在轻易云上如何配置

在轻易云数据集成平台里,我们可以直接选择金蝶云星空适配器并填入连接信息,平台会预置 executeBillQuery 的请求模板。典型做法是:

在数据源选择「金蝶云星空」,填写数据中心 ID、授权账号与对应表单 CN_PAYAPPLY;
用平台可视化字段映射器勾选目标字段,头行合一扁平模型会被自动展开为上游单据字段;
增量策略可勾选「按 FCREATEDATE 增量」,平台会用上次调度时间自动拼接 FilterString;
调度周期与原策略一致(每 10 分钟 8-22 点),Target 选「空操作」即可发布为纯查询策略,供下游同步策略依赖。

轻易云的字段映射器对对象型字段(如 FCONTACTUNIT.FNumber)做了智能取数,不需要再手写 Groovy;对 FPAYAMOUNTFOR_H、FAPPLYAMOUNTFOR_H 等带 _H 后缀的表头汇总字段会自动重命名为 apply_amount/pay_amount,贴合下游对接语义。

跨方案实战要点

头行合一模型必须按行拆解:同一行既有表头字段又有分录字段,集成时建议「主键+分录主键」做联合去重,否则下游会重复消费。
对象型字段只取 .FNumber:FSETTLEORGID、FCONTACTUNIT、FRECTUNIT 等在金蝶侧是对象,真实场景中只取编码才能跨系统对齐。
本位币 vs 原币双轨保留:FAPPLYAMOUNTFOR_H(本位币)用于汇总报表,FAPPLYAMOUNTFOR(原币)用于核对外币单据,不要只取其一。
增量字段优先选 FCREATEDATE:相比 FAPPROVEDATE,创建日期更稳定,不会因反审核重审导致漏单;若有反审核场景再叠加 FMODIFYDATE。
状态过滤放在源头:只同步 FDOCUMENTSTATUS='已审核' 且未作废未关闭的单据,可减少下游 70% 以上噪声数据。
时间窗口对齐调度:金蝶侧 cron 8-22 点每 10 分钟执行,下游写入策略应错开 1-2 分钟,避免读写并发冲突。

踩坑复盘

坑 1:对象字段返回完整对象导致反序列化失败。应对:FilterString 不变,字段映射时只取 .FNumber,并在轻易云映射器里勾选「扁平取值」。
坑 2:增量时间未格式化,金蝶返回 0 条。应对:FilterString 必须使用金蝶识别的 yyyy-MM-dd HH:mm:ss,用 {{LAST_SYNC_TIME|dateTime}} 模板注入,不要传 ISO-8601。
坑 3:把 FID 当 FBillNo 用,导致下游查不到单据。应对:人肉对账与展示用 FBillNo,接口幂等键用 FID,二者职责分离。
坑 4:表头金额与分录金额混用,合计对不上。应对:汇总用 *_H 系列,明细用 FAPPLYAMOUNTFOR,报表层做 SUM 前先分组校验。
坑 5:多组织场景漏带 FAPPLYORGID,下游写错账套。应对:把组织字段加入主键映射,路由阶段按组织分流目标账套。

何时选用

适用于金蝶云星空 → 钉钉/BI/报表系统的付款申请单数据同步,尤其是需要按创建时间增量拉取、做审批对账或付款计划跟踪的场景。若业务仅需手工审批留痕,可改用金蝶工作流引擎直接处理,无需本接口;若需反写金蝶侧付款单,需切换到 saveBill 接口而不是 executeBillQuery。

金蝶云星空付款申请单接口字段手册权威教程(executeBillQuery/CN_PAYAPPLY)