金蝶云星空接口对接常见问题汇总

1. 简述WebAPI的工作原理

WebAPI的工作原理通俗来说，就是模拟录单的过程，根据传入的Json数据包构造的每个字段值，按顺序逐一模拟录单填充（录入）对应字段的值，触发此字段的相关值更新事件、实体服务和插件逻辑。构造完成整个单据的数据包之后，调用Save保存接口（Submit提交、Audit接口），并对应触发保存（提交、审核）的操作校验、操作逻辑、操作单据插件逻辑等整个过程。

细节参考帖子链接：
1.1.K/3 Cloud系统集成【汇总贴】
https://vip.kingdee.com/article/9185

1.2.K3 Cloud WebAPI接口说明书5.0

https://vip.kingdee.com/article/188291213903611648

1.3金蝶云星空日志管理-WebAPI日志

https://vip.kingdee.com/article/8744

1.4.【精华合辑】金蝶云BOS资料合辑

https://vip.kingdee.com/article/9186

2. WebAPI的Demo示例和功能自测Json。

登录Cloud系统–菜单：基础管理-动态服务定义-WebAPI 或者直接搜索菜单关键字WebAPI

3. WebAPI的几个特殊参数和可能遇到的常见问题及解决。

3.1 特殊参数如上图上面做了简单解释，下面常见问题会涉及到一些。

3.2 更多对接问题请查看：销售管理常见WEBAPI问题及其他常见问题汇总指导

常见问题1：明明Json里面给了某个字段值，保存结果却并没有此字段值

原因分析：

1.1.字段值不合法，赋值不成功，测试：到单据录单界面尝试录入Json的值，看是否可以录入成功。
2.1.字段合法，赋值成功后被其他字段逻辑重新赋值覆盖清空掉了，此问题是Json构造数据包字段的顺序不正确，可以调整Json数据包里面的字段前后顺序：常见如： 单价-》数量-数量触发取价服务，覆盖了前面单价。 调整Json构造的顺序：单价字段调整到数量字段后面去。
3.1单据插件其他服务、插件逻辑影响了字段值。可以使用插件调试DataChange事件和保存事件分析数据包字段值在不同时机是否有值

常见问题2：销售套件业务，构造Json分录里面有多行套件父项物料，实际却只有第一行成功

原因分析：上图2.7参数 IsEntryBatchFill 需设置为False，因为套件父项物料需依赖前置字段 产品类型，不适用批量填充。

常见问题3：系统里面仓库设置了允许负库存，系统界面操作交互没问题，WebAPI审核出库单却不成功，提示负库存

原因分析：由于WebAPI是服务端处理业务，无法支持交互弹出界面，因此需要设置 上图2.10参数：InterationFlags:“STK_InvCheckResult”

其他相关可能的交互校验忽略标识，一般都是交互校验的弹出交互界面的唯一标识即可（可在BOS查询）

如： 
    预计可发量检查的交互标识：Sal_ExpectQtyCheckDetail  
    最低限价检查的交互标识：SAL_DOWNPRICECHECK
    允许负库存交互标识：STK_InvCheckResult
    价格来源检查的交互标识：SAL_CHECKPRICESOURCEFB

常见问题4：WebAPI保存单据希望自动建立上下游关联关系

解决参考：参考：WebAPI保存接口实现上下游关联https://vip.kingdee.com/article/171055

常见问题5：未购买CRM销售过程管理模块WebAPI保存【销售合同】，未购买销售管理模块 WebAPI保存【销售出库单】

提示未购买XXX模块的问题

原因分析：系统某些单据（如销售合同【属于CRM-销售过程管理，同时属于供应链-销售管理】、销售出库单【属于供应链-销售管理，同时属于供应链-库存管理】）是只要购买两个里面其中任一模块即可使用。由于WebAPI默认会取单据本身所属的功能模块子系统校验加密，如果本身所属这个子系统未购买，则会提示。

解决方案：根据参数说明里面的2.5参数 SubSystemId 主动给已购买的子系统即可。如：SubSystemId：“23”

常用子系统值：销售管理：23 库存管理：21 采购管理：20

常见问题6：WebAPI保存单据某个物料不合法，生成的单据缺少此物料分录行也能保存成功

解决参考：保存单据json传入的分录行，某个物料不合法（未分配、反审核、作废、以及单据对物料的其他条件限制）导致此物料行不能正确对接成功，但是实际单据却保存成功（缺少丢失此行），没有任何提示。

