WebAPI接口之【销售出库单保存/修改接口】使用指南和实例

栏目：云星空知识作者：金蝶来源：金蝶云社区发布：2024-09-23浏览：1

【应用场景】

第三方对接系统业务单据的常用单据--销售出库单，常用的新增、修改销售出库单的WebAPI接口

【销售出库单保存接口说明及示例】

一、接口说明：

1.接口名称：Save [批量保存：BatchSave]

接口组件：Kingdee.BOS.WebApi.ServicesStub.dll

接口类名：Kingdee.BOS.WebApi.ServicesStub.DynamicFormService.cs

2.接口调用全称：

SDK调用：Kingdee.BOS.WebApi.ServicesStub.DynamicFormService.Save

Kingdee.BOS.WebApi.ServicesStub.DynamicFormService.BatchSave

HTTP调用：

http://服务器地址/k3cloud/Kingdee.BOS.WebApi.ServicesStub.DynamicFormService.Save.common.kdsvc

http://服务器地址/k3cloud/Kingdee.BOS.WebApi.ServicesStub.DynamicFormService.BatchSave.common.kdsvc

【参数说明】

参数列表

参数含义

备注

formid

表单唯一标识，“SAL_OUTSTOCK”

必须

data

数据包:

\"Creator\":\"\",
\"NeedUpDateFields\":[\"\"],

\"IsDeleteEntry\":\"false\",

\"NeedReturnFields\":\" \",

\"IsVerifyBaseDataField\":\"false\",

\"IsEntryBatchFill\":\"false\",

\"InterationFlags\":\"\",

\"IgnoreInterationFlag\":\"\",

\"IsAutoSubmitAndAudit\":\"false\",
\"Model\":{下面重点说明}

Creator：非必须
NeedUpDateFields：非必须，如果是更新单据而不是新增一个单据，可以设置这个数据集合，内容为字段标识，使用逗号分隔，如果需要更新表体数据，则需要填写表体的标识。一般情况下，如果Model中只填写了需要更新的字段信息，没有其他冗余的字段，那么这个参数不需要设置，否则其他冗余字段会覆盖ERP中的源单数据。

IsDeleteEntry:非必须，在修改单据时是否需要删除已经存在的分录。

NeedReturnFields:非必须，需要返回的所有字段。

IsVerifyBaseDataField:非必须，是否需要验证基础资料。

IsEntryBatchFill:非必须，是否需要批量填充分录。

Model：必须，Model数据格式说明：所有字段和实体都是用元素的标识来识别。

\"InterationFlags\":交互标志集合，字符串类型，分号分隔，格式：

IgnoreInterationFlag：是否允许忽略交互，布尔类型，默认true（非必录）

"flag1;flag2;..."（非必录）例如（允许负库存标识：STK_InvCheckResult）

\"IsAutoSubmitAndAudit\":是否自动提交与审核，布尔类型，默认false（非必录）注（启用此参数，保存，提交和审核是在一个事务中）。
另外要注意的是更新单据时，表体信息必须填写明细表体的主键，如果不填写，将会删除源单的表体，而没有主键的数据会视为新增，有明细主键的视为更新。

*****【重点】**************************【Model字段构造】*****************************【重点】*****

原则：

1.构造json字段尽量精简，按需构造关键字段即可，WebAPI构造单据原理类似模拟录单，有默认值的字段和字段会自动联动携带相关值（包括字段值更新、插件等逻辑联动携带出来，如：客户字段自动携带默认销售员、结算币别等）的字段可无须构造。

2.修改保存单据，只需要构造单据主键FID或分录主键FEntryId+需要修改的字段即可。

3.json字段顺序位置非常关键，构造单据时是按照json字段顺序逐实体逐个字段触发值更新事件和服务的。

4.json数据包字段多少和顺序对性能和数据正确性有很大影响，尽量按需构造，避免无用的字段

5.json数据包同时构造Link子单据体数据，自动与上游单据建立关联关系进来构造完整（参考示例3）

示例1：【极简模式】（Webapi在线测试 json测试）：

{
   "Model": {
       "FBillTypeID": {"FNUMBER": "XSCKD01_SYS"},
       "FStockOrgId": {"FNumber": "100"},
       "FCustomerID": {"FNumber": "A"},
       "FEntity":
              [{
           "FMaterialID": {"FNumber": "1.01.001.0001"},
           "FRealQty": 1,
           "FStockID": {"FNumber": "CK001"   }
       }]
   }
}

示例1：Webapi菜单在线测试验证：（极简字段模式）

示例1：Post:man测试验证：（极简字段模式）

上传图片

示例2：在极简字段模式下追加一些业务需要的字段+多行分录：（Postman json示例）

示例2：Postman测试验证（追加业务可能所需字段+多行分录）

上传图片

示例3：重点构造Link子单据体数据，自动与上游建立关联关系（Postman json示例）

{
    "formId":"SAL_OUTSTOCK",
    "data":{
        "Model": {
            "FBillTypeID": {"FNUMBER": "XSCKD01_SYS"},
            "FStockOrgId": {"FNumber": "100"},
            "FSaleOrgId": {"FNumber": "100"},
            "FCustomerID": {"FNumber": "A"},
            "SubHeadEntity": {
                        "FSettleCurrID": {"FNumber": "PRE001"},
                        "FSettleOrgID": {"FNumber": "100"}
             },
            "FEntity":[{
                "FMaterialID": {"FNumber": "1.01.001.0001"},
                "FRealQty": 1,
                "FStockID": {"FNumber": "CK001"   },
                "FSRCTYPE": "SAL_SaleOrder",
                "FSRCBILLNO": "XSDD000772",
                "FSoorDerno":"XSDD000772",
                "FSOEntryId":"101634",
               "FEntity_Link ": [{
                        "FEntity_Link_FRULEID": "SaleOrder-OutStock",
                        "FEntity_Link_FSTABLENAME ": "T_SAL_ORDERENTRY",
                        "FEntity_Link_FSBILLID ": "101034",
                        "FEntity_Link_FSID": "101634",
                        "FEntity_Link_FBaseUnitQty" :"10",
                        "FEntity_Link_FBaseUnitQtyOld" :"10",
                        "FEntity_Link_FSalBaseQty" : "10",
                        "FEntity_Link_FSalBaseQtyOld" : "10",
                        "FEntity_Link_FPriceBaseQty" : "10",
                        "FEntity_Link_FPriceBaseQtyOld" : "10"
                    }]
               }]
    }
}

示例3：Postman测试验证（重点构造Link子单据体数据，自动与上游建立关联关系）

上传图片

【修改保存】

*****【重点】**************************【Model字段构造】*****************************【重点】*****

原则：

1.修改保存时，除了构造主键FID、分录主键FEntryId 以及需要修改的字段外，不要构造其他多余字段

2.修改保存时，注意IsDeleteEntry参数非常重要，且默认为true，需小心使用。如为true，则原分录行的FEntryId未在分录json出现的行，将会被删除（如无需删除分录行，需将参数值改为fasle 或者 json里面传入对应行的FEntryId值）

修改保存示例：

{
    "formId":"SAL_OUTSTOCK",
    "data":{
         "IsDeleteEntry":"false",
         "Model": {
                 "FId": "100750",
                 "FEntity": [
                                 {
                                      "FEntryId":"101172",
                                        "FQty":"5"
                                  }
                            ]
                       }
         }
}