金蝶云星空供应商接口字段手册权威教程：易快报→金蝶供应链集成实战

这个接口解决什么问题

在易快报与金蝶云星空的供应链集成里,「金蝶供应商」是一张高频被联查的主数据表:采购订单、付款申请、日常报销、采购退单四条业务线都要根据供应商编码判定币别与收付对象。一旦供应商主数据延迟或缺编码,下游所有单据都会卡住。本篇把 26 个策略里与供应商相关的踩坑经验聚合成一份权威教程。

接口能力总览

• 认证方式:金蝶云星空采用 OAuth2 + 内置用户(KDCloudStdKong)的签名机制,接入参数包括 acctId、appId、appSecret、user、orgId,在轻易云适配器中以「连接器」统一托管。
• 请求/响应结构:查询走 Kingdee.BOS.WebApi.ServicesStub.DynamicFormService.View,保存走 Save 接口,FormId=BD_Supplier,返回 ResultType 与 Status。
• 分页/增量模式:支持 Limit/StartNum 分页(单页 ≤ 100),增量字段 updateTime,通过 LAST_SYNC_TIME 游标推进;全量校验时按 orgId 维度遍历。

典型字段映射

在轻易云上如何配置

在轻易云里,金蝶供应商同步通常封装为「金蝶云星空适配器 + 主数据策略」。我们用一个「供应商同步」连接器承载认证与分页,再用字段映射器把易快报的 entityId、name、bankAccount 等字段一一对到 BD_Supplier 的 FNumber/FName/FBankAccount。轻易云的字段映射器会自动跑银行账号清洗脚本,并把结果写入平台缓存,供策略 G/H/K/R/V 联查「国内外供应商」用于币别分支判断。增量游标 LAST_SYNC_TIME 写在策略级变量里,失败记录落 StrategyErrorDetail,由策略 Y 合并邮件告警。

跨方案实战要点

1. 主数据先行:供应商、部门、员工三类基础资料必须先于业务单据执行,否则下游联查拿不到编码,会导致整批失败。
2. 编码映射集中维护:物料、客户、供应商、部门四类编码单独建映射表,不要散落在每条策略里,平台缓存是更稳妥的「共享字典」。
3. 币别靠联查而非硬编码:FCURRENCYID 永远从供应商主数据里按「国内/国外」分支计算,严禁写死,否则跨国业务上线必翻车。
4. 增量字段选 updateTime:易快报接口没有专门的「最后同步时间」,稳妥的做法是用 updateTime + 排序拉取,再写入游标。
5. 付款回写必经帐表:金蝶付款回写易快报时,必须先经过采购订单帐表(P)和费用审核帐表(U)缓存,按 fsrcbillno 展开成多条 dataLinks,直接回写会导致单据错位。
6. 银行账号等敏感字段做脚本清洗:去空格、仅保留数字,平台不要保存明文,生产环境用 HTTPS + 加密存储。

踩坑复盘

• 翻车点 1:供应商主数据没同步完就触发下游采购订单,导致 FCURRENCYID 全部为空,金蝶保存报 4xx。应对:依赖关系上把策略 E 提到第一阶段,调度平台做阶段编排。
• 翻车点 2:易快报员工同步比供应商晚,日常报销里按收款对象类型分支时查不到员工编码。应对:策略 I 必须先于 R 执行,收款对象为员工时 fallback 到「未知员工」并告警。
• 翻车点 3:银行账号写入金蝶时未做清洗,带空格直接保存,后续付款行校验失败。应对:在 AfterSourceInvoke 加脚本清洗,不要依赖金蝶侧自动 trim。
• 翻车点 4:增量同步用 createTime 过滤,导致 updateTime 晚于 createTime 的「修改单」漏掉。应对:统一用 updateTime,并在策略里写排序 orderBy=updateTime。
• 翻车点 5:限流 429 时未退避,触发金蝶临时封禁。应对:429 按 60s/120s/300s 指数退避重试 3 次,失败后写死信队列并告警。

何时选用

本接口适用于易快报/轻易云中间层向金蝶云星空同步供应商主数据,以及由此衍生的采购订单、付款申请、日常报销、采购退单等业务单据。若源系统不是易快报,字段命名会变,但「主数据先行 + 编码映射 + 币别分支 + 增量游标」这套方法论依然通用;若目标系统换成 SAP/用友,需重新适配分页与 FormId。