这个接口解决什么问题

在金蝶与钉钉的集成场景里,结算方式是收付款、费用报销、审批流绕不开的主数据。通过 ExecuteBillQuery 拉取金蝶云星空的 BD_SETTLETYPE 表,可建立统一、可信、可追溯的支付方式字典,让下游业务单据在「选择结算方式」时有据可依,避免两边口径不一致导致财务对账困难。

接口能力总览

接口协议:金蝶云星空 WebAPI,基于 ExecuteBillQuery 接口,表单 ID 为 BD_SETTLETYPE,请求方法为 POST。
认证方式:金蝶标准的第三方系统登录授权(通常采用 userName + password + appId + appSecret 或 OAuth 形式生成 access_token),由轻易云适配器封装,无需手动拼接。
请求结构:FormId、FieldKeys(字段集合)、FilterString(过滤条件)、Limit、StartRow、OrderString。
响应结构:JSON 数组,每行包含若干 FieldKey 对应值,主键与编码统一落在 Number 字段。
分页模式:基于 Limit + StartRow 翻页,单页建议 2000-5000 行,过大易触发金蝶端超时。
增量模式:通过 FilterString: FModifyDate>='{{LAST_SYNC_TIME|datetime}}' 拉取增量,定时任务常配为 1 8-22 * * *,业务时段高频刷新。
策略类型:纯查询(QUERY_ONLY),不向目标系统回写。

字段名	类型	含义	实战注意事项
Number	string	结算方式业务编码(FNumber)	metadata 中 id/number 均映射到此字段,是跨系统匹配的主键,轻易云字段映射器会自动将其作为唯一标识
Name	string	显示名称	下游展示、选择器数据源
SETTLECATEGORY	string	结算方式类别(现金/票据/银行)	财务分类统计的常用维度
TYPE	string	业务分类(收/付款)	决定下游是否可用,务必区分
PAYTYPE	string	具体支付方式	与钉钉审批单的支付方式字段对齐
FISDEFAULT	string	是否默认结算方式	单据初始化时自动带出的依据
IsSysPreset	string	是否系统预设	预设记录通常不可删,只能禁用
ForbidStatus	string	禁用状态	禁用后下游需同步隐藏,否则用户仍可选到
IsSupBankPay	string	是否支持网银付款	涉及银行类业务时强校验
FModifyDate	string	最后修改日期	增量同步唯一可靠依据,务必保留时区一致
CreateOrgId_Id/Name/Number	string	创建组织三件套	多组织隔离必用
UseOrgId_Id/Name/Number	string	使用组织三件套	同一结算方式在不同组织下可见性可能不同
CreatorId_/ModifierId_/AuditorID_/ForbidderID_	string	审计链四件套	用于追溯变更责任,轻易云会自动展开
DocumentStatus	string	单据审批状态	仅同步已审核数据可避免脏数据

在轻易云数据集成平台里,「查询金蝶结算方式」这类策略通常封装为金蝶云星空适配器的一个查询模板:

数据源配置:填写金蝶租户地址、账套 ID、应用密钥,适配器会自动维护 token 生命周期。
表单选择:下拉选中 BD_SETTLETYPE,平台会预置该表单的标准字段集合。
字段映射器:在轻易云字段映射画布里,把金蝶的 Number/Name/SETTLECATEGORY/PAYTYPE/FModifyDate 等字段拖拽到目标表结构上,内置的「id/number」合并策略会自动把 Number 同时作为主键和编码。
增量配置:FilterString 编辑器中直接引用内置变量 {{LAST_SYNC_TIME}},首次全量、后续增量无缝衔接。
调度器:可视化配置 crontab 1 8-22 * * *,平台会在窗口期内自动错峰重试。
目标写入:因为是 QUERY_ONLY,数据通常落到轻易云中台主数据池,供钉钉审批、销售订单等其他策略引用。

Number 字段双重身份要确认:在多个客户方案里,我们都把 Number 同时配作 id 与 number,跨系统匹配时千万别再用 Name 当主键,同名异码的情况极常见。
增量锚点统一用 FModifyDate:金蝶的 CreateDate 在审核、补录场景会变,但 FModifyDate 才是稳定可靠的增量依据。
禁用状态要同步下游:ForbidStatus='B' 时,下游钉钉选择器必须同步隐藏,否则用户在审批时选了已禁用的结算方式,后续生成单据会失败。
多组织三件套不能只存 ID:CreateOrgId/UseOrgId 务必把 Id/Name/Number 三件套都带过去,后续按组织过滤或回显时才会省事。
业务时段高频、夜里降频:crontab 1 8-22 * * * 是经验值,白天业务单据密集,夜里结算方式几乎不变,降低频率可省配额。
先全量后增量的两步走:第一次跑必须用空 FilterString 全量拉,确认总条数与金蝶端一致,再切增量,稳妥且容易排查问题。

FilterString 时间格式带 T 带 Z:金蝶 FModifyDate 比较要求 yyyy-MM-dd HH:mm:ss,如果用了 ISO 时间串会查不到数据或全量返回。这里容易翻车,稳妥的做法是在轻易云 FilterString 表达式里显式格式化。
系统预设记录误删:IsSysPreset='1' 的结算方式不可删除,只能禁用。如果下游逻辑是「拉过来就同步删除」会直接报错,需要在映射器里加跳过策略。
分页 Limit 过大超时:把 Limit 设到 10000 触发金蝶端 60 秒超时,接口返回空数组还以为没数据。真实场景中我们限制在 3000 以内最稳。
增量漏数据:某次 LAST_SYNC_TIME 用了 UTC,金蝶是东八区,导致凌晨那段修改漏拉。务必在轻易云时区配置里与金蝶保持一致。
同名结算方式混淆:同一家企业里「现金」和「现金(备用)」编码不同,Name 却相似。下游展示要带 Number 后缀,排查问题才能一眼定位。

适合金蝶作为结算方式唯一来源、需要把字典同步到钉钉等下游审批/报销系统、或在多个业务单据间统一支付方式口径的场景。如果业务只有现金一种支付方式,或无需跨系统联动,直接硬编码即可,不必引入本接口。