.NetCore對接各大財務軟體憑證API——金蝶系列（1）

2020 年 4 月 28 日
筆記

哈嘍，又和大家見面了，雖然看文章的小夥伴不多，但是我相信總有一天，自己寫的這些文章或多或少會對其他人有些幫助，讓他們在相關的業務開發下能少走些彎路，那我的目的就達到了，好了，今天就正式開始我們的系列了，今天要講的是金蝶系列的API，大家都知道，金蝶的產品是比較多的，那麼我們這次要講解的就是金蝶雲星空，或者叫K3Cloud。

首先，作為一名程式猿我們在拿到類似的介面對接需求，第一件是肯定是看相關文檔，然後做介面分析，最後是封裝介面，運用到我們的項目中去，所以對於我們來說，第一步就是尋找相關的開發文檔，在這方面不得不承認，金蝶社區是個好地方。裡面有關於產品的所有知識點和大家遇到的各種問題。廢話不多說，文檔哪裡找，請看下面的步驟

一.K3Cloud介面地址以及財務環境的登錄資訊

我們在做.netCore對接財務系統時，要用到的幾個參數有：賬套號，用戶名，密碼，財務環境地址(支援外網訪問)

這個資訊你可以找你對接的客戶要，最好是能要到外網登錄的地址，因為這樣省去你遠程登錄的麻煩，其次，帳號的許可權也很重要，該帳號下必須能看到名為– WebAPI的菜單，因為我們需要的介面資訊包括後續的測試等都可以在這裡處理。如下圖所示

二.對接要用到的介面列表

既然將憑證API，那麼我們需要用到的幾個菜單在財務會計–總賬下：主要有科目查詢介面、憑證字查詢介面、憑證新增介面

每個操作我們都可以通過在線測試WebAPI來驗證我們的介面資訊，查詢介面的請求參數說明詳見下圖

1.唯一碼的FormId

FormId為每個業務對象的表單Id,如科目對應的就是BD_Account，這裡建議我們在開發時，可以提前將這些用到的表單ID統一設置為常量。參考以下程式碼片段，當然實際開發中我們可能用不到這麼多，大家根據自己的情況進行合理的取捨。

