金蝶云星空银行账户查询接口字段手册权威教程

这个接口解决什么问题

在金蝶云星空与小满 OKKICRM 的供应链集成中，银行账户主数据是回款单、收款单据、开票信息的公共引用基础。CN_BANKACNT 接口用于按计划批量拉取金蝶侧的银行账户主数据，下游用于 CRM 侧银行账户对照、客户/供应商收款账户引用。纯查询策略，目标端为写入空操作。

接口能力总览

• API：executeBillQuery（金蝶云星空通用单据查询接口）
• FormId：CN_BANKACNT（银行账户主数据表单）
• 请求参数：FormId、FilterString、FieldKeys、Limit、StartRow，支持按字段集合按页拉取
• 分页模式：通过 {{PAGINATION_PAGE_SIZE}} 与 {{PAGINATION_START_ROW}} 变量控制
• 调度方式：定时任务，crontab 3 2 * * *（每日凌晨 02:03）
• 响应结构：返回 FNumber、FName、FBANKID 三个基础字段
• 集成定位：QUERY_ONLY（仅查询，无目标写入）

典型字段映射

通用概念对照：FNumber → bank_account_code，FName → bank_account_name，FBANKID → opening_bank_id。

在轻易云上如何配置

在轻易云数据集成平台中，金蝶云星空源端已封装为标准适配器，调用 executeBillQuery 只需三步：

1. 选择表单：在源端适配器下拉中选 CN_BANKACNT，平台会自动带入默认字段集合
2. 配置 FieldKeys：在轻易云字段映射器里勾选 FNumber、FName、FBANKID；如需开户银行名称，需在金蝶元数据中展开 FBANKID.FName
3. 配置分页变量：将 Limit 绑定 {{PAGINATION_PAGE_SIZE}}，StartRow 绑定 {{PAGINATION_START_ROW}}，轻易云会自动按页迭代直至拉空

由于该策略为 QUERY_ONLY，目标端配置「写入空操作」即可，轻易云不会做落库动作，仅把数据推到后续策略或临时存储区。

跨方案实战要点

1. FNumber 是唯一锚点：所有跨系统对照、客户/供应商收款账户引用一律走 FNumber，不要用 FName 匹配
2. FBANKID 双形态兼容：下游解析必须同时兼容 FBANKID.FNumber 与 FBANKID.FName，否则在不同客户环境会断流
3. 增量用 FilterString：按 FModifyDate > last_sync_time 过滤比全量重拉更稳，轻易云的变量可以直接注入时间戳
4. 凌晨调度避让：02:03 错开金蝶自身的结账与备份窗口，避免长事务阻塞
5. 字段裁剪优先：FieldKeys 只勾选业务必须字段，能显著降低单次返回体大小
6. 空操作不等于无用：QUERY_ONLY 策略往往作为后续同步策略的数据源或对账基线

踩坑复盘

• FBANKID 嵌套对象解析失败：FieldKeys 写成 FBANKID 时返回关联 ID 字符串，写成 FBANKID.FNumber 时返回编码，两种格式下游必须分别处理，否则开户银行会全部为空
• FNumber 与 FName 混淆：业务方误用 FName 作为对照键，导致重名账户串行——稳妥做法是接口层就拒绝非 FNumber 主键
• 分页变量未替换：在轻易云早期版本中，Limit/StartRow 若硬编码会导致只拉第一页，务必使用平台分页变量
• 凌晨结账撞车：crontab 与金蝶日结任务重叠时 executeBillQuery 超时，建议前后各空 30 分钟
• 权限不足返回空表：金蝶侧集成用户若缺 CN_BANKACNT 查询权限，会静默返回空数据，集成监控需要加零数据告警

何时选用

适用于金蝶云星空作为 ERP 主数据源、需要把银行账户同步到 CRM/SCM 等下游系统的场景。若下游不依赖开户银行明细、或金蝶侧已有标准 API 替代品，可评估是否合并到主数据同步策略中复用。