浅谈通过WebAPI实现金蝶云单据对接的那些事[持续更新完善]

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

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

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

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

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

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

2. 自动删除【不合法物料】分录行：由于我们目前大部分单据的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"   }   ]    } 

}

参考帖子：https://vip.kingdee.com/article/509455783696820480

常见问题8：WebAPI在线验证测试查询报表接口查询返回单价、金额字段为null：

原因分析：一般可能的原因就是跟登录用户的权限有关，通常是使用Administrator用户（因为默认只有Administrator用户有WebAPI菜单的使用权限），但是Administrator用户虽然能查询报表，但是默认却是没有报表的单价、金额查看权限的。

参考帖子：https://vip.kingdee.com/article/515608255897537792

常见问题9：webapi调用保存接口返回提示：“插件取消了保存操作，可能因为数据不合法”的处理方案      ：

原因分析：客户端表单插件的BeforeSave事件里面某个业务校验不合法，插件使用了e.Cancel=true，取消了保存操作导致的。一般界面操作会有提示信息，WebAPI接口无法提示信息，BOS接口只能返回结果“插件取消了保存操作，可能因为数据不合法”

参考帖子：https://vip.kingdee.com/article/512308917888492800

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

WebAPI对接系统单据过程中，根据其原理，需要逐行逐字段触发字段值更新、实体服务规则，触发单据的保存、提交、审核 操作上所挂的服务，以及单据的校验逻辑和插件操作处理逻辑。为了保证数据的正确性，注定这个过程是一个耗时的过程。但是，我们却可以从不同的点入手结合业务实际应用对一些逻辑和操作服务进行优化，以下以销售订单和出库单为例进行优化说明。同时可以开启WebAPI日志管理，详细判断WebAPI的时间花费在哪里

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

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

1.销售订单、销售出库完全来自于第三方对接，不存在界面进行手工录单的情况下，直接更改调整配置，取消取价服务、取折扣
2.系统可能存在WebAPI对接和界面手工录单两种方式，最近新补丁可调整BOS服务配置分场景禁用服务。

销售出库单审核操作的相关服务优化说明：（反审核类似）

销售出库单审核自动生成应收单 的相关参数配置调整

（系统默认审核自动生成应收 影响对接性能，作为WebAPI对接性能要求比较高时，可取消参数，分两步进行，先对接出库单单据过来，再用其他另外的对接服务或执行计划单独处理下推应收单以及审核应收单过程）

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。

   BatchCount：此参数主要用于优化性能，当传入的单据数据量较大时，可以设定此参数的并行分批执行次数。例如传入100张单据数据，此参数设定为10，则表示在星空系统中，以10个单据为一批，分10批，同时并行保存，提升效率。
   

6：WebAPI 自定义接口 通过SQL脚本查询数据

具体参考上面的连接1.2：K3Cloud WebAPI接口说明书 里面的5.1.10章节

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

关于文档里面示例用的是QueryService进行了查询币别过程，做过开发的同学都知道，其实完全可以把这个QueryService替换为自己写的查询脚本（Select * from t_BD_Currency），这里定义的接口试下方法，其实已经可以完全看做是客户端插件（ 此处是客户端调用组件）的方法一样：

1. 可以用脚本执行任何查询、更新等动作，QueryServiceHelper----》DBServiceHelper.Execute（SQL）

2. 或者是自己定义自己业务ServiceHelper通过接口Contracts调用的APP.Core服务端现有方法。