public class BillKeyConst
    {
        #region 財務會計 總賬 

        public const string 科目 = "BD_Account";

        public const string 帳薄 = "BD_AccountBook";

        public const string 會計日曆 = "BD_ACCOUNTCALENDAR";

        public const string 會計要素 = "BD_AccountGroup";

        public const string 幣別 = "BD_Currency";

        public const string 費用項目 = "BD_Expense";

        public const string 匯率 = "BD_Rate";

        public const string 結算方式 = "BD_SETTLETYPE";

        public const string 憑證字 = "BD_VOUCHERGROUP";

        public const string 調整期間管理 = "GL_ADJUSTPERIOD";

        public const string 自動轉賬 = "GL_AutoTransfer";

        public const string 現金流量項目 = "GL_CashFlow";

        public const string 附表項目指定 = "GL_CashIndirectItem";

        public const string 智慧轉存 = "GL_DepositScheme";

        public const string 期末調匯 = "GL_ExchangeScheme";

        public const string 摘要庫 = "GL_Explanation";

        public const string 附表項目調整 = "GL_INDIRECTITEMADJUST";

        public const string 帳薄隸屬關係 = "GL_MultiBookMergeScheme";

        public const string 結轉損益 = "GL_PLScheme";

        public const string T型賬 = "GL_TACCOUNT";

        public const string 憑證 = "GL_VOUCHER";

        public const string 憑證攤銷 = "GL_VoucherAmortize";

        public const string 模式憑證 = "GL_VoucherModel";

        public const string 憑證預提 = "GL_VoucherProvision";

        public const string 會計核算體系 = "Org_AccountSystem";

        #endregion

        #region 財務會計 智慧會計平台

        public const string 業務憑證 = "BAS_BusinessVoucher";

        public const string 憑證生成 = "Bas_MakeBizVchWizard";

        public const string 分錄類型 = "BAS_VchEntryType";

        public const string 憑證模板 = "BAS_VchTemplate";

        public const string 增值稅發票單據 = "GL_AddedTaxBill";

        public const string 增值稅發票識別 = "GL_AddedTaxOcrResult";

        public const string 憑證自動生成方案 = "GL_AutoBuildVoucherScheme";

        public const string 掃描識別模板管理 = "GL_BillOcrTemplate";

        public const string 對賬方案 = "GL_CHECKSCHEME";

        public const string 自定義單據識別 = "GL_OcrResultBase";

        public const string 掃描儀註冊登記 = "GL_ScannerSign";

        public const string 銀行回單_付款 = "GL_YHHDFK";

        public const string 銀行回單_收款 = "GL_YHHDSK";

        #endregion

        #region 供應鏈 採購單據

        public const string SCM_警示燈方案 = "SCM_WarnScheme";

        public const string BD_採購條款 = "BD_PURCLAUSE";

        public const string BD_採購折扣表 = "BD_PurDiscount";

        public const string PUR_評估等級 = "PUR_Assessment";

        public const string PUR_採購評估指標 = "PUR_AssessmentIndex";

        public const string PUR_採購評估方案 = "PUR_AssessmentPlans";

        public const string PUR_貨源清單 = "PUR_CATALOG";

        public const string PUR_採購合約 = "PUR_Contract";

        public const string PUR_採購合約變更單 = "PUR_ContractChange";

        public const string PUR_期初採購退料單 = "PUR_InitMRS";

        public const string PUR_退料申請單 = "PUR_MRAPP";

        public const string PUR_採購退料單 = "PUR_MRB";

        public const string PUR_採購調價表 = "PUR_PAT";

        public const string PUR_採購定價變更單 = "PUR_POChange";

        public const string PUR_採購定價新變更單 = "PUR_POXChange";

        public const string PUR_採購價目表 = "PUR_PriceCategory";

        public const string PUR_物權轉移單 = "PUR_PropertyConvert";

        public const string PUR_採購訂單 = "PUR_PurchaseOrder";

        public const string PUR_收料通知單 = "PUR_ReceiveBill";

        public const string PUR_採購申請單 = "PUR_Requisition";

        public const string PUR_供應商評分表 = "PUR_SupplierAsseementTb";

        public const string PUR_消耗匯總表 = "PUR_VMIConsumeSum";

        public const string STK_期初採購入庫單 = "STK_InitInStock";

        public const string STK_採購入庫單 = "STK_InStock";

        #endregion

        #region 供應鏈 銷售管理

        public const string BD_雲之家考勤設置 = "BD_AttendanceSetting";

        public const string BD_輕應用自定義欄位設置 = "BD_MobExtendFieldConfig";

        public const string BD_銷售折扣表 = "BD_SAL_DiscountList";

        public const string BD_銷售價目表 = "BD_SAL_PriceList";

        public const string BD_銷售條款 = "BD_SALCLAUSE";

        public const string SAL_銷售調價方案 = "SAL_ADJUSTPRICE";

        public const string SAL_可發量查詢 = "SAL_AvailableQuery";

        public const string SAL_批量調價單 = "SAL_BATCHADJUSTPRICE";

        public const string SAL_寄售結算單 = "SAL_ConsignmentSettle";

        public const string SAL_客戶物料對應表 = "SAL_CustMatMapping";

        public const string SAL_發貨通知單 = "SAL_DELIVERYNOTICE";

        public const string SAL_期初銷售出庫單 = "SAL_INITOUTSTOCK";

        public const string SAL_電子面單 = "SAL_KuaidiBill";

        public const string SAL_銷售物流資訊 = "SAL_LogisticsInfo";

        public const string SAL_銷售出庫單 = "SAL_OUTSTOCK";

        public const string SAL_銷售報價單 = "SAL_QUOTATION";

        public const string SAL_退貨通知單 = "SAL_RETURNNOTICE";

        public const string SAL_銷售退貨單 = "SAL_RETURNSTOCK";

        public const string SAL_銷售訂單 = "SAL_SaleOrder";

        public const string SAL_銷售訂單變更單 = "SAL_SaleOrderChange";

        public const string SAL_模擬報價單 = "Sal_SimulateQuotation";

        public const string SAL_標準費率維護 = "Sal_StdExchangeRate";

        public const string SAL_銷售訂單新變更單 = "SAL_XORDER";

        public const string SAL_銷售報價變更單 = "SAL_XQUOTATION";

        #endregion

        #region 供應鏈 信用管理

        public const string CRE_信用檢查規則 = "CRE_CheckRule";

        public const string CRE_信用表更 = "CRE_CreditChange";

        public const string CRE_信用總額特批 = "CRE_CreditSumPermit";

        public const string CRE_信用檔案 = "CRE_CustArchives";

        public const string CRE_客戶物料信用檔案 = "CRE_CustMaterialArchive";

        public const string CRE_信用評估模型 = "CRE_EvalModel";

        public const string CRE_信用評估指標 = "CRE_EvaluateIndex";

        public const string CRE_信用等級方案 = "CRE_Gade";

        public const string CRE_信用評分表 = "CRE_ScoringTable";

        public const string CRE_信用特批許可權 = "CRE_SpecPermission";

        public const string CRE_臨時信用檔案 = "CRE_TmpCustArchives";


        #endregion

        #region 供應鏈 庫存管理

        public const string BD_歸檔序列號 = "BD_ArchivedSerial";

        public const string BD_批號主檔 = "BD_BatchMainFile";

        public const string BD_批號_序列號屬性 = "BD_LotCodeItem";

        public const string BD_批號_序列號編碼規則 = "BD_LotCodeRule";

        public const string BD_生產追溯序列號主檔 = "BD_MTSerialMainFile";

        public const string BD_序列號主檔 = "BD_SerialMainFile";

        public const string BD_倉庫 = "BD_STOCK";

        public const string BD_倉庫最大最小安全庫存 = "BD_StockAlert";

        public const string BD_庫存狀態 = "BD_StockStatus";

        public const string SP_簡單生成入庫單 = "SP_InStock";

        public const string SP_簡單生成退庫單 = "SP_OUTSTOCK";

        public const string SP_簡單生成領料單 = "SP_PickMtrl";

        public const string SP_簡單生成退料單 = "SP_ReturnMtrl";

        public const string STK_組裝拆卸單 = "STK_AssembledApp";

        public const string STK_周期盤點計劃 = "STK_CycleCountPlan";

        public const string BD_物料周期盤點表 = "STK_CycleCountTable";

        public const string STK_即時庫存 = "STK_Inventory";

        public const string STK_初始庫存 = "STK_InvInit";

        public const string STK_庫存鎖庫 = "STK_LockStock";

        public const string STK_鎖庫日誌 = "STK_LOCKSTOCKLOG";

        public const string STK_批號調整單 = "STK_LOTADJUST";

        public const string STK_ABC分配組 = "STK_MaterialABCGroup";

        public const string STK_其他入庫單 = "STK_MISCELLANEOUS";

        public const string STK_其他出庫單 = "STK_MisDelivery";

        public const string STK_委託加工材料入庫單 = "STK_OEMInStock";

        public const string STK_委託加工材料退料單 = "STK_OEMInStockRETURN";

        public const string STK_委託加工材料收料單 = "STK_OEMReceive";

        public const string STK_出庫申請單 = "STK_OutStockApply";

        public const string STK_形態轉換單 = "STK_StatusConvert";

        public const string STK_庫存狀態轉換 = "STK_StockConvert";

        public const string STK_盤盈單 = "STK_StockCountGain";

        public const string STK_物料盤點作業 = "STK_StockCountInput";

        public const string STK_盤虧單 = "STK_StockCountLoss";

        public const string STK_盤點方案 = "STK_StockCountScheme";

        public const string STK_調撥申請單 = "STK_TRANSFERAPPLY";

        public const string STK_直接調撥單 = "STK_TransferDirect";

        public const string STK_分散式調入單 = "STK_TRANSFERIN";

        public const string STK_分散式調出單 = "STK_TRANSFEROUT";

        #endregion

        #region 供應鏈  組織間結算

        public const string IOS_應付結算清單_物料 = "IOS_APSettlement";

        public const string IOS_應付結算清單_費用 = "IOS_APSettlementExp";

        public const string IOS_應付結算清單_資產 = "IOS_APSettlementFA";

        public const string IOS_應收結算清單_物料 = "IOS_ARSettlement";

        public const string IOS_應收結算清單_費員 = "IOS_ARSettlementExp";

        public const string IOS_應收結算清單_資產 = "IOS_ARSettlementFA";

        public const string IOS_組織間結算價目表 = "IOS_PriceList";

        public const string IOS_定時結算 = "IOS_ScheduleSettle";

        public const string IOS_組織間結算關係 = "IOS_SettleRelation";

        public const string IOS_跨組織業務類型 = "IOS_TransferBizType";

        #endregion

        #region 供應鏈 條碼管理

        public const string BD_非同步生成數據 = "BD_AsyncBillScanData";

        public const string BD_條碼盤點清單 = "BD_BarcodeInventoryData";

        public const string BD_條碼屬性 = "BD_BarCodeItem";

        public const string BD_條碼主檔 = "BD_BarCodeMainFile";

        public const string BD_條碼列印 = "BD_BarCodePrint";

        public const string BD_條碼規則 = "BD_BarCodeRule";

        public const string BD_條碼掃描 = "BD_BarCodeScan";

        public const string BD_條碼拆分 = "UN_BarCodeSplit";

        public const string BD_物料編碼解析對應表 = "UN_MaterialMap";

        public const string BD_條碼拆箱表 = "UN_Packaging";

        public const string BD_掃描配置 = "UN_SCAN";

        public const string BD_掃描記錄 = "UN_SCANRecordSet";

        public const string BD_條碼掃描任務 = "UN_SCANTASK";

        public const string BD_條碼掃描任務生成日誌 = "UN_SCANTASKCREATELOG";

        public const string BD_條碼掃描任務方案 = "UN_SCANTASKSCHEME";

        #endregion

        #region 供應鏈 供應商管理

        public const string SVM_企業公告 = "SVM_BusinessBulletin";

        public const string SVM_比價單 = "SVM_ComparePrice";

        public const string SVM_詢價單 = "SVM_InquiryBill";

        public const string SVM_報價單 = "SVM_QuoteBill";

        public const string SVM_供應商角色 = "SVM_Role";

        public const string SVM_供應商用戶 = "SVM_SUPPLIERUSER";

        #endregion

        #region 供應鏈 供應商協同

        public const string SCP_供應商協同條碼列印 = "SCP_BarCodePrint";

        public const string SCP_供應商協同條碼掃描 = "SCP_BarCodeScan";

        public const string SCP_企業公告 = "SCP_BusinessBulletin";

        public const string SCP_詢價單 = "SCP_InquiryBill";

        public const string SCP_採購入庫單 = "SCP_InStock";

        public const string SCP_退料通知單 = "SCP_MRAPP";

        public const string SCP_採購退料單 = "SCP_MRB";

        public const string SCP_應付單 = "SCP_Payable";

        public const string SCP_採購訂單變更單 = "SCP_POChange";

        public const string SCP_採購訂單 = "SCP_PurchaseOrder";

        public const string SCP_報價單 = "SCP_QuoteBill";

        public const string SCP_送貨通知單 = "SCP_ReceiveBill";

        public const string SCP_供應商協同即時庫存查詢 = "SCP_STKInventory";

        public const string SCP_供應商評估報告 = "SCP_SupplierAssResport";

        public const string SCP_供應商註冊資料 = "SCP_SupReg";

        public const string SCP_供應商協同VMI消耗匯總表 = "SCP_VMIConsumeSum";

        #endregion

        #region 基礎管理--基礎資料

        public const string 關鍵字_智慧機器人 = "BAS_ROBOTKEYWORDS";

        public const string 消息任務_智慧機器人 = "BAS_ROBOTMSGTASK";

        public const string 關鍵字服務_智慧機器人 = "BAS_ROBOTSERVICE";

        public const string 會計政策 = "BD_ACCTPOLICY";

        public const string 輔助屬性值組合 = "BD_AuxPtyValCom";

        public const string 輔助屬性值 = "BD_AuxPtyValue";

        public const string 銀行 = "BD_BANK";

        public const string 聯繫對象 = "BD_ContactObject";

        public const string 客戶 = "BD_Customer";

        public const string 客戶_包含非交易客戶 = "BD_Customer_All";

        public const string 部門 = "BD_Department";

        public const string 員工 = "BD_Empinfo";

        public const string 快遞100物流公司 = "BD_KD100LogisticsCom";

        public const string 物料 = "BD_MATERIAL";

        public const string 存貨類別 = "BD_MATERIALCATEGORY";

        public const string 存貨模板 = "BD_MATERIALTEMPLATE";

        public const string 物料單位換算 = "BD_MATERIALUNITCONVERT";

        public const string 員工任崗資訊 = "BD_NEWSTAFF";

        public const string 業務員 = "BD_OPERATOR";

        public const string 業務組 = "BD_OPERATORGROUPBILL";

        public const string 付款條件 = "BD_PaymentCondition";

        public const string 崗位彙報 = "BD_PostReport";

        public const string 收款條件 = "BD_RecCondition";

        public const string 供應商 = "BD_Supplier";

        public const string 稅組合 = "BD_TAXMIX";

        public const string 稅率 = "BD_TaxRate";

        public const string 稅務規則 = "BD_TAXRULE";

        public const string 稅收制度 = "BD_TAXSYSTEM";

        public const string 稅種 = "BD_TAXTYPE";

        public const string 計量單位 = "BD_UNIT";

        public const string 銀行帳號 = "CN_BANKACNT";

        public const string 現金帳號 = "CN_CASHACCOUNT";

        public const string 內部賬戶 = "CN_INNERACCOUNT";

        public const string 其他往來單位 = "FIN_OTHERS";

        public const string 崗位資訊 = "HR_ORG_HRPOST";

        #endregion

        #region 基礎管理--組織管理

        public const string 組織隸屬關係 = "ORG_Affiliation";

        public const string 分配執行情況 = "ORG_AutoAllocateLogInfo";

        public const string 基礎資料自動分配計劃 = "ORG_AUTOALLOCATEPLAN";

        public const string 基礎資料控制策略 = "ORG_BaseDataControlPolicy";

        public const string 組織業務關係 = "ORG_BizRelation";

        public const string 組織變更檢查規則 = "ORG_ChangeChkRule";

        public const string 組織變更方案 = "ORG_ChangeSolution";

        public const string 組織機構 = "ORG_Organizations";

        public const string 組織形態 = "ORG_OrgBodyForm";

        public const string 組織用戶維護 = "Org_OrgUserRoleMap";

        #endregion
    }

