这个接口解决什么问题

在 MySQL 与金蝶云星空的供应链集成里,付款单(AP_PAYBILL)是连接业务前台与财务后台的关键单据。我们需要把金蝶侧的付款明细、实付金额、往来单位、银行账号等信息稳定地拉到 MySQL 侧,用于付款对账、应付余额核对、跨系统单据关联与财务稽核。这个接口本质是一个纯查询适配器,只负责把数据从金蝶拉出来,不写回目标系统。

接口能力总览

接入方式:金蝶云星空 WebAPI,基于 HTTP(S) 调用,需要先在金蝶侧申请并配置应用凭证。
接口方法:ExecuteBillQuery(POST),FormId 固定为 AP_PAYBILL。
认证:采用金蝶云星空的 API 认证机制(通常为应用 ID + 应用密钥 + 租户信息),由轻易云适配器统一托管。
请求结构:Filter 字符串 + 字段集合 + 分页参数(SQL 风格的 SELECT/FROM/WHERE/LIMIT)。
响应结构:返回二维结果集,字段名与 metadata 中的 field 一一对应。
分页/增量:通过 LIMIT/OFFSET 实现分页;增量通常以 FModifyDate 作为游标字段,按时间窗口滚动拉取。
策略类型:QUERY_ONLY,不向目标系统写入数据,只做数据同步与对账支撑。

典型字段映射

下表摘自多个客户项目中的高频使用字段,已经过脱敏处理。

字段名	类型	含义	实战注意事项
FPAYBILLENTRY_FEntryID	string	分录行主键	在 metadata 中作为 `id`,用于增量同步去重
FID	string	表头主键	标识整张付款单,与 FEntryID 配合形成主从关系
FBillNo	string	单据编号	在 metadata 中作为 `number`,跨系统对账的业务主键
FDOCUMENTSTATUS	string	单据状态	集成侧通常只取"已审核",避免拉到暂存单
FCreateDate / FModifyDate	string	创建/修改时间	增量同步的核心游标字段,稳妥起见按 FModifyDate
FApproveDate / FAPPROVERID	string	审核日期与审核人	财务稽核常用,需要单独建表存储
FPAYTOTALAMOUNTFOR_H / FPAYTOTALAMOUNT_H	string	表头应付金额(原币/本位币)	对账场景的关键字段,与 MySQL 侧应付金额比对
FREALPAYAMOUNTFOR_H / FREALPAYAMOUNT_H	string	表头实付金额(原币/本位币)	实付≠应付时,差额就是核销/手续费,需要单独记录
FPAYAMOUNTFOR	string	分录付款金额(原币)	分录级金额,核对供应商往来必备
FWRITTENOFFSTATUS / FWRITTENOFFAMOUNT	string	核销状态/金额	影响应付余额计算,务必随单据同步
FCURRENCYID / FSETTLECUR	string	币别/结算币别	通常带 FNumber 基础资料,建议拆开存编码
FEXCHANGERATE / FSETTLERATE	string	汇率/结算汇率	用于本位币折算,避免重复折算导致差异
FCONTACTUNIT / FRECTUNIT	string	往来单位/收款单位	注意区分付款对象与实际收款方
FPAYORGID / FSETTLEORGID / FPURCHASEORGID	string	付款/结算/采购组织	多组织场景下建议冗余保存,便于按组织过滤
FACCOUNTID / FPAYACCOUNTNAME	string	付款账户及名称	出纳对账核心字段
FOPPOSITEBANKACCOUNT / FOPPOSITECCOUNTNAME	string	对方银行账号与名称	跨境/对私付款时要特别留意字符集
FTHIRDBILLNO	string	第三方单据编号	跨系统关联的"桥梁字段"
FWBSETTLENO	string	银行/支付流水号	用于与银行流水核对
FBookingDate	string	期望付款日期	资金计划场景会用到
FISPOST / FPOSTDATE	string	过账状态与日期	过账后才入正式账,通常作为入账口径
FCancelStatus / FCancellerId / FCancelDate	string	作废相关字段	增量同步时建议把作废当作"逆向单据"处理
FGYSHOPNAME / FGYCUSTOMERID / FGYACCOUNTWATERID	string	管易集成扩展字段	与第三方零售系统对接时使用

