变更记录

产品版本	更新内容	更新日期
R202211.001	初始版本	2022年11月
R202507.002	新增工作流参数forcedAudit，支持自动审核时，不进入工作流	2024年07月
R202503.001	保存操作API增加操作参数multiOps，支持组合保存、提交、审核操作	2025年03月
R202504.001	保存操作API增加自定义操作参数judgeKeyRepeatCheck，支持批量保存数据时，在内存中校验候选键	2025年04月

1 接口介绍

保存操作API是通过在系统中维护接口基本信息、配置请求参数来定义接口具体的功能。

2 注意事项

保存操作接口根据入参的不同，可同时执行保存、更新、批量保存和批量更新四种操作。
候选键作为接口执行更新逻辑的唯一主键，需要谨慎选择，一般选id或number/billno为候选键，也可选择不同字段组合作为候选键。
若接口只用于更新数据，此时可以将候选键字段设为必填。

3 接口示例

3.1 维护API基本信息

录入API编码、API名称、业务对象、操作方式、详细描述等信息，请求方式为“POST”，系统自动生成API请求地址。

3.2 维护请求头参数

系统已预置Content-Type、accesstoken等参数，用户无需维护。

3.3 维护请求体参数

点击“添加属性”按钮快速添加请求参数，业务对象每个层级必须设有候选键，若在系统中查到相同候选键的数据，会执行更新操作，若未传入则执行新增操作。用户还可以点击“参数示例”按钮，查看JSON、XML、SOAP1.1、SOAP1.2 四种格式的数据示例。

3.4 维护操作参数（可选）

操作参数分为系统保存参数和自定义参数，都支持在保存时对数据进行特殊处理。

类型	参数	说明
系统保存参数	importType	保存类型，new - 新增，override - 覆盖，overridenew - 覆盖新增，接口默认执行覆盖新增逻辑
	firePropChanged	更新时触发值更新事件，true - 触发，false - 不触发，接口默认不触发
	firePropChangedOnAdd	新增时触发值更新事件，true - 触发，false - 不触发，接口默认不触发，开启后性能影响极大，单次请求分录上限为200条注意：经压测，在新增数据时200条分录开与不开值更新，存在10倍的性能损耗差异，建议在超出200条分录时，采用以下解决方案：解决方案一：新增不触发值更新 1. API不要配置firePropChangedOnAdd； 2. 需值更新的属性，在API上配置为请求参数； 3. 由调用方计算并保障传入的数据准确性，这是合理的集成方案且保障了性能；解决方案二：拆分调用 1. 将一次数据新增拆分为新增和更新，新增保证200条分录以内； 2. 新增成功后再更新追加分录，通过更新触发值更新； 3. 更新API的操作参数需增加配置【is_checkentryid】为【false】，保障更新数据时可新增分录数据。
	forcedSubmit	强制提交（注意，若单据的save插件中有复杂计算逻辑，配置后无法触发），submit - 提交，空 - 不提交，接口默认不自动提交
	OverrideEntry	更新时完整覆盖分录，会将原表单分录数据清除后追加分录， true - 覆盖，false - 不覆盖，接口默认不覆盖；
	mutex_ignoremodify	保存时忽略网络互斥，true - 忽略，false - 不忽略，接口默认不忽略
	is_importinit	是否触发引入方法，true - 触发，false - 不触发，接口默认触发
	multiOps	组合操作参数，支持将保存、提交和审核操作组合执行。save,submit - 保存后提交；save,submit,audit - 保存后提交并审核，接口默认只执行保存。注意：批量保存时，若提交或审核失败，会出现不同状态的数据，需用户手工补偿
自定义参数	rmStatusControl	是否移除单据状态控制，默认为false，当值为true时，可跳过已审核单据和基础资料不允许修改的校验，直接更新已审核的单据或基础资料
	is_checkentryid	默认为true，默认为true，若设为false，则更新数据时，不强制校验分录id在系统中是否存在，适用于接口更新单据时，同时新增单据分录（带id）的场景
	forcedAudit	强制提交并审核，默认为false，当值为 true 时，新增数据时会自动提交并审核单据（注意，若单据的save插件中有复杂计算逻辑，配置后无法触发）
	WF	该参数配合forcedAudit参数使用，可控制OpenAPI提交审核的单据是否进入工作流，默认为true，将该值设为false后，即可跳过工作流，直接审核成功。
	updateEntrySummaryEnable	更新时汇总分录金额到单据头，默认为false，当值为true时，当API不传入单据头汇总金额字段时，会将分录金额自动汇总至单据头
	fireAfterCreateNewData	是否触发表单插件中的fireAfterCreateNewData方法，默认为true，当值为false时，不触发该方法。
	fireFieldControlRule	保存时是否触发实体中的字段权限方案（字段不可读写），默认为true，当值为false时，不触发该权限校验
	judgeKeyRepeatCheck	保存时是否在内存中检查候选键，默认为false，将请求候选键和数据库已存在的数据，进行唯一性校验；当值为true时，在内存中检查候选键是否唯一

3.5 定义返回参数

保存操作服务的返回参数目前不允许用户自定义，统一按平台规范返回。

API Response契约统一为:

{
    “data”: {//结果数据
        "result": [],//返回结果详细信息
　         “failcount”: “”,//操作失败数量
　         “successcount”: “”//操作成功数量
        }
       “errorCode”: “”,//错误码
       “message”: null,//失败时的提示信息
       “status”: true/false//是否成功
   }

3.6 API测试

点击“API测试”按钮，开始调试API。当传入候选键字段时，执行更新操作，不传入候选键字段，则执行新增操作。

4 更多资讯

关于OpenAPI的更多资讯，请随时关注OpenAPI（开放平台）新特性汇总。