View Code

2.查詢欄位集合

FieldKeys為要查詢的欄位Key集合，如我需要查詢的欄位有FName,FNumber等，詳細的欄位說明可以通過保存介面查看

那麼我們只需要傳入FName,FNumber即可。

3.返回結果的處理

返回的結果是個數組類型，所以我們無法直接通過.net序列化為對象，所以建議是直接序列化為JArry數組，然後進行取值。

三. .NetCore對接處理

3.1登錄以及業務介面處理

有了以上的對接參數和簡單的介面資訊了解之後，我們就可以開始我們的API介面對接工作了，

首先，在社區一位大佬封裝的WebAPI的基礎上，我們來處理.netCore環境下的WebAPI介面，非常感謝大佬，我們可以看到封裝的介面文件如下圖所示：

常用的有Query、BatchSave類，如下圖所示

Query操作

    /// <summary>
    /// 執行查詢操作。
    /// </summary>
    public class Query : FormOperation
    {
        #region 公共覆蓋操作參數

        /// <summary>
        /// 操作的服務名稱定義。
        /// </summary>
        public override string ServiceName
        {
            get
            {
                return "Kingdee.BOS.WebApi.ServicesStub.DynamicFormService.ExecuteBillQuery";
            }
        }//end property

        /// <summary>
        /// 操作的請求參數。
        /// </summary>
        public override string RequestParameters
        {
            get
            {
                var parametersArray = new object[]
                {
                    new 
                    {
                        FormId = this.ObjectTypeId,
                        TopRowCount = this.TopRowCount,
                        Limit = this.PageRowCount == default(int) ? 2000 : this.PageRowCount,
                        StartRow = this.PageIndex,
                        FilterString = this.Filter,
                        OrderString = this.OrderBy,
                        FieldKeys = string.Join(",", this.FieldKeys)
                    }
                };

                return JsonConvert.SerializeObject(parametersArray);
            }
        }//end property

        #endregion

        #region 公共操作參數屬性

        /// <summary>
        /// 讀寫最多允許查詢的數量屬性值。
        /// </summary>
        /// <remarks>
        /// 0或者不要此屬性表示不限制。
        /// </remarks>
        public virtual int TopRowCount { get; set; }//end property

        /// <summary>
        /// 讀寫分頁取數每頁允許獲取的數據屬性值。
        /// </summary>
        /// <remarks>
        /// 最大不能超過2000。
        /// </remarks>
        public virtual int PageRowCount { get; set; }//end property

        /// <summary>
        /// 讀寫分頁取數開始行索引屬性值。
        /// </summary>
        /// <remarks>
        /// 從0開始，例如每頁10行數據，第2頁開始是10，第3頁開始是20，以此類推，當不提供此屬性，表示僅查詢Limit中填寫的數據量。
        /// </remarks>
        public virtual int PageIndex { get; set; }//end property

        /// <summary>
        /// 讀寫過濾條件屬性值。
        /// </summary>
        public virtual string Filter { get; set; }//end property

        /// <summary>
        /// 讀寫排序條件屬性值。
        /// </summary>
        public virtual string OrderBy { get; set; }//end property

        /// <summary>
        /// 讀寫表單返回數據欄位的索引鍵屬性值。
        /// </summary>
        public virtual List<string> FieldKeys { get; set; }//end property

        #endregion

        #region 公共方法

        /// <summary>
        /// 設置讀寫動態表單類型標識。
        /// </summary>
        /// <param name="objectTypeId">動態表單類型標識。</param>
        /// <returns>返回類本身實例對象。</returns>
        public virtual Query SetObjectTypeId(string objectTypeId)
        {
            return this.SetObjectTypeId<Query>(objectTypeId);
        }//end method

        /// <summary>
        /// 設置最多允許查詢的單據數量。
        /// </summary>
        /// <param name="topRowCount">單據數量值。</param>
        /// <returns>返回類本身實例對象。</returns>
        public virtual Query SetTopRowCount(int topRowCount)
        {
            this.TopRowCount = topRowCount;
            return this;
        }//end method

        /// <summary>
        /// 設置分頁取數每頁允許獲取的單據數量。
        /// </summary>
        /// <param name="pageRowCount">分頁數量值。</param>
        /// <returns>返回類本身實例對象。</returns>
        public virtual Query SetPageRowCount(int pageRowCount)
        {
            this.PageRowCount = pageRowCount;
            return this;
        }//end method

        /// <summary>
        /// 設置分頁取數開始行索引。
        /// </summary>
        /// <param name="pageIndex">索引值。</param>
        /// <returns>返回類本身實例對象。</returns>
        public virtual Query SetPageIndex(int pageIndex)
        {
            this.PageIndex = pageIndex;
            return this;
        }//end method

        /// <summary>
        /// 設置過濾條件。
        /// </summary>
        /// <param name="filter">過濾條件。</param>
        /// <returns>返回類本身實例對象。</returns>
        public virtual Query SetFilter(string filter)
        {
            this.Filter = filter;
            return this;
        }//end method

        /// <summary>
        /// 設置排序條件。
        /// </summary>
        /// <param name="orderBy">排序條件。</param>
        /// <returns>返回類本身實例對象。</returns>
        public virtual Query SetOrderBy(string orderBy)
        {
            this.OrderBy = orderBy;
            return this;
        }//end method

        /// <summary>
        /// 表單返回數據欄位。
        /// </summary>
        /// <param name="fieldKey">欄位索引鍵。</param>
        /// <returns>返回類本身實例對象。</returns>
        public virtual Query AddFieldKey(string fieldKey)
        {
            if (this.FieldKeys == null)
            {
                this.FieldKeys = new List<string>();
            }//end if

            this.FieldKeys.Add(fieldKey);
            return this;
        }//end method

        #endregion

    }//end class

