金蝶云星空集成指南:WebAPI 鉴权与单据读写

接口形态总览

金蝶云星空对外提供 WebAPI,统一挂载在 /K3Cloud/ 路径下,调用方式为 HTTP POST,Content-Type 为 application/json。接口地址即"服务全名":

{服务器地址}/K3Cloud/{服务命名空间}.{服务类}.{方法}.common.kdsvc

核心三个接口:

第一步:ValidateUser 登录

登录是后续一切调用的前提,成功后服务器返回会话 Cookie(kdservice-sessionid),后续请求需携带。

请求体参数(按数组顺序传):账套 ID(acctID)、用户名(username)、密码(password)、语言 ID(lcid,中文 2052,英文 1033,繁体 3076):

{
  "parameters": ["5f3a9c1e2b7d01", "api_user", "your_password", 2052]
}

要点:

• 账套 ID 是数据中心的 FDATACENTERID,不是账套编码,可在管理中心查询;
• 建议为集成单独建账号,只授必要权限,密码定期轮换;
• 会话有过期时间,长期运行的集成程序要处理会话失效后自动重登;
• 星空新版同时支持 AppID/AppSecret 方式登录(Login 接口),适合无法保存明文密码的场景。

第二步:ExecuteBillQuery 单据查询

以查询销售订单(表单标识 SAL_SaleOrder)为例:

{
  "parameters": [{
    "FormId": "SAL_SaleOrder",
    "FieldKeys": "FBillNo,FCustId.FNumber,FSaleOrgId.FNumber,FDate",
    "FilterString": "FModifyDate >= '2026-06-01 00:00:00'",
    "OrderString": "FModifyDate ASC",
    "TopRowCount": 0,
    "StartRow": 0,
    "Limit": 2000
  }]
}

陷阱提示:

• FieldKeys 里基础资料字段要用 Fxxx.FNumber 取编码,直接写字段名返回的是内码;
• 返回结果是无表头的二维数组,字段顺序与 FieldKeys 一致,要自己按位置对应;
• FilterString 用 SQL 风格字符串,注意防注入与日期格式;
• 大批量拉取必须用 StartRow + Limit 分页,单次建议不超过 2000 行。

第三步:Save 保存单据

保存销售订单的核心结构:

{
  "parameters": [{
    "FormId": "SAL_SaleOrder",
    "Data": {
      "NeedUpDateFields": [],
      "NeedReturnFields": [],
      "IsDeleteEntry": true,
      "ValidateFlag": true,
      "NumberSearch": true,
      "Model": {
        "FCustId": { "FNumber": "CUST001" },
        "FSaleOrgId": { "FNumber": "100" },
        "FSaleOrderEntry": [
          {
            "FMaterialId": { "FNumber": "SKU0001" },
            "FQty": 10,
            "FTaxPrice": 99.5
          }
        ]
      }
    }
  }]
}

要点:

• NumberSearch: true 表示基础资料按编码(FNumber)匹配,这是集成场景的标配;
• Model 的结构必须与 BOS 里单据的字段结构一致,分录是数组;
• Save 只保存不审核,需要审核要再调 Submit + Audit;
• 幂等控制:保存前先按外部单号字段(建议占用单据头上的自定义文本字段存外部单号)查询,存在则走更新逻辑。

稳定性建议

1. 登录、查询、写入封装成带重试的客户端,网络抖动与 5xx 自动重试;
2. 查询走增量(FModifyDate),窗口与调度频率匹配,避免全量扫表;
3. 写入失败要解析返回的 Result.ResponseStatus,把金蝶的业务错误信息原文落日志;
4. 所有请求记录请求/响应原文(脱敏后),这是与金蝶顾问对数时最有力的证据。