在轻易云上如何配置

在轻易云数据集成平台里,AP_PAYBILL 被封装为金蝶云星空查询适配器,我们通常这样配置:

数据源选择:选「金蝶云星空」,填好 API 接入地址、账套、应用凭证等(实际由适配器统一托管)。
表单与字段:FormId 选择 AP_PAYBILL,然后在轻易云的「字段映射器」里勾选需要同步的字段,平台会自动按金蝶 metadata 拉取字段类型与基础资料引用关系。
过滤条件:Filter 用金蝶 SQL 风格的字符串,例如按 FModifyDate >= 上次同步时间 + 单据状态过滤。
增量策略:轻易云的「增量识别器」会基于主键(FPAYBILLENTRY_FEntryID)做 upsert,避免重复写入。
目标端:写入 MySQL 时,平台会根据字段映射器自动建表并执行 INSERT/UPDATE,字段命名按通用概念(参见上文映射表)更便于二次开发。
异常处理:轻易云的「容错策略」可配置网络重试、分页续传、金蝶限流退避,这是工程上必备的兜底。

跨方案实战要点

基于多个客户项目,我们提炼出以下共性经验:

永远以 FModifyDate 作为增量游标,不要用 FCreateDate——很多场景下会补单、改单,按创建时间会漏数据。
原币 + 本位币同时落库。金蝶的金额字段是成对的(原币 _FOR_H、本位币 _H),集成侧必须把两套都存,不要自己再折算,避免汇率口径不一致。
基础资料字段要拆解存储。像 FCONTACTUNIT、FSETTLEORGID 这类字段,金蝶返回的是带 FNumber 的复合对象,务必在 ETL 里把 FNumber 单独抽出来,目标端只存编码。
金额核对不要只看总金额。在多个项目里我们发现,实付金额、应付金额、核销金额、手续费需要分别核对,只看一张表的总和容易掩盖单笔差异。
第三方单据编号(FTHIRDBILLNO)是跨系统对账的桥梁。MySQL 侧的业务单据编号如果维护得好,可以和这个字段做精确关联,反向回查也很方便。
作废单据要作为"逆向事件"处理。金蝶里 FCancelStatus='B' 的单据并不是物理删除,集成侧需要把它当成"撤销"事件写入目标库,否则对账会出现"凭空消失"的金额。

踩坑复盘

踩坑 1:用 ExecuteBillQuery 时把 SelectField 写成了 SQL 风格的 *,导致金蝶返回了 200 多个字段,接口超时。稳妥做法:只勾选业务真正需要的字段,通常 30~50 个就够用。
踩坑 2:增量同步直接用 FCreateDate,结果补单、改单时数据丢失。应对:统一以 FModifyDate 为游标,且每次拉取时多回溯 5~10 分钟,处理时间窗口边界。
踩坑 3:对方银行账号含特殊字符或全角空格,落库后比对总是失败。应对:在 ETL 里做 trim + 半角化处理,统一字符集为 UTF-8。
踩坑 4:本位币金额在目标端被二次折算,导致 0.01 元的尾差对不上。应对:原币和本位币都直接从金蝶拉取,目标端不做任何汇率换算。
踩坑 5:金蝶分页参数超过单次返回上限后,后续页会被截断。应对:在轻易云适配器里开启分页续传,每页控制在 500~1000 行以内,避免触发金蝶侧超时。

何时选用

该接口适用于「金蝶云星空 → MySQL」纯查询型供应链集成,特别是付款对账、应付余额核对、跨系统单据追溯、银行流水与付款单匹配等场景。不适合用于付款单的回写或修改,因为策略类型固定为 QUERY_ONLY;若需要双向同步,应配合付款单的写入策略使用。

金蝶云星空付款单(AP_PAYBILL)接口字段手册权威教程