View Code

BatchSave操作，主要用於憑證的批量保存

    /// <summary>
    /// 執行批量保存操作。
    /// </summary>
    public class BatchSave : Save
    {
        #region 公共覆蓋操作參數

        /// <summary>
        /// 操作的服務名稱定義。
        /// </summary>
        public override string ServiceName
        {
            get
            {
                return "Kingdee.BOS.WebApi.ServicesStub.DynamicFormService.BatchSave";
            }
        }//end property

        /// <summary>
        /// 待保存的數據對象。
        /// </summary>
        public override string RequestParameters
        {
            get
            {
                var parametersArray = new object[]{
                    this.ObjectTypeId,
                    new
                    {
                        Creator = string.IsNullOrEmpty(this.Creator) ? "IT" : this.Creator ,
                        NeedUpDateFields = this.NeedUpdateFieldKeys,
                        NeedReturnFieldKeys=this.NeedReturnFieldKeys,
                        Model = this.Models,
                        IsEntryBatchFill=this.IsEntryBatchFill,
                        IsDeleteEntry = this.IsDeleteEntry,
                        SubSystemId = this.SubSystemId,
                        IsAutoSubmitAndAudit=this.IsAutoSubmitAndAudit,
                        IsVerifyBaseDataField = this.IsVerifyBaseDataField,
                        NumberSearch = (this.BDSetter == BaseDataSetter.Number),
                        BatchCount=this.BatchCount
                    }
                };

                return JsonConvert.SerializeObject(parametersArray);
            }
        }//end property

        #endregion

        #region 公共操作參數屬性

        /// <summary>
        /// 讀寫待保存的數據對象。
        /// </summary>
        public override object Model
        {
            get
            {
                return this.Models == null ? null : this.Models.FirstOrDefault();
            }
            set
            {
                if (this.Models == null)
                {
                    this.Models = new List<object>();
                }//end if
                this.Models.Add(value);
            }
        }//end property

        /// <summary>
        /// 讀寫待保存的多個數據對象。
        /// </summary>
        public virtual List<object> Models { get; set; }//end property

        /// <summary>
        /// 是否批量填充分錄。
        /// </summary>
        public virtual bool IsEntryBatchFill { get; set; }//end property

        public virtual bool IsAutoSubmitAndAudit { get; set; }
        public virtual int BatchCount { get; set; }

        #endregion

        #region 公共方法

        /// <summary>
        /// 添加待保存的數據對象。
        /// </summary>
        /// <param name="model">待保存的數據對象。</param>
        /// <returns>返回類本身實例對象。</returns>
        public virtual BatchSave AddModel(object model)
        {
            if (this.Models == null)
            {
                this.Models = new List<object>();
            }//end if
            this.Models.Add(model);
            return this;
        }//end method

        /// <summary>
        /// 設置待保存的數據對象，但無論執行多少次只會保留最後一次設置的數據對象。
        /// </summary>
        /// <param name="model">待保存的數據對象。</param>
        /// <returns>返回類本身實例對象。</returns>
        new public virtual BatchSave SetModel(object model)
        {
            return this.SetModel<BatchSave>(model);
        }//end method

        #endregion

    }//end class

