金蝶云星空 WebAPI 实测：两个接口参数结构不一样，还有这几个坑

做金蝶云星空对接，文档看一遍觉得不难，真动手调才发现好几个地方跟想的不一样。这篇是我们实际调通之后记下来的，不是照文档抄的。

测试环境：金蝶官方公开的体验环境（experience.ik3cloud.com），只做了只读查询，没有调用保存、提交、审核，也没有改动这个公共环境的数据。客户实际账套里的自定义字段，仍然要单独确认。

接口地址长这样

/k3cloud/Kingdee.BOS.WebApi.ServicesStub.<服务>.<方法>.common.kdsvc

比如单据查询和单据详情：

/k3cloud/Kingdee.BOS.WebApi.ServicesStub.DynamicFormService.ExecuteBillQuery.common.kdsvc
/k3cloud/Kingdee.BOS.WebApi.ServicesStub.DynamicFormService.View.common.kdsvc

注意：在浏览器里看星空网页自己发的请求，走的是另一个命名空间 Kingdee.BOS.ServiceFacade...，那是星空前端的内部接口，不要拿来做对接。

坑一：两个接口的参数结构不一样

ExecuteBillQuery（单据查询）：FormId 放在 data 里面

{
  "data": {
    "FormId": "SAL_SaleOrder",
    "FieldKeys": "FBillNo,FDate,FCustId.FName,FSaleOrgId.FName,FDocumentStatus",
    "FilterString": "",
    "OrderString": "",
    "TopRowCount": 0,
    "StartRow": 0,
    "Limit": 3
  }
}

View（单据详情）：formid 放在最外层，而且是小写

{
  "formid": "BD_SAL_PriceList",
  "data": { "Number": "TY002" }
}

如果照着 ExecuteBillQuery 的习惯把 formid 写进 data 里，会报错：

表单标识为空，请确认接口参数中是否已给单据标识赋值。

同一个服务下的两个方法，一个要大写放里面，一个要小写放外面。第一次调基本都会在这里卡一下。

坑二：查询返回的是二维数组，不是对象

ExecuteBillQuery 返回的不是「字段名: 值」的对象，而是一行一个数组：

[["XSDD000001","2018-01-01T00:00:00","金蝶云科技有限公司深圳分公司","金蝶蓝海销售公司","C"]]

列的顺序就是你传的 FieldKeys 的顺序。解析时只能按位置取值，不能按字段名取。FieldKeys 顺序一改，解析代码就得跟着改——这是很多对接程序上线后出错的原因。

View 返回的是完整对象，字段很全，一张价目表实测返回了 55KB 左右。

坑三：FormId 不能凭命名规律猜

下面这几个是实测确认过的：

单据	FormId
销售订单	`SAL_SaleOrder`
销售出库单	`SAL_OUTSTOCK`
客户	`BD_Customer`
物料	`BD_MATERIAL`
销售价目表	`BD_SAL_PriceList`
应收单	`AR_receivable`

看到销售订单是 SAL_SaleOrder，很自然会以为销售价目表是 SAL_PriceList。实际不存在，会报「标识为'SAL_PriceList'的业务对象不存在，或者被删除」。正确的是 BD_SAL_PriceList。

大小写也没有统一规律：SAL_OUTSTOCK 全大写，AR_receivable 后半截小写。每个 FormId 都要实际验证过再用。

几个字段写法

取关联对象的字段用点号：FCustId.FName 取客户名称，FSaleOrgId.FName 取销售组织名称
状态值：单据状态 C 表示已审核；禁用状态 A 表示正常
多语言字段（名称、描述）返回数组：2052 简体中文、1033 英文、3076 繁体
组织字段：CreateOrgId 创建组织、UseOrgId 使用组织。多组织的账套，对接时必须指定，否则数据会进错组织

登录：公有云新账套只能走第三方授权

金蝶云星空公有云的新账套，已经不支持用账号密码调用接口，要走「第三方系统登录授权」：

金蝶管理员登录星空，进入系统管理下的「第三方系统登录授权」，新增
点「获取应用 ID」，按提示在应用市场填写信息并提交，生成应用 ID 和应用密钥
指定一个集成用户
把服务器地址、数据中心 ID、集成用户名、应用 ID、应用密钥交给对接方

所以对接前要先跟客户的金蝶管理员约好这一步，不然代码写完了也连不上。

顺带一个发现：价目表的维度很细

看销售价目表的完整结构，星空本身就能做「同一个货不同客户不同价」，而且维度很细：按客户、客户分组、客户类型定价；按物料、物料分组定价；数量区间的阶梯价；表头和明细两层生效日期；最低价限制；多组织隔离。价目表还要审核才生效。

也就是说，已经在用星空的客户，「不同客户不同价」这件事星空自己能做，犯不着为这个另外开发。真正难的通常是：规则太多太细，小团队用不过来。

小结

ExecuteBillQuery 的 FormId 在 data 里，View 的 formid 在外层且小写
查询结果是二维数组，按 FieldKeys 顺序取值
FormId 逐个验证，不能凭命名猜
多组织账套必须指定组织
公有云新账套走第三方系统登录授权，提前约好客户管理员

我们把这些处理放进了开单系统对接金蝶的对接演示里，可以直接点。

实测环境：金蝶官方公开体验环境，仅只读查询。登录授权流程参考金蝶云社区「金蝶云星空系统集成（WebAPI）」。金蝶、金蝶云星空为金蝶软件（中国）有限公司的商标，本文仅用于技术说明，鹰翔科技与金蝶不存在隶属、代理或授权关系。