不能校验问题：WebApi保存接口参数：2.5.IsVerifyBaseDataField：是否验证所有的基础资料有效性，布尔类，默认false（非必录）。因此此参数未指定，就导致不会校验基础资料合法性。开启参数后会校验单据所有的基础资料字段值的合法性（会对性能有一定影响，根据业务需要酌情启用）

自动删除【不合法物料】分录行：由于我们目前大部分单据的BOS设置分录的属性【关键字段】：指定的都是物料字段。因此物料没有录入，系统保存时候就认为此行是无效行，自动删除了。【关键字段】还有另外一个作用，就是录入（关键字段：物料）值后，会自动新增一行空行，省去了手工点击新增行菜单，是对易用性的一个优化。可酌情考虑是否设置关键字段。

常见问题7：关于WebAPI修改保存单据的Json构造：

修改保存单据传入的json与新增保存单据不同，无需构造复杂的单据字段：如

只需要构造单据FID和FEntryId和需要修改的字段即可：

{   

 "NeedUpDateFields": [],  
  "NeedReturnFields": [],   
//注意IsDeleteEntry参数，如为True，则原分录行的FEntryId未在分录json出现的行，将会被删除 （如无需删除分录行，可改为fasle）   
 "IsDeleteEntry": "True",
 "IsVerifyBaseDataField": "false",   
 "IsEntryBatchFill": "True",   
 "Model": {       
 "FID": "188888",       
 "FSaleOrderEntry": [ {  "FEntryId":"255555", "FQty":"3"   }   ]    } 
}

4. WebAPI的对接对于性能的影响点和优化方案

优化点1：精简Json构造的字段数量，保留必须的字段，去掉非必须的，比如：单位、计价单位、税率等等都是物料自动携带的，无需构造。

优化点2：销售订单和销售出库单大概有10几个字段值更新事件上都挂有取价服务、取折扣服务，取价服务、取折扣服务相对来说是比较耗时的，特别是优先级取价时。如果Json字段里面已经填了价格，就无需让取价服务触发避免浪费性能。

5. 超高性能大数据量对接时的方案和相关建议

大数据量对接建议方案：

1. 通常将外围第三方需对接的数据对接到ERP的中间表中，（中间表仅包含外围的简单字段+一个状态字段）
2. 数据要分批通过执行计划对接，通过ERP的执行计划插件，少量多次，分批轮询执行，每批次定量从临时表抓取待同步的数据（比如一次200条，控制在5分钟内本批次的全部执行完毕的最优条数，避免超时）。
3. 每批次尽量使用WebAPI批量接口操作，同时每个执行计划尽量只专注于做一件事情（比如：A执行计划仅处理保存接口批量调用处理，B执行计划仅处理（提交、审核）批量接口调用）。
4. 避免使用参数【 IsAutoSubmitAndAudit：True】平台最新说明里面已经屏蔽此参数了，在大并发时此参数可能会导致某些服务未正常执行等（核心原因是一次对接事务多个操作战线拉的太长）
5. 如果单据量比较大，接口调用比较频繁，尽量单独部署独立的应用服务器专门给API进行访问，同时可以设定多个不同的对接用户来达到并发的目的，每个用户尽量做不同的业务，防止出现业务瓶颈。

大数据量对接的并行调用（适度应用，按推荐模式应用）

1. 多线程并行的调用使用，需根据业务数据量评估，酌情使用，多线程并行调用对系统服务器资源（CPU、内存）耗费较高，不可并发太多调用，以免影响系统的正常使用。一般根据数据情况和服务器资源情况建议并行调用2-10个以内。（不建议使用多线程的并发请求来进行并行处理，优先使用下面5的推荐内部并行模式调用）

2. 如果使用执行计划调用WebAPI，尽量使用WebAPI批量接口BatchSave调用，但一次批量不宜过多，建议20左右，尽量遵循少量多次的调用原则：如：一次执行计划的调用执行100单，分5批次调用，每次批量保存20单。尽量避免执行计划执行超时出错，一般系统默认5分钟超时。一次执行计划的执行可控制5分钟时间内。

3. 多线程并行执行时，对并行执行过程中数据要特别注意，禁止共用线程外的共用变量，以免数据相互污染干扰。

4. 登录连接最好放在并行外部，一次登录即可。

5. 推荐使用的并行调用模式：（WebAPI内部底层自动并行处理）

   推荐使用BatchSave接口，建议开启BatchCount并行处理参数，参数值建议不超过10。

作者：程晓峰
来源：金蝶云社区
原文链接：https://vip.kingdee.com/article/11179?productLineId=1
著作权归作者所有。商业转载请联系作者获得授权，非商业转载请注明出处。