View Code

然後我們來看APIException類，可以看到該異常處理類統一繼承自Kingdee.BOS.WebAPi.Client.ServiceException.

所以我們要引用 Kingdee.BOS.WebApi.Client.dll

另外這裡官網給的程式碼示例中有句話很值得重視：// 使用webapi引用組件Kingdee.BOS.WebApi.Client.dll

這個組件我們可以在金蝶的安裝目錄下找到，當你興緻勃勃的找到這個dll，並將它引用到你的.netCore的項目中時，編譯運行你會發現有個ServiceException類在.netCore環境下不支援，因為它僅在.net Framework支援。

所以呢，我們的第一反應是這可咋辦，別著急，我們總有辦法解決，反編譯應該是我們在開發過程中比較常見的解決問題的辦法，所以當我們將上述的dll進行反編譯以後，我們可以得到如下一堆文件

接著我們就可以來處理我們的介面了，按照示例程式碼中的一樣，我們來實現登錄介面

/// <summary>
/// 實現登錄。
/// </summary>
/// <returns>返回API結果。</returns>
public virtual APIResponse<LoginResult> Login()
{
var result = APIClient.CreateAPIOperation<LoginByUserPassword>(_Config.URL)
.SetDBId(_Config.DBId)
.SetUserName(_Config.UserName)
.SetPassword(_Config.Password)
.ToKdAPIRequest()
.ToAPIResponse<LoginResult>();
return result;
}

