简介金蝶K/3 Cloud金蝶云星空WebAPI接口说明书V4.0是一份面向K3 Cloud开发者、云计算应用及第三方系统集成人员的官方技术文档目的在于解决企业云应用与外部系统之间的接口对接、数据交互和流程协同问题。全文围绕WebAPI架构、技术规范、开发工具和接口定义展开重点说明Kingdee.BOS.WebApi.FormService.dll、ServicesStub.dll、Client.dll三个核心组件的用途并给出Visual Studio、.NET Framework及K3 Cloud SDK的开发环境组合。内容预览显示文档从概述、问题与解决策略、目标和约束一直延伸到接口详细描述具体涵盖登录验证、查看、保存、批量保存、提交、审核、反审核和删除表单数据接口每个接口均含定义、参数及返回值说明同时针对接口调用失败、错误信息处理、性能优化等常见问题给出解决策略可帮助读者快速定位问题、规范调用流程。资源包为1个docx说明文档压缩包约101KB轻量实用已有1159人学习适合需要系统梳理K3 Cloud WebAPI集成能力的后端开发与实施人员。1. K3 Cloud WebAPI 接口说明书到项目落地先看认证和请求模板K3 Cloud金蝶 K/3 Cloud后续版本并入金蝶云星空产品体系WebAPI 是 ERP 对外集成使用频率最高的一套接口。V4.0 接口说明书对应的是一套已经收束下来的调用约定所有 URL 都是固定模板数据全部走 HTTP JSON学习成本集中在对认证、业务对象结构和错误码的掌握上。这套接口解决的是第三方系统与 ERP 之间的单据往返MES 要报工单WMS 要同步出入库电商中台要把订单推成销售订单动作不同底层的调用模板完全一样。接到这类任务后不需要自己发布 WebAPI 项目K3 Cloud 应用服务器已经注册好了 kdsvc 服务你只需要按文档约定组装参数并发起 HTTPS 请求。真正决定项目顺不顺利的是开始阶段的三个选择令牌怎么换、单据参数怎么传、错误从哪里定位。下面按这份说明书最常用的三条路径展开。2. K3 Cloud WebAPI 的认证方式从会话令牌到并发会话管理2.1 认证为什么是接口说明书里的头号问题K3 Cloud WebAPI 的所有业务接口包括保存、查看、查询、审核都不是无状态调用。客户端必须先完成登录认证拿到服务端认可的会话凭证后续请求才能被正常受理。V4.0 文档把这个过程放在前面的逻辑不难理解没有令牌后面的业务参数写得再正确也进不了业务服务。实际联调中认证踩坑的比例相当高。常见的问题有两个一是使用管理员账号登录权限太大日志里无法区分操作人二是密码直接明文传输被接口网关直接拒绝。更隐蔽的问题是很多团队把认证和业务调用放在两个不同的服务里会话没有共享导致 A 服务登录成功后B 服务请求又返回“未登录”。所以在设计集成层结构时第一步就要定好会话的归属和复用方式。我的建议是为集成单独建一个专用账号权限按要求的最小集合开放登录凭证统一放在网关或会话管理器里业务模块从同一个位置取凭证不做各自登录。2.2 用账号密码换取会话令牌的调用示例认证的典型调用是对 AuthService 的 ValidateUser 服务发 POST 请求。下面给出最基础的 curl 示例curl -X POST \ http://k3cloud.example.com/K3Cloud/Kingdee.BOS.WebApi.ServicesStub.AuthService.ValidateUser.common.kdsvc \ -H Content-Type: application/json \ -c /tmp/k3cloud_cookie.txt \ -d { acctID: a3f5e9d8c7b64f1b9a0c2d3e4f5a6b7c, username: erp_api, password: BASE64(RSA(明文密码)), lcid: 2052 }逐个字段说明。acctID 是数据中心标识。多账套部署时这一步决定你操作的是哪个账套。这个标识在管理中心里能看到也可以在数据库中查 t_SystemProfile 获取。username/password 是专门配置的集成账号。V4.0 文档要求密码经过 RSA 加密后再传输不能直接提交明文。客户端先从服务器获取公钥用公钥加密密码得到密文再 Base64 编码后放入 password 字段。这是很多联调项目第一次报“用户名或密码错误”的根源——不是密码错了是加密格式不对。lcid 是区域语言标识2052 表示简体中文会影响错误消息的语言。-c参数把服务端返回的 cookie 写到本地文件后续请求用-b参数带上保持会话。curl 适合做连通性验证真正常用的是客户端封装。下面是 Python requests 的会话管理示例import requests LOGIN_URL http://k3cloud.example.com/K3Cloud/Kingdee.BOS.WebApi.ServicesStub.AuthService.ValidateUser.common.kdsvc session requests.Session() def login(acct_id: str, username: str, password: str) - bool: resp session.post( LOGIN_URL, json{ acctID: acct_id, username: username, password: password, lcid: 2052, }, timeout30, ) payload resp.json() result payload.get(Result, {}) status result.get(ResponseStatus, {}) if status.get(IsSuccess, False): return True print(login failed:, status.get(Errors)) return False这里的关键点是 requests.Session 会自动保存服务端返回的 Cookie后续业务调用继续用同一个 session 实例即可不需要手工传递凭证。代码里把认证结果检查放在 ResponseStatus.IsSuccess 上而不是 HTTP 状态码——K3 Cloud WebAPI 返回 200 不代表业务成功这是接口说明书里最容易忽略的规则。2.3 会话失效与并发会话处理K3 Cloud 的会话有有效期默认约 20 分钟无操作会失效。设计集成层时要注意两点。第一不要在每次请求前重复登录。频繁调用 ValidateUser 不只浪费网络还可能触发服务端的登录频率限制。用 Session 对象复用是成本最低的方案等会话真正失效再重建。第二多节点部署时每个节点各持有一个会话是常见做法。若要共享就需要把登录凭证放到 Redis 这类集中缓存里并配合锁避免多个节点同时刷新同一个账号的会话导致互相踢掉线。业务量不大时不共享会话反而是更稳的选择。2.4 认证参数与安全配置对照表参数用途说明acctID数据中心标识对应账套不用填数据库名username登录账号建议单独建 API 用户不共享管理员password密码密文RSA 加密后 Base64不传明文lcid语言代码2052 简体中文错误信息语言HTTPS传输层生产环境必须开启防抓包会话有效期无活动超时默认约 20 分钟可调提示集成账号的权限应小于等于所需业务的最小权限集合。权限过大会让一次越权调用绕过整个审批体系这是生产事故的高发点。3. K3 Cloud WebAPI 的保存与查询一张销售订单的完整往返3.1 业务对象参数formId 和 Model 的对应关系K3 Cloud WebAPI 不采用 RESTful 资源路径URL 始终保持同一个服务地址变化的只是请求体里的参数。第一个参数永远是表单标识 formId它决定了本次操作作用于哪张业务单据。下面是集成中常用的一组映射业务对象formId说明销售订单SAL_SaleOrder核心销售单据采购订单PUR_PurchaseOrder采购流程主单物料档案BD_MATERIAL基础资料客户档案BD_Customer基础资料供应商档案BD_Supplier基础资料即时库存INV_Stock库存查询类业务对象映射表要在项目里维护成常量文件避免把字符串散落在代码各处。改一个表单标识时只需要动一处。3.2 调用 Save 接口保存销售订单保存接口在 DynamicFormService 下操作名为 Save。请求体由 parameters 数组决定第一个参数是 formId第二个参数是业务数据 JSON 字符串第三个参数是操作参数。下面的代码保存一张带客户和销售组织的销售订单import requests import json session requests.Session() # 调用第 2 章的 login()成功后继续 def save_sale_order(): payload { parameters: [ SAL_SaleOrder, json.dumps({ NeedUpDateFields: [FBillNo], NeedReturnFields: [FID, FBillNo], Model: { FBillNo: SO20241001-001, FDate: 2024-10-01, FCustomerId: {FNumber: C001}, FSaleOrgId: {FNumber: 100} } }), {} ] } resp session.post( http://k3cloud.example.com/K3Cloud/Kingdee.BOS.WebApi.ServicesStub.DynamicFormService.Save.common.kdsvc, jsonpayload, timeout60, ) result resp.json().get(Result, {}) status result.get(ResponseStatus, {}) if status.get(IsSuccess): print(saved:, result.get(Id), result.get(Number)) else: print(save error:, status.get(Errors))这段代码有几个参数值得展开。NeedUpDateFields 表示允许更新的字段。如果 Model 里带了单据编号就必须把 FBillNo 列入否则服务端认为该字段不可更新。NeedReturnFields 控制保存后返回的字段。这里只要 FID 和 FBillNo可以减少不少传输量。Model 是数据主体所有业务字段都放在这个对象里。FDate 用 yyyy-MM-dd 字符串基础资料字段用 {FNumber: 编码} 这种嵌套结构。第三个参数 {} 是操作参数空对象表示使用默认行为。如果希望保存的同时忽略一些警告可以在这层传入 IgnoreWarning 等配置。Result.Id 返回的是单据内码 FID后面做审核、作废、反审核时传这个 Id 最直接。如果未来对接流程引擎需要同时保存 Id 和业务单据号两条都能作为操作主键使用。3.3 用 View 接口回读单据并校验字段保存完成后建议用 View 把单据读出来校验而不是直接信任返回。View 操作也在 DynamicFormService 下{ parameters: [ SAL_SaleOrder, {\FID\:\${FID}\} ] }第二个参数传主键定位单据这里用 FID 定位。如果调用方手里只有业务编号也可以用 Key 或 Number 字段定位。响应返回完整表单对象包括表头、明细、基础资料引用名称拿到后可以和源系统的数据做比对。这里${FID}是占位符实际请求时替换成第 3.2 节保存返回的 Id 值。3.4 用 ExecuteBillQuery 做查询过滤与分页查询不需要拉整张表单适合用 ExecuteBillQuery。这个接口接收六个参数依次是 formId、字段列表、过滤条件、排序规则、页码、每页行数。我经常把它当成稳定的报表取数通道{ parameters: [ SAL_SaleOrder, FID,FBillNo,FDate,FCustomerId.FName,FSaleOrgId.FName, FBillNoSO20241001-001, , 0, 100 ] }字段列表里用点号连接引用属性FCustomerId.FName 代表客户基础资料的名称字段这种写法在 V4.0 文档里是标准写法。过滤条件与 SQL WHERE 语法相近支持、、、LIKE、IN等。排序规则为空字符串表示不排序也可以写 FBillNo DESC。页码从 0 开始每页行数建议不超过 1000服务端有行数限制。返回结果不是键值对象而是一个二维数组{ Result: [ [FID, FBillNo, FDate, FCustomerId.FName, FSaleOrgId.FName], [128, SO20241001-001, 2024-10-01 00:00:00, 测试客户, 华南销售组织] ] }第一行是字段名后面每行是一条数据。解析时不要硬编码字段索引建议先在联调环境拉一次真实数据按返回顺序建立字段到索引的映射表后面解析就会稳定很多。另一个约定是日期时间字段返回格式带空格分隔容易和源系统的字符串比较逻辑冲突解析时统一转成 datetime 对象再比较可以避免绕弯。4. K3 Cloud WebAPI 的单据操作与错误排错4.1 用 ExecuteBillOperation 执行提交、审核、反审核和作废保存后的单据如果直接落库通常还要走提交流程。提交、审核、反审核、作废这类状态流转统一走 ExecuteBillOperation 接口。它的参数是四项formId、操作类型、主键定位 JSON、操作参数。以下是审核一张销售订单的 Python 示例def execute_operation(form_id: str, operation: str, bill_no: str): payload { parameters: [ form_id, operation, json.dumps({Numbers: [bill_no]}), {} ] } resp session.post( http://k3cloud.example.com/K3Cloud/Kingdee.BOS.WebApi.ServicesStub.DynamicFormService.ExecuteBillOperation.common.kdsvc, jsonpayload, timeout60, ) result resp.json().get(Result, {}) status result.get(ResponseStatus, {}) if status.get(IsSuccess): print(f{operation} success: {bill_no}) else: print(f{operation} failed:, status.get(Errors))operation 参数是服务端预定义的操作类型常见值如下操作类型含义备注Submit提交从暂存到已提交Audit审核从已提交到已审核UnAudit反审核从已审核到已提交Cancel作废终止单据生命周期主键定位用 Numbers 传业务单据号列表也可以用 Ids 传内码列表两者在文档中都支持。我习惯用 Numbers因为源系统同步过来的数据里只有业务单号不额外维护内码映射。一个容易踩的坑是 Numbers 要传数组不是单个字符串。即使只处理一张单也写成[bill_no]的形式传 string 时部分版本会直接报参数类型错误。4.2 从 ResponseStatus 解析成功和失败K3 Cloud WebAPI 统一返回结构成功和失败都通过 ResponseStatus 表达。HTTP 状态码 200 不代表业务成功必须逐层判断数据结构。{ Result: { ResponseStatus: { IsSuccess: true, Errors: null, SuccessEntitys: [ { Id: 128, Number: SO20241001-001, DIndex: 0 } ] }, Id: 128, Number: SO20241001-001 } }IsSuccess 为 false 时Errors 数组里会给出错误详情。每个错误对象包含三个常用键FieldName报错字段标识例如 FBillNoMessage错误描述面向人的可读文案DIndex出错明细行的索引-1 表示表头字段错误0 及以上对应明细行号程序化处理时用三个键的组合就能快速定位不需要解析整段错误堆栈。4.3 高频错误及解决联调阶段最常遇到的错误现象和处理思路整理在下表。这些问题里的大部分不是代码逻辑问题而是参数组装与状态流转顺序问题。错误场景返回信息特征解决办法会话过期“请登录”或“登录已失效”抛弃旧会话重新走登录流程单据编号重复“编号重复”保存前按 FBillNo 查询预检基础资料不存在“客户不存在”或“编码无效”核对 FNumber 与主数据系统注意大小写和前后空格必录项为空错误里带 FieldName 和“不能为空”对照单据设计器字段属性逐项补齐状态流错误“尚未提交不能审核”先 Submit 再 Audit顺序不能跳参数类型错误“参数类型: String”检查是否将数组传成了字符串这类错误有一个共同的处理顺序先看 ResponseStatus.IsSuccess再看 Errors[0].FieldName最后核对参数原始值。不要一看到“失败”就查数据库先确认入参是否符合文档的类型和必录规则。提示登录接口如果返回“用户名或密码错误”先检查密码加密环节换了服务器或重新部署后公钥是否同步更新。这个原因导致的失败往往和账号本身无关排错方向不要一开始就锚定在密码上。5. K3 Cloud WebAPI 批量操作与集成工程化的三个落地做法5.1 用 BatchSave 一次提交多张单据逐张循环调 Save 面对几百上千条记录时耗时线性增长。文档专门提供了 BatchSave 接口第二个参数从单个业务对象变成数组def batch_save(orders: list[dict]): model_list [] for order in orders: model_list.append({ NeedUpDateFields: [FBillNo], NeedReturnFields: [FID, FBillNo], Model: { FBillNo: order[bill_no], FDate: order[date], FCustomerId: {FNumber: order[customer_code]} } }) payload { parameters: [ SAL_SaleOrder, json.dumps(model_list), {} ] } resp session.post( http://k3cloud.example.com/K3Cloud/Kingdee.BOS.WebApi.ServicesStub.DynamicFormService.BatchSave.common.kdsvc, jsonpayload, timeout120, ) result resp.json().get(Result, {}) status result.get(ResponseStatus, {}) if status.get(IsSuccess): for entity in status.get(SuccessEntitys, []): print(entity.get(Number), entity.get(Id)) else: print(batch error:, status.get(Errors))返回的 SuccessEntitys 顺序与传入顺序一致可以按索引把结果映射回原数据。每批条数我通常控制在 100 到 200 之间超过 500 条事务时间会明显变长死锁概率也在上升。5.2 按幂等性设计重试策略集成层重试要考虑操作是否幂等盲目重试可能把单子重复保存或是把“审核中”的单子再审核一次。操作是否幂等重试建议View / ExecuteBillQuery幂等可重试 3 次指数退避Submit / Audit基本幂等重试前先查状态避免状态冲突Save / BatchSave非幂等用 FBillNo 唯一键约束重复保存报重号UnAudit / Cancel幂等重试前先确认目标状态超时设置也要分开查询 30 秒Save 60 秒BatchSave 120 秒。混合设置会导致慢查询拖垮整个调用链的体验。5.3 用 request_id 串起调用链路接口层面最后一个建议是给每一次外部调用统一记录台账。开发日志里单看一条错误信息很难反推入参配合 request_id 才能把请求、响应、业务单号串起来。字段示例检索价值request_id8f3a1d2c-9b02聚合一次全链路日志form_idSAL_SaleOrder定位业务对象operationBatchSave定位操作类型bill_noSO20241001-001按单号反查cost_ms843观察性能波动statussuccess / fail快速过滤error_msg单据编号重复联调阶段最高频检索字段对接人员上门排查时往往先按 request_id 过滤日志再找对应时段的请求体。日志记录不需要保留整段响应记录 formId、操作、返回状态和错误摘要就够了。本文还有配套的精品资源点击获取
简介金蝶K/3 Cloud金蝶云星空WebAPI接口说明书V4.0是一份面向K3 Cloud开发者、云计算应用及第三方系统集成人员的官方技术文档目的在于解决企业云应用与外部系统之间的接口对接、数据交互和流程协同问题。全文围绕WebAPI架构、技术规范、开发工具和接口定义展开重点说明Kingdee.BOS.WebApi.FormService.dll、ServicesStub.dll、Client.dll三个核心组件的用途并给出Visual Studio、.NET Framework及K3 Cloud SDK的开发环境组合。内容预览显示文档从概述、问题与解决策略、目标和约束一直延伸到接口详细描述具体涵盖登录验证、查看、保存、批量保存、提交、审核、反审核和删除表单数据接口每个接口均含定义、参数及返回值说明同时针对接口调用失败、错误信息处理、性能优化等常见问题给出解决策略可帮助读者快速定位问题、规范调用流程。资源包为1个docx说明文档压缩包约101KB轻量实用已有1159人学习适合需要系统梳理K3 Cloud WebAPI集成能力的后端开发与实施人员。1. K3 Cloud WebAPI 接口说明书到项目落地先看认证和请求模板K3 Cloud金蝶 K/3 Cloud后续版本并入金蝶云星空产品体系WebAPI 是 ERP 对外集成使用频率最高的一套接口。V4.0 接口说明书对应的是一套已经收束下来的调用约定所有 URL 都是固定模板数据全部走 HTTP JSON学习成本集中在对认证、业务对象结构和错误码的掌握上。这套接口解决的是第三方系统与 ERP 之间的单据往返MES 要报工单WMS 要同步出入库电商中台要把订单推成销售订单动作不同底层的调用模板完全一样。接到这类任务后不需要自己发布 WebAPI 项目K3 Cloud 应用服务器已经注册好了 kdsvc 服务你只需要按文档约定组装参数并发起 HTTPS 请求。真正决定项目顺不顺利的是开始阶段的三个选择令牌怎么换、单据参数怎么传、错误从哪里定位。下面按这份说明书最常用的三条路径展开。2. K3 Cloud WebAPI 的认证方式从会话令牌到并发会话管理2.1 认证为什么是接口说明书里的头号问题K3 Cloud WebAPI 的所有业务接口包括保存、查看、查询、审核都不是无状态调用。客户端必须先完成登录认证拿到服务端认可的会话凭证后续请求才能被正常受理。V4.0 文档把这个过程放在前面的逻辑不难理解没有令牌后面的业务参数写得再正确也进不了业务服务。实际联调中认证踩坑的比例相当高。常见的问题有两个一是使用管理员账号登录权限太大日志里无法区分操作人二是密码直接明文传输被接口网关直接拒绝。更隐蔽的问题是很多团队把认证和业务调用放在两个不同的服务里会话没有共享导致 A 服务登录成功后B 服务请求又返回“未登录”。所以在设计集成层结构时第一步就要定好会话的归属和复用方式。我的建议是为集成单独建一个专用账号权限按要求的最小集合开放登录凭证统一放在网关或会话管理器里业务模块从同一个位置取凭证不做各自登录。2.2 用账号密码换取会话令牌的调用示例认证的典型调用是对 AuthService 的 ValidateUser 服务发 POST 请求。下面给出最基础的 curl 示例curl -X POST \ http://k3cloud.example.com/K3Cloud/Kingdee.BOS.WebApi.ServicesStub.AuthService.ValidateUser.common.kdsvc \ -H Content-Type: application/json \ -c /tmp/k3cloud_cookie.txt \ -d { acctID: a3f5e9d8c7b64f1b9a0c2d3e4f5a6b7c, username: erp_api, password: BASE64(RSA(明文密码)), lcid: 2052 }逐个字段说明。acctID 是数据中心标识。多账套部署时这一步决定你操作的是哪个账套。这个标识在管理中心里能看到也可以在数据库中查 t_SystemProfile 获取。username/password 是专门配置的集成账号。V4.0 文档要求密码经过 RSA 加密后再传输不能直接提交明文。客户端先从服务器获取公钥用公钥加密密码得到密文再 Base64 编码后放入 password 字段。这是很多联调项目第一次报“用户名或密码错误”的根源——不是密码错了是加密格式不对。lcid 是区域语言标识2052 表示简体中文会影响错误消息的语言。-c参数把服务端返回的 cookie 写到本地文件后续请求用-b参数带上保持会话。curl 适合做连通性验证真正常用的是客户端封装。下面是 Python requests 的会话管理示例import requests LOGIN_URL http://k3cloud.example.com/K3Cloud/Kingdee.BOS.WebApi.ServicesStub.AuthService.ValidateUser.common.kdsvc session requests.Session() def login(acct_id: str, username: str, password: str) - bool: resp session.post( LOGIN_URL, json{ acctID: acct_id, username: username, password: password, lcid: 2052, }, timeout30, ) payload resp.json() result payload.get(Result, {}) status result.get(ResponseStatus, {}) if status.get(IsSuccess, False): return True print(login failed:, status.get(Errors)) return False这里的关键点是 requests.Session 会自动保存服务端返回的 Cookie后续业务调用继续用同一个 session 实例即可不需要手工传递凭证。代码里把认证结果检查放在 ResponseStatus.IsSuccess 上而不是 HTTP 状态码——K3 Cloud WebAPI 返回 200 不代表业务成功这是接口说明书里最容易忽略的规则。2.3 会话失效与并发会话处理K3 Cloud 的会话有有效期默认约 20 分钟无操作会失效。设计集成层时要注意两点。第一不要在每次请求前重复登录。频繁调用 ValidateUser 不只浪费网络还可能触发服务端的登录频率限制。用 Session 对象复用是成本最低的方案等会话真正失效再重建。第二多节点部署时每个节点各持有一个会话是常见做法。若要共享就需要把登录凭证放到 Redis 这类集中缓存里并配合锁避免多个节点同时刷新同一个账号的会话导致互相踢掉线。业务量不大时不共享会话反而是更稳的选择。2.4 认证参数与安全配置对照表参数用途说明acctID数据中心标识对应账套不用填数据库名username登录账号建议单独建 API 用户不共享管理员password密码密文RSA 加密后 Base64不传明文lcid语言代码2052 简体中文错误信息语言HTTPS传输层生产环境必须开启防抓包会话有效期无活动超时默认约 20 分钟可调提示集成账号的权限应小于等于所需业务的最小权限集合。权限过大会让一次越权调用绕过整个审批体系这是生产事故的高发点。3. K3 Cloud WebAPI 的保存与查询一张销售订单的完整往返3.1 业务对象参数formId 和 Model 的对应关系K3 Cloud WebAPI 不采用 RESTful 资源路径URL 始终保持同一个服务地址变化的只是请求体里的参数。第一个参数永远是表单标识 formId它决定了本次操作作用于哪张业务单据。下面是集成中常用的一组映射业务对象formId说明销售订单SAL_SaleOrder核心销售单据采购订单PUR_PurchaseOrder采购流程主单物料档案BD_MATERIAL基础资料客户档案BD_Customer基础资料供应商档案BD_Supplier基础资料即时库存INV_Stock库存查询类业务对象映射表要在项目里维护成常量文件避免把字符串散落在代码各处。改一个表单标识时只需要动一处。3.2 调用 Save 接口保存销售订单保存接口在 DynamicFormService 下操作名为 Save。请求体由 parameters 数组决定第一个参数是 formId第二个参数是业务数据 JSON 字符串第三个参数是操作参数。下面的代码保存一张带客户和销售组织的销售订单import requests import json session requests.Session() # 调用第 2 章的 login()成功后继续 def save_sale_order(): payload { parameters: [ SAL_SaleOrder, json.dumps({ NeedUpDateFields: [FBillNo], NeedReturnFields: [FID, FBillNo], Model: { FBillNo: SO20241001-001, FDate: 2024-10-01, FCustomerId: {FNumber: C001}, FSaleOrgId: {FNumber: 100} } }), {} ] } resp session.post( http://k3cloud.example.com/K3Cloud/Kingdee.BOS.WebApi.ServicesStub.DynamicFormService.Save.common.kdsvc, jsonpayload, timeout60, ) result resp.json().get(Result, {}) status result.get(ResponseStatus, {}) if status.get(IsSuccess): print(saved:, result.get(Id), result.get(Number)) else: print(save error:, status.get(Errors))这段代码有几个参数值得展开。NeedUpDateFields 表示允许更新的字段。如果 Model 里带了单据编号就必须把 FBillNo 列入否则服务端认为该字段不可更新。NeedReturnFields 控制保存后返回的字段。这里只要 FID 和 FBillNo可以减少不少传输量。Model 是数据主体所有业务字段都放在这个对象里。FDate 用 yyyy-MM-dd 字符串基础资料字段用 {FNumber: 编码} 这种嵌套结构。第三个参数 {} 是操作参数空对象表示使用默认行为。如果希望保存的同时忽略一些警告可以在这层传入 IgnoreWarning 等配置。Result.Id 返回的是单据内码 FID后面做审核、作废、反审核时传这个 Id 最直接。如果未来对接流程引擎需要同时保存 Id 和业务单据号两条都能作为操作主键使用。3.3 用 View 接口回读单据并校验字段保存完成后建议用 View 把单据读出来校验而不是直接信任返回。View 操作也在 DynamicFormService 下{ parameters: [ SAL_SaleOrder, {\FID\:\${FID}\} ] }第二个参数传主键定位单据这里用 FID 定位。如果调用方手里只有业务编号也可以用 Key 或 Number 字段定位。响应返回完整表单对象包括表头、明细、基础资料引用名称拿到后可以和源系统的数据做比对。这里${FID}是占位符实际请求时替换成第 3.2 节保存返回的 Id 值。3.4 用 ExecuteBillQuery 做查询过滤与分页查询不需要拉整张表单适合用 ExecuteBillQuery。这个接口接收六个参数依次是 formId、字段列表、过滤条件、排序规则、页码、每页行数。我经常把它当成稳定的报表取数通道{ parameters: [ SAL_SaleOrder, FID,FBillNo,FDate,FCustomerId.FName,FSaleOrgId.FName, FBillNoSO20241001-001, , 0, 100 ] }字段列表里用点号连接引用属性FCustomerId.FName 代表客户基础资料的名称字段这种写法在 V4.0 文档里是标准写法。过滤条件与 SQL WHERE 语法相近支持、、、LIKE、IN等。排序规则为空字符串表示不排序也可以写 FBillNo DESC。页码从 0 开始每页行数建议不超过 1000服务端有行数限制。返回结果不是键值对象而是一个二维数组{ Result: [ [FID, FBillNo, FDate, FCustomerId.FName, FSaleOrgId.FName], [128, SO20241001-001, 2024-10-01 00:00:00, 测试客户, 华南销售组织] ] }第一行是字段名后面每行是一条数据。解析时不要硬编码字段索引建议先在联调环境拉一次真实数据按返回顺序建立字段到索引的映射表后面解析就会稳定很多。另一个约定是日期时间字段返回格式带空格分隔容易和源系统的字符串比较逻辑冲突解析时统一转成 datetime 对象再比较可以避免绕弯。4. K3 Cloud WebAPI 的单据操作与错误排错4.1 用 ExecuteBillOperation 执行提交、审核、反审核和作废保存后的单据如果直接落库通常还要走提交流程。提交、审核、反审核、作废这类状态流转统一走 ExecuteBillOperation 接口。它的参数是四项formId、操作类型、主键定位 JSON、操作参数。以下是审核一张销售订单的 Python 示例def execute_operation(form_id: str, operation: str, bill_no: str): payload { parameters: [ form_id, operation, json.dumps({Numbers: [bill_no]}), {} ] } resp session.post( http://k3cloud.example.com/K3Cloud/Kingdee.BOS.WebApi.ServicesStub.DynamicFormService.ExecuteBillOperation.common.kdsvc, jsonpayload, timeout60, ) result resp.json().get(Result, {}) status result.get(ResponseStatus, {}) if status.get(IsSuccess): print(f{operation} success: {bill_no}) else: print(f{operation} failed:, status.get(Errors))operation 参数是服务端预定义的操作类型常见值如下操作类型含义备注Submit提交从暂存到已提交Audit审核从已提交到已审核UnAudit反审核从已审核到已提交Cancel作废终止单据生命周期主键定位用 Numbers 传业务单据号列表也可以用 Ids 传内码列表两者在文档中都支持。我习惯用 Numbers因为源系统同步过来的数据里只有业务单号不额外维护内码映射。一个容易踩的坑是 Numbers 要传数组不是单个字符串。即使只处理一张单也写成[bill_no]的形式传 string 时部分版本会直接报参数类型错误。4.2 从 ResponseStatus 解析成功和失败K3 Cloud WebAPI 统一返回结构成功和失败都通过 ResponseStatus 表达。HTTP 状态码 200 不代表业务成功必须逐层判断数据结构。{ Result: { ResponseStatus: { IsSuccess: true, Errors: null, SuccessEntitys: [ { Id: 128, Number: SO20241001-001, DIndex: 0 } ] }, Id: 128, Number: SO20241001-001 } }IsSuccess 为 false 时Errors 数组里会给出错误详情。每个错误对象包含三个常用键FieldName报错字段标识例如 FBillNoMessage错误描述面向人的可读文案DIndex出错明细行的索引-1 表示表头字段错误0 及以上对应明细行号程序化处理时用三个键的组合就能快速定位不需要解析整段错误堆栈。4.3 高频错误及解决联调阶段最常遇到的错误现象和处理思路整理在下表。这些问题里的大部分不是代码逻辑问题而是参数组装与状态流转顺序问题。错误场景返回信息特征解决办法会话过期“请登录”或“登录已失效”抛弃旧会话重新走登录流程单据编号重复“编号重复”保存前按 FBillNo 查询预检基础资料不存在“客户不存在”或“编码无效”核对 FNumber 与主数据系统注意大小写和前后空格必录项为空错误里带 FieldName 和“不能为空”对照单据设计器字段属性逐项补齐状态流错误“尚未提交不能审核”先 Submit 再 Audit顺序不能跳参数类型错误“参数类型: String”检查是否将数组传成了字符串这类错误有一个共同的处理顺序先看 ResponseStatus.IsSuccess再看 Errors[0].FieldName最后核对参数原始值。不要一看到“失败”就查数据库先确认入参是否符合文档的类型和必录规则。提示登录接口如果返回“用户名或密码错误”先检查密码加密环节换了服务器或重新部署后公钥是否同步更新。这个原因导致的失败往往和账号本身无关排错方向不要一开始就锚定在密码上。5. K3 Cloud WebAPI 批量操作与集成工程化的三个落地做法5.1 用 BatchSave 一次提交多张单据逐张循环调 Save 面对几百上千条记录时耗时线性增长。文档专门提供了 BatchSave 接口第二个参数从单个业务对象变成数组def batch_save(orders: list[dict]): model_list [] for order in orders: model_list.append({ NeedUpDateFields: [FBillNo], NeedReturnFields: [FID, FBillNo], Model: { FBillNo: order[bill_no], FDate: order[date], FCustomerId: {FNumber: order[customer_code]} } }) payload { parameters: [ SAL_SaleOrder, json.dumps(model_list), {} ] } resp session.post( http://k3cloud.example.com/K3Cloud/Kingdee.BOS.WebApi.ServicesStub.DynamicFormService.BatchSave.common.kdsvc, jsonpayload, timeout120, ) result resp.json().get(Result, {}) status result.get(ResponseStatus, {}) if status.get(IsSuccess): for entity in status.get(SuccessEntitys, []): print(entity.get(Number), entity.get(Id)) else: print(batch error:, status.get(Errors))返回的 SuccessEntitys 顺序与传入顺序一致可以按索引把结果映射回原数据。每批条数我通常控制在 100 到 200 之间超过 500 条事务时间会明显变长死锁概率也在上升。5.2 按幂等性设计重试策略集成层重试要考虑操作是否幂等盲目重试可能把单子重复保存或是把“审核中”的单子再审核一次。操作是否幂等重试建议View / ExecuteBillQuery幂等可重试 3 次指数退避Submit / Audit基本幂等重试前先查状态避免状态冲突Save / BatchSave非幂等用 FBillNo 唯一键约束重复保存报重号UnAudit / Cancel幂等重试前先确认目标状态超时设置也要分开查询 30 秒Save 60 秒BatchSave 120 秒。混合设置会导致慢查询拖垮整个调用链的体验。5.3 用 request_id 串起调用链路接口层面最后一个建议是给每一次外部调用统一记录台账。开发日志里单看一条错误信息很难反推入参配合 request_id 才能把请求、响应、业务单号串起来。字段示例检索价值request_id8f3a1d2c-9b02聚合一次全链路日志form_idSAL_SaleOrder定位业务对象operationBatchSave定位操作类型bill_noSO20241001-001按单号反查cost_ms843观察性能波动statussuccess / fail快速过滤error_msg单据编号重复联调阶段最高频检索字段对接人员上门排查时往往先按 request_id 过滤日志再找对应时段的请求体。日志记录不需要保留整段响应记录 formId、操作、返回状态和错误摘要就够了。本文还有配套的精品资源点击获取
