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系統集成溝通群)。只要我能解決的，都會幫忙，畢竟大家都是一個行業的，相互交流，學習。
-----------------------------------------------------------------------------------------------------------------------------------------------------------
|