View Code

_config.Url—對應我們的金蝶財務環境的登錄地址

_config.DBid–對應我們要操作的賬套號—怎麼查看到這個賬套號是多少呢？還記得我們上面說的那個WebAPI菜單嘛，沒錯就是那裡。我們隨便點開一個菜單，比如我這裡以科目為例，我們選中科目後，點擊在線測試WebAPI按鈕，就能找到我們所需的各自參數了。

_config.UserName –登錄的用戶名

_config.Password — 登錄的用戶名的密碼

這四個參數就對應我們登錄介面的四個參數。

要注意的一點是我們在調用我們的業務介面時，必須先調用登錄介面以實現登錄操作。不然無法操作我們的業務介面。

        /// <summary>
        /// 查詢人民幣幣別編碼
        /// </summary>
        /// <returns></returns>
        public string QueryCurrency()
        {
            this.Login();
            var result = APIClient.CreateAPIOperation<Query>(_Config.URL)
                .SetObjectTypeId(BillKeyConst.幣別)
                .AddFieldKey("FNumber")
                .AddFieldKey("FName")
                .SetFilter("FName like '%人民幣%'")
                .ToAPIRequest<KdAPIRequest>().Execute<JArray>();
            if (result.Count > 0)
            {
                return result[0][0].ToString();
            }
            else
            {
                return "";
            }
        }

