金蝶云星空辅助资料查询接口字段手册权威教程

这个接口解决什么问题

金蝶云星空的「辅助资料明细」接口用于批量拉取系统内置的字典型主数据，例如国家、省份、地区、行业分类、客户等级等枚举值。在 CRM 与 ERP 集成场景里，CRM 端的地址、行业、级别等下拉框往往需要与金蝶保持一致；该接口就是把这些字典从金蝶同步到 CRM 主数据层的标准入口，避免双端维护导致的数据漂移。

接口能力总览

• 认证方式：金蝶云星空 WebAPI，调用方需传入 acctId、userName、password（或签名票据）换取 SessionToken，再以 Token 调用查询接口。
• 请求结构：基于通用单据查询接口 executeBillQuery，Body 中通过 formId、fieldKeys、filterString、orderString 拼接查询条件。
• 响应结构：返回 JSON 数组，每条记录对应一个辅助资料明细行；外层包含 Result（数据）与 ResponseStatus（状态码、错误信息）。
• 分页模式：通过 limit 与 startRow 控制单次返回条数，单次建议 200~500 条，避免大数据量超时。
• 增量模式：金蝶原生未提供时间戳增量字段，实战中通常采用「全量 + 状态过滤」每日定时同步，或借助 FModifyDate 字段做拉链增量。
• 默认过滤：FId.FNumber in ('Country','SSQY','Provincial') 与 FDocumentStatus='C'、FForbidStatus='A'，确保只同步已审核、未禁用的有效地理区域数据。

典型字段映射

在轻易云上如何配置

在轻易云数据集成平台里，金蝶云星空被封装为「金蝶云星空适配器」，平台已内置 BOS_ASSISTANTDATA_DETAIL 这一业务对象的元数据。我们在轻易云的「数据源 → 业务对象」中选择该对象后，字段映射器会自动列出上表全部字段，免去手工拼 fieldKeys 的麻烦。过滤条件既可以沿用平台默认的「类别 + 审核 + 未禁用」三件套，也可以在「自定义过滤」里叠加 FUseOrgId_FNumber 做多组织裁剪。返回结果是数组时，轻易云的「数组展开」组件会自动把每一行拍平成一条记录，后续直接对接 CRM 的写入节点即可。

跨方案实战要点

1. 类别先收敛再同步：先与业务方确认到底要哪几类辅助资料（如只同步国家与省份，不同步行业），再用 FId.FNumber in (...) 收敛，避免一次性把全量字典拉过来污染 CRM 字典池。
2. 状态双过滤必须保留：FDocumentStatus='C' 与 FForbidStatus='A' 是数据质量的护栏，轻易云里建议把它们放在「基础过滤」而不是「业务过滤」，防止后续配置变更时被覆盖。
3. FParentId 需要二次查询：金蝶只返回父节点 ID 并不返回父节点名称，构建树形下拉时必须在 CRM 端再做一次关联或回查金蝶，避免前端渲染出 undefined。
4. 编码做唯一键而非名称：跨系统对照一律以 FNumber 为锚点，FDataValue 仅作展示；名称可能被业务人员改，但编码稳定。
5. 分页大小与超时平衡：单次 500 条在数据量大的客户场景里会偶发超时，稳妥值是 200 条；若轻易云运行日志里频繁出现 Read timed out，把 limit 降到 100 通常立竿见影。
6. 增量用 FModifyDate 更稳：金蝶官方未声明增量字段，但我们多个项目验证 FModifyDate 可靠，建议在轻易云里把它加到拉链增量条件中。

踩坑复盘

1. 类别编码大小写不一致：某客户金蝶环境里 ssqy 与 SSQY 同时存在，导致过滤条件只命中一半；建议同步前先 SELECT DISTINCT FId_FNumber 摸清实际编码。
2. 未禁用过滤漏掉导致下拉出现已作废项：禁用字典仍在缓存里，CRM 用户选了之后单据保存失败；务必把 FForbidStatus='A' 加进默认过滤。
3. 多组织下 UseOrg 越权：未带 FUseOrgId_FNumber 过滤时会把其他组织的辅助资料也拉过来，CRM 端出现不该看到的内部组织字典；务必按使用组织裁剪。
4. 树形结构只查了一层：只查 Country 没查 Provincial，下拉里省份直接挂在国家下，层级错乱；类别范围里要把上下级类别一起勾选。
5. 字段命名带下划线在 CRM 端报错：金蝶返回的是 FId_FNumber，CRM 写入节点字段名若误写为 FId.FNumber 会直接报字段不存在；轻易云的字段映射器会自动做驼峰/下划线归一化，但手工 SQL 写入时要留意。

何时选用

该接口适用于「CRM 需要从金蝶拉取枚举/字典型主数据并保持一致」的场景，尤其是地理区域、行业、客户等级等长期稳定的数据。若业务方要求「实时」更新金蝶字典，应改用金蝶的变更通知或消息中心，而不是高频轮询本接口；当数据量极小（如只有几条）时，也可以直接走手工维护，不必为此搭建集成链路。