K3cloud Web API对接---单据保存接口(有源单)

https://club.kingdee.com/forum.php?mod=viewthread&tid=1485115

 

 

今天接着来分享一下Web API中的保存接口的另外一个接口：单据保存。 单据保存可分为无源单的单据保存，和有源单的单据保存。 本文主要分享关于有源单的单据保存接口操作。（无源单的单据保存接口操作链接：https://club.kingdee.com/forum.php?mod=viewthread&tid=1485063&page=1） 保存接口的分享内容有点多，你一定要细心看下去，对其他的API操作也有一定的帮助。 好了，闲话不多说，进入正题： 下面我以保存采购入库单为例子进行讲解分析（采购入库单的源单为采购订单）： 首先，同样地，我们需要准备好对接的三大利器： 1：URL(链接)： 保存接口的URL是：https://自己企业的登录域名 +/k3Cloud/Kingee.Bos.WebApi.ServicesStub.DynamicFormservice.Save.Common.KDSVC     (固定不变） 举个例子，如果贵公司的登录域名是：https://thisisatest.ik3cloud.com， 那么，保存接口的URL就应应该是：https://thisisatest.ik3cloud.com ... e.Save.Common.KDSVC    顺便说明一下，我上面举例是用https协议的，而有的企业是http协议的，如果是的话，就要使用http协议。尽量复制域名，这样才不会出错，也别多复制一个k3cloud哈。 2：  Data(即请求参数)： 打开金蝶的Web API功能，可以看到保存接口的请求参数有，如图所示 第一次打开，一看，我cha ！！！ 心里一万个草泥马扑心而来，是不是。咋一个保存接口要这么多死鬼请求参数？ 不仅仅如此哦。我跟你说一下我当时的分析思路哦： 外部有两个参数，1，formid，2，data。然后data里面又包含了12个参数，接着到第12个参数Model里面，又包含了一大堆参数。 分析到这里，我就彻底懵逼，对吧。 别担心。我是分享心得的，肯定让你舒舒服服地把它给做了。 首先，你要记住一个规则，金蝶云的Web API有个特点，非必填的参数是可以不用传的。 看到这里，有的朋友就问，非必填的话，我可以传空值吗？答案是：有时候可以，但有的时候就不可以，因为空值有的时候会报错(未将对象引用设置到对象的实例)， 这个就是典型的：没有实例化。传了key，然后服务器找不到value。如果不传key，那么就不会报这个错。所以非必填的参数能不传就不传。千万要记住这一点。记住这一点后，你的成功率就达到90%以上了！！！ 然后估计又有人问了，那我哪知道哪些是必传，哪些是非必传呢？ 看下面截图： 看到没有？？ formid是必传的，data也是必传的，然后data里面的Model也是必传的。 你心里肯定在想，这不是废话吗？？？ 别急，关键的来了。让人最激动的地方来了：看截图 开心不，激动不，Happy不，data里面的一大串参数不需要传！不需要传！不需要传！重要的事情所三遍！！！ 所以，先总结一下，请求参数就应该是post_data={   "formid" :  "STK_InStock"   ,  "data"  :  {"model":{}}， （这里需说明一下，model里面数据就是单据的主数据，包括单据头数据，单据体数据） 接着你肯定会想到，那Model里面也有很多参数，我是不是同样的道理，只要传我想要的就行了？？ 非常正确！！！Web API就是如此简单。 所以，你就会想：我手工新增采购入库的时候，如果没有特殊要求，我点击新增， 只需要把：供应商，日期，物料，数量，含税单价，仓库，源单相关信息， 这几个字段的内容写上去，就可以保存提交审核了。那么，API单据保存也是如此吗？ 我很确定地告诉你：是的！API单据保存也就是这样！！！    Model里面可以只包含你想要的参数就行。 因此按照上面的需求，请求参数就应该是（暂未构建源单关联关系）: post_data={"FormId":"STK_InStock" , "Data":{"Model":{ "FSupplierId": {"FNumber": "01.S02.008"},                                                         "FDate":"2019-04-21",                                                         "FInStockEntry":[{"FMaterialId":{"FNumber": "A.000362"},"FRealQty":1,"FTaxPrice": 100,"FStockId": {"FNumber": "000"}}]}}} 顺便说一下，如果有一些字段不是系统出厂就有的，而是你在BOS上二开自定义增加的，那你就把这个字段名给加到Model里面，然后给它你想要传的value值， 例如，你在采购入库单上加了一个字段叫FPython文本框， 那你的请求参数就应该是： post_data={"FormId":"STK_InStock" , "Data":{"Model":{ "FSupplierId": {"FNumber": "01.S02.008"},"FPython"："Python写入",                                                         "FDate":"2019-04-21",                                                         "FInStockEntry":[{"FMaterialId":{"FNumber": "A.000362"},"FRealQty":1,"FTaxPrice": 100,"FStockId": {"FNumber": "000"}}]}}} 记住，一定是加到Model里面的。Model才是真正的要上传数据。 字段名可以在BOS上面找到，也可以在选择保存接口后往下面拉，如图。它也是有数据字典的。 这样，基本的参数构建已经完成，那么我们接下来就要构建源单关联关系了。 构建源单关联关系的原理是：需增加4个参数在明细单据体里面（FInStockEntry）： 1，FInStockEntry_Link_FRuleId（单据转换规则唯一识别码）； 2，FInStockEntry_Link_FSBillId（上游单据业务对象的ID）； 3，FInStockEntry_Link_FSTableName（上游单据体的明细表名）； 4，FInStockEntry_Link_FSId（上游单据的明细分录内码，这里说明一下：金蝶所说的内码，其实就是它数据库里面，表的主键，唯一不重复） 如图： 那么，这4个参数的值应该如何取得呢。请继续往下看，我会一一为你解答。 1：FInStockEntry_Link_FRuleId，单据转换规则唯一识别码，必须要传，可以随便填个值就行，只要不传空值就好； 2：FInStockEntry_Link_FSBillId，上游单据业务对象的ID，跟上面的参数一样，必须要传，也是可以随便填个值就行，只要不传空值就好； 3，FInStockEntry_Link_FSTableName，上游单据体的明细表名（即采购订单明细的表名），如何获取？我们先分析： 采购入库单的源单明细应该是采购订单的明细，所以直接在BOS上面便可找到采购订单明细内容所存储的表，然后再看截图 由此可见，它的上游单据表名是：t_PUR_POOrderEntry 4，FInStockEntry_Link_FSId，上游单据的明细分录内码。这个需要通过Web API的查看接口（不是单据查询接口），方能知道它的内码是多少。 具体如何调用API的查看接口，请看链接：https://club.kingdee.com/forum.php?mod=viewthread&tid=1485117 综上所述，创建关联关系的4个参数，其中前两个是虚的，随便传个值就行，而后面那两个必须传正确的值。 至此，有源单的单据保存的所有请求参数已构建完毕（创建关联关系的那4个参数一定要放在单据体明细里面，即：FInStockEntry）：如下： post_data={"FormId":"STK_InStock" , "Data":{"Model":{"FSupplierId": {"FNumber": "01.S02.031"},"FDate":"2019-04-21", "FInStockEntry":[{"FMaterialId":{"FNumber": "A.000366"}, "FRealQty":5,"FTaxPrice": 100, "FStockId": {"FNumber": "000"}, "FInStockEntry_Link":[{             "FInStockEntry_Link_FRuleId":"随便传个值，但不能传空值",              "FInStockEntry_Link_FSBillId":"随便传个值，但不能传空值"             "FInStockEntry_Link_FSTableName":"T_PUR_POOrderEntry",             "FInStockEntry_Link_FSId":1000023}]}} 随便多说一嘴，关联源单明细跟本单的明细单据体的数据结构有点类似，都是列表，然后里面放字典，一个字典元素代表一行明细数据，如果源单是多行明细，那么它应该是多个字典元素。 好了，讲了这么多，大家应该知道怎么去构建请求参数了吧。是不是清晰了很多。 再跟大家说一个技巧，先截图： IsAutoSubmitAndAudit：是否自动提交与审核，布尔类型，默认false（非必录） 注（启用此参数，保存，提交和审核是在一个事务中） 看到这个参数了吗？顾名思义，它是可以帮你在保存单据的同时，还可以自动提交审核，够爽吧。当为true时，会自动帮你提交审核的，你连提交审核的接口都不需要再调用了。记得哦。很大效率的一个参数。 3：Cookies(用户验证,基于HTTP协议的) 之前的文章已经说了如何通过API登录验证，这里就不多说了，需要看的话，点击链接查看即可： https://club.kingdee.com/forum.php?mod=viewthread&tid=1484661 这里只是说一下，除了登录校验不需要cookies，其他的API接口都需要携带cookies进行操作的。 建议写一个登录函数，然后返回 cookies，即可每次携带cookies访问了。可参照我下面的函数。 如果没有携带，会出现如下的返回信息： {'Result': {'ResponseStatus': {'ErrorCode': 500, 'IsSuccess': False, 'Errors': [{'FieldName': None, 'Message': 'Context Is Null', 'DIndex': 0}], 'SuccessEntitys': [], 'SuccessMessages': [], 'MsgCode': 1}}} 我也看不懂，反正'IsSuccess'==False，我就知道是操作失败了。 ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- 好了，三大利器准备好了，我就直接上Python代码了： import requests,json login_url="https://pocknoiral.ik3cloud.com/k3cloud/Kingdee.BOS.WebApi.ServicesStub.AuthService.ValidateUser.common.kdsvc" save_url ="https://pocknoiral.ik3cloud.com/K3Cloud/Kingdee.BOS.WebApi.ServicesStub.DynamicFormService.Save.common.kdsvc" login_data={ "acctid":"20180321174312","username":"你的用户名","password":"你的密码","lcid":2052} def login():  # 定义登录函数     login_response=requests.post(url=login_url,data=login_data)     return login_response.cookies   #  返回cookies,方便下次访问时携带 post_data={"FormId":"STK_InStock" , "Data":{"Model":{"FSupplierId": {"FNumber": "01.S02.031"},"FDate":"2019-04-07", "FInStockEntry":[{"FMaterialId":{"FNumber": "A.000366"}, "FRealQty":5,"FTaxPrice": 100, "FStockId": {"FNumber": "000"}, "FInStockEntry_Link":[{             "FInStockEntry_Link_FRuleId":"随便传个值，但不能传空值",              "FInStockEntry_Link_FSBillId":"随便传个值，但不能传空值"             "FInStockEntry_Link_FSTableName":"T_PUR_POOrderEntry",             "FInStockEntry_Link_FSId":1000023}]}} 返回信息： "IsSuccess"==true，说明采购入库单保存成功了！ 总的来说，有源单的单据保存也是非常简单的，它只是多增加了几个参数而已。 另外，它如果符合反写条件的话，也是会触发反写条件的。例如单据的业务关闭状态反写等等。 感谢阅读！！！ 其他的分享，请关注评论内容，里面有链接。 ----------------------------------------------------------------------------------------------------------------------------------------------------------- 另外，如果大家有遇到问题，随时可以加我建立的QQ群：712623210 (金蝶云Web API系统集成沟通群)。只要我能解决的，都会帮忙，毕竟大家都是一个行业的，相互交流，学习。 -----------------------------------------------------------------------------------------------------------------------------------------------------------