如我們上圖所示的查詢人民幣的名稱和編碼。當然這只是查詢單個實體，當我們查詢所有的數據時，就可能會用到分頁查詢，因為金蝶的查詢介面默認一次查詢2000條數據，所以當總數量超過2000時，我們就需要用到分頁查詢了。

       public string QueryBasicInfoByPageList(string typeId, string FieldName, string Filter, int pageIndex)
        {
            this.Login();
            var result = APIClient.CreateAPIOperation<Query>(_Config.URL)
                .SetObjectTypeId(typeId)
                .AddFieldKey(FieldName)
                .SetFilter(Filter)
                .SetPageIndex(pageIndex)
                .ToAPIRequest<KdAPIRequest>().Execute<string>();
            return result;
        }

只需要在原有的基礎上，增加pageIndex-頁碼參數即可，不過要注意的是每次查詢的起始頁碼是不一樣的，這樣才能通過循環來得到我們需要的列表數據。

3.2 憑證保存介面

        /// <summary>
        /// 批量保存單據實體
        /// </summary>
        /// <param name="typeId"></param>
        /// <param name="models"></param>
        /// <returns></returns>
        public string BatchSave(string typeId, List<object> models)
        {
            this.Login();
            var client = APIClient.CreateAPIOperation<BatchSave>(_Config.URL);
            client.SetObjectTypeId(typeId);
            client.Models = models;
            return client.ToAPIRequest<KdAPIRequest>().Execute<string>();
        }

View Code

