金蝶云星空结算方式查询接口字段手册权威教程

这个接口解决什么问题

在金蝶与钉钉集成场景里,结算方式是收付款单据、费用报销、审批流选择的必备基础资料。该接口(ExecuteBillQuery / FormId: BD_SETTLETYPE)用于按修改时间增量拉取金蝶云星空的结算方式主数据,落地到下游系统供业务选择,解决跨系统支付方式编码不统一、新增/禁用结算方式无法及时同步等痛点。

接口能力总览

• 认证方式:金蝶云星空 OAuth / 第三方 Token(在轻易云连接器中统一托管)。
• 请求方法:POST,接口路径形如 /kapi/v2/bd/settletype 风格,实际走 Kingdee 通用查询 API。
• 请求体:包含 FormId=BD_SETTLETYPE、FilterString、FieldKeys、Limit、StartRow、TopRowCount。
• 响应结构:返回 Result.ResponseStatus.IsSuccess 与 Result.Result 数组,每行包含 Number、Name、SETTLECATEGORY、TYPE、PAYTYPE 等业务字段。
• 分页模式:采用 Limit + StartRow 循环分页,TopRowCount 用于判断总量。
• 增量模式:FilterString 使用 FModifyDate>='{{LAST_SYNC_TIME|datetime}}',定时任务 1 8-22 * * * 每小时拉取。

典型字段映射

在轻易云上如何配置

• 适配器:在轻易云连接器市场选用「金蝶云星空·ExecuteBillQuery」适配器,FormId 直接填 BD_SETTLETYPE。
• 字段映射器:轻易云字段映射器会自动把 Number、Name、SETTLECATEGORY 等金蝶字段名映射为通用名(settlement_type_code 等),支持一键转换 Id/Name/Number 三件套。
• 增量变量:平台内置 {{LAST_SYNC_TIME|datetime}} 变量,首次同步置零,后续自动滚动。
• 触发与定时:策略调度中配置 1 8-22 * * *,轻易云的调度器会负责断点续跑与超时重试。
• 落地目标:本策略为 QUERY_ONLY,落地到轻易云数据池即可,后续由钉钉侧订阅使用。

跨方案实战要点

1. 主键必须用 Number 而非 FNumber:金蝶 ExecuteBillQuery 返回的字段名是 Number,metadata 中 id/number 都指向 Number,千万别写成 FNumber,否则增量匹配会全量复活。
2. 增量水位一定要走 FModifyDate:多个项目踩过这个坑——用 CreateDate 做增量会导致后续修改永远同步不到下游。
3. 禁用态要过滤:ForbidStatus='B' 表示禁用,下游(钉钉选择器、报销单)必须过滤禁用项,否则会出现选了结算方式却落不到付款单的尴尬。
4. 多组织三件套要看 UseOrgId:跨组织可见性由 UseOrgId 控制,CreateOrgId 仅表示创建方;做权限过滤时务必以 UseOrgId 为主。
5. 预设项不要试图删除:IsSysPreset='Y' 的结算方式是金蝶系统预设(如现金),只能禁用,删除会报业务校验错误。
6. 审计字段三件套下游建议取 Name:轻易云映射器可一键拆解,减少下游系统冗余字段。

踩坑复盘

• 坑1:FieldKeys 没声明导致返回字段空。稳妥做法是在请求体里显式列出所有需要的字段(包括 Id/Name/Number 后缀),不要依赖默认全量返回。
• 坑2:FModifyDate 时区错位。金蝶返回的是 UTC+8 字符串,如果下游用 UTC 解析会差 8 小时,导致增量漏单。务必在轻易云变量格式化时指定 |datetime 并锁定时区。
• 坑3:票据类结算方式没填 FRECBILLTYPE。某零售企业的「银行承兑汇票」结算方式漏配票据类型,后续生成付款单时票据模块无法关联,排查了两天才定位到这里。
• 坑4:默认结算方式被覆盖。同步时若直接拿全量覆盖下游配置,FISDEFAULT='Y' 的记录一旦被禁用,下游就找不到默认项了。稳妥做法是仅同步启用项,默认项变更通过单独策略下发。
• 坑5:定时窗口外的修改漏同步。crontab 设的 8-22 点窗口,凌晨修改的结算方式要等第二天 8 点才被捞到;对结算方式这种低频变更可接受,但务必在 SLA 文档里写明。

何时选用

适合金蝶云星空与钉钉(或异构系统)集成,需要在下游做收付款选择、报销审批的基础资料同步场景。不适合需要双向同步、字段深度自定义、或非金蝶单据的结算体系;此类情况应走自定义连接器或单据映射策略。