这个接口解决什么问题

在 ERP 与 MES、低代码平台并行的私有化环境里,物料、供应商、客户三大基础资料是所有下游单据的根基。我们在做集成时,核心目标是把金蝶云星空里的 BD_MATERIAL、BD_Supplier、BD_Customer 高质量下发到简道云的 MES 业务表单,做到编码唯一、状态可控、增量稳定。

接口能力总览

认证方式：金蝶云星空侧通常采用 OAuth2 / Cookie 登录换取 Token,简道云侧使用 API Key + App Secret 双因子鉴权。在轻易云里,这两个连接器都已预置,只需填入实例地址、账套、租户 ID 即可。

请求结构：金蝶云星空通过 /syrk/interface.do 或开放平台的 QueryExecutor 接口提交 FormId(单据标识)+ 过滤条件 + 字段集合;简道云侧通过 /api/v1/app/{app_id}/entry/{entry_id}/data 写入表单。

响应结构：金蝶返回标准的 Result.ResponseTime + Rows(字段名/值 JSON 数组);简道云返回 data._id 与 data.idCheck 幂等校验结果。

分页/增量模式：金蝶支持基于 FModifyDate / FAuditDate / FApproveDate 的时间窗过滤,页大小一般 50–500。增量同步以这些时间戳为水印,首次部署走全量,日常走增量。

典型字段映射

物料(BD_MATERIAL)

字段名	类型	含义	实战注意事项
FNumber	string	物料编码	业务主键,目标端 idCheck 必须为 true
FName	string	物料名称	注意多语言场景下 _lName 后缀
FSpecification	string	规格型号	易出现长文本截断,提前评估目标字段长度
FBaseUnitId.FNumber	string	基本单位编码	嵌套对象需展平
FMaterialGroup.FNumber	string	物料分组编码	分组变动不影响业务主键
FModifyDate	datetime	修改时间	增量水印首选
FApproveDate	datetime	审核时间	已审核数据过滤依据
FMATERIALID	string	实体主键	用于内部去重,不写入目标

供应商(BD_Supplier)

字段名	类型	含义	实战注意事项
FNumber	string	供应商编码	业务主键
FName	string	供应商名称	税务、银行信息需脱敏
FShortName	string	简称	用于列表展示
FTaxRegisterCode	string	税务登记号	敏感字段,谨慎同步
FOpenBankName / FBankCode	string	开户行 / 银行账号	银行账号属高敏感,需评估合规
FPayCondition.FNumber	string	付款条件编码	嵌套对象
FAuditDate	datetime	审核时间	增量水印
FUseOrgId.FNumber	string	使用组织	多组织必加过滤

客户(BD_Customer)

字段名	类型	含义	实战注意事项
FNumber	string	客户编码	业务主键,可复用为售后商家组
FName	string	客户名称	同名客户需结合 FNumber 区分
FTEL	string	联系电话	私域合规字段,谨慎写入
FADDRESS	string	通讯地址	注意省市区拆分
FInvoiceTitle	string	发票抬头	财务相关,需严格校验
FCustTypeId.FNumber	string	客户类别编码	嵌套对象
FForbidStatus	string	禁用状态	仅同步 A(未禁用)
FModifyDate	datetime	修改时间	增量水印

在轻易云上如何配置

轻易云对金蝶云星空有专门的适配器封装:选择「金蝶云星空」连接器,填入私有化实例地址、登录态、FormId(如 BD_MATERIAL),即可在可视化界面看到全部字段。平台提供的字段映射器会自动识别嵌套对象(如 FBaseUnitId.FNumber),展平后拖拽到简道云目标字段即可。

在轻易云里,这个接口的调用通常采用「增量 + 时间水印 + 业务过滤」的组合:在策略编排中设 FModifyDate >= {{LAST_SYNC_TIME}},再叠加 FUseOrgId.FNumber = '150' 这类组织过滤。轻易云的死信队列和重试策略按本文第 5 节配置后,单条失败不会阻塞整批。

简道云侧配置:选择「简道云」连接器,选择目标应用与表单,开启「按业务字段去重」(idCheck=true),以 FNumber 对应字段作为去重键。

跨方案实战要点

业务主键必须用编码,不要用实体主键：FMATERIALID 等内部 ID 在跨环境、跨账套时会变,只有 FNumber 才稳定。
增量水印三选一：FModifyDate 覆盖最广,FAuditDate 偏已审核,FApproveDate 偏最终生效。多组织场景建议组合 FModifyDate >= LAST_SYNC_TIME OR FApproveDate >= LAST_SYNC_TIME。
目标端 idCheck 必须开启：简道云去重依靠业务字段,不开启会导致重复写入。
业务过滤要前置：使用组织、物料编码前缀、禁用状态这些条件必须放在金蝶侧,不要在同步后过滤,否则会浪费带宽。
错峰调度三个策略：物料每 10 分钟,供应商每 10 分钟,客户每 30 分钟,且启动时间错开 5 分钟,避免对目标系统造成集中冲击。
敏感字段分级：银行账号、税务登记号、联系电话属于高敏感,在轻易云里建议走「脱敏映射器」后再写入目标。

踩坑复盘

翻车点 1:增量水印漂移。LAST_SYNC_TIME 用的是系统时间,但金蝶返回的是 UTC,结果漏数据。稳妥的做法是在轻易云的「时间格式转换」节点统一改成金蝶的时区(UTC+8)再比对。
翻车点 2:目标端重复主键。简道云的去重键用了 FName 而非 FNumber,结果同名物料全部冲突。务必以编码作为业务主键。
翻车点 3:全量模式下时间过滤未移除。某零售企业首次部署时没去掉 FModifyDate >= LAST_SYNC_TIME,导致只同步了最近一批,历史数据全丢。
翻车点 4:Token 过期未配置自动刷新。金蝶 OAuth2 Token 默认 7200 秒过期,轻易云连接器开启「自动刷新」后能避开 401 风暴。
翻车点 5:禁用客户同步进了售后商家组。某次没加 FForbidStatus = 'A' 过滤,售后页面出现了已禁用客户,导致客诉。

何时选用

这套接口组合适合 ERP 主数据向低代码/MES 平台下发的私有化场景,尤其是物料、供应商、客户三大基础资料需要高频同步且对编码一致性要求严格的制造业、零售业。若目标端是交易类大表或需要双向同步,则需要引入更复杂的冲突检测与版本控制策略。

金蝶云星空基础资料接口字段手册：从物料、供应商到客户的实战权威教程