憑證批量保存介面，所以當我們在外部構造好憑證實體後，就可直接通過該介面來處理憑證的保存工作。憑證保存實體如下CloudSaveVoucherModel

  public class CloudSaveVoucherModel
    {
        public string FVoucherID { get; set; }
        public FVoucherNumber FAccountBookID { get; set; }
        public string FDate { get; set; }
        public FVoucherNumber FVoucherGroupID { get; set; }
        public string FVoucherGroupNo { get; set; }
        public string FIsAdjustVoucher { get; set; }
        public string FDocumentStatus { get; set; }
        public string FYear { get; set; }
        public FVoucherNumber FSourceBillKey { get; set; }
        public string FPeriod { get; set; }
        public string FImportVersion { get; set; }
        public Fentity[] FEntity { get; set; }
    }
    public class FVoucherNumber
    {
        public string FNumber { get; set; }
    }
    public class Fentity
    {
        public string FEntryID { get; set; }
        public string FExplanation { get; set; }
        public FVoucherNumber FAccountID { get; set; }
        public Fdetailid FDetailID { get; set; }
        public FVoucherNumber FCurrencyID { get; set; }
        public FVoucherNumber FExchangerateType { get; set; }
        public string FExchangeRate { get; set; }
        public FVoucherNumber FUnitId { get; set; }
        public string FPrice { get; set; }
        public string FQty { get; set; }
        public decimal FAmountFor { get; set; }
        public decimal FDebit { get; set; }
        public decimal FCredit { get; set; }
        public FVoucherNumber FSettleTypeID { get; set; }
        public string FSettleNo { get; set; }
        public string FExportentryID { get; set; }
    }
    public class Fdetailid
    {
        /// <summary>
        /// 費用項目
        /// </summary>
        public FVoucherNumber FDetailID__Fflex9 { get; set; }
        /// <summary>
        /// 供應商
        /// </summary>
        public FVoucherNumber FDetailID__Fflex4 { get; set; }
        public FVoucherNumber FDetailID__Fflex5 { get; set; }
        /// <summary>
        /// 客戶
        /// </summary>
        public FVoucherNumber FDetailID__Fflex6 { get; set; }
        /// <summary>
        /// 員工
        /// </summary>
        public FVoucherNumber FDetailID__Fflex7 { get; set; }
        /// <summary>
        /// 物料
        /// </summary>
        public FVoucherNumber FDetailID__Fflex8 { get; set; }
        /// <summary>
        /// 資產類別
        /// </summary>
        public FVoucherNumber FDetailID__Fflex10 { get; set; }
        /// <summary>
        /// 組織機構
        /// </summary>
        public FVoucherNumber FDetailID__Fflex11 { get; set; }
        /// <summary>
        /// 物料分組
        /// </summary>
        public FVoucherNumber FDETAILID__FF100005 { get; set; }
        public FVoucherNumber FDetailID__Fflex12 { get; set; }
        public FVoucherNumber FDetailID__Fflex13 { get; set; }
    }

通過前面的BatchSave類，我們可以看到有個屬性叫做NeedReturnFieldKeys — 意為需要返回的欄位，等於是在執行成功保存操作後，金蝶可以直接將我們需要返回的欄位返回回來，傳遞形式還是和查詢的FieldsKey格式一樣，但是在實際的開發過程中我發現其實即便你傳了NeedReturnFieldKeys，但是在返回值中並沒有正常返回。我曾經在論壇里找個該問題，發現有小夥伴也遇到同樣的問題。但是都沒有得到解決，因為我在實際的邏輯中還需要得到類似總金額，憑證日期，憑證號等欄位，所以沒辦法只能通過查詢介面再執行一次查詢操作了，當然不涉及後續的業務處理的話，可以不用執行該步驟的。

ps：當你執行批量保存操作時，如果一次操作的JSon數據量過大時，介面提示操作超時，所以在實際開發中建議可以分批次進行保存操作。

四.結語

相對來說，K3Cloud的介面文檔還是比較全面的，所以當時在實際開發的時候，並沒有遇到很多坑，只是在API封裝的過程中，如上述說到的.netCore環境不支援的情況，這樣的話通過反編譯來處理問題也是一個不錯的辦法。後續我們還會在處理用友的一個產品時同樣使用反編譯來處理問題。

以上就是自己在實際生產過程中處理K3CloudAPI介面時的一些想法和思路。比如金蝶社區，論壇是不錯的選擇。同樣QQ群也是一個溝通交流的途徑。比如上面說到的批量保存時JSon串過大導致介面操作超時的問題，就是通過群里一個小夥伴的提醒，改變了思路通過分批傳遞的方法來解決問題的。我想說的是在開發過程中我們會遇到各種各樣的問題，但是通過解決這些問題我們就能得到鍛煉和成長，這就是我們的財富。說實話在之前我從沒接觸過這些知識點和業務範圍，但是這不是也是一種成長的方式嘛。希望可以給在開發對接此產品的小夥伴一點幫助，一點支援就夠了。

附上本文中的示例程式碼：K3Cloud介面