如何逐步构建采购订单Web API保存接口参数

需求背景：
K/3 Cloud提供了Web API接口，供第三方程序调用，以实现与第三方系统之间的数据集成。
调用Web API接口虽然简单，但是构建参数却非常复杂，与各单据上的字段密切相关。

K/3 Cloud内置了一个Web API接口说明功能，提供了示例代码，演示如何调用各单据的各种操作。
遗憾的是，示例代码中的参数，包含了全部单据头字段，但没有包括单据体字段，完全按照此示例代码调用接口，往往会保存失败。

案例说明：
本案例，基于采购订单的保存接口，演示如何构建各种字段参数，单据体字段参数。
以便读者在K/3 Cloud内置的Web API接口示例代码基础上，据此类推，自行构建出各种单据，Web API保存接口需要的，包含了单据体字段的完整参数。

为方便阅读，本案例仅构建了采购订单必须的字段参数，其他类似的字段，直接忽略。

示例代码：

using System;
using System.Collections.Generic;
using System.ComponentModel;
using System.Data;
using System.Drawing;
using System.Linq;
using System.Text;
using System.Windows.Forms;

using Newtonsoft.Json.Linq;
using Kingdee.BOS.WebApi.Client; 
//*********************************************************

        /// <summary>
        /// 采购订单
        /// </summary>
        private string Sample2015121401()
        {
            try
            {
                // K/3 Cloud业务站点URL
                // using Kingdee.BOS.WebApi.Client; // (需引用Kingdee.BOS.WebApi.Client.dll)
                ApiClient client = new ApiClient(this.txtWebSite.Text);

                // 调用登录接口：
                // 参数说明：
                // dbid     : 数据中心id。到管理中心数据库搜索：
                //            select FDataCenterId, * from T_BAS_DataCenter
                // userName : 用户名
                // password ：原始密码（未加密）
                // loid     : 语言id，中文为2052，中文繁体为3076，英文为1033
                var loginResult = client.Login(
                    this.txtDbId.Text,
                    this.txtUser.Text,
                    this.txtPassword.Text,
                    2052);

                string result = "登录失败，请检查与站点地址、数据中心Id，用户名及密码！";

                // 登陆成功，开始保存数据
                if (loginResult == true)
                {
                    // 开始构建Web API参数对象
                    // 参数根对象：包含Creator、NeedUpDateFields、Model这三个子参数
                    // using Newtonsoft.Json.Linq;  // (需引用Newtonsoft.Json.dll)
                    JObject jsonRoot = new JObject();

                    // Creator: 创建用户
                    jsonRoot.Add("Creator", "Demo");

                    // NeedUpDateFields: 哪些字段需要更新？为空则表示参数中全部字段，均需要更新
                    jsonRoot.Add("NeedUpDateFields", new JArray(""));

                    // Model: 单据详细数据参数
                    JObject model = new JObject();
                    jsonRoot.Add("Model", model);
                    // 开始设置单据字段值
                    // 必须设置的字段：主键、单据类型、主业务组织，各必录且没有设置默认值的字段
                    // 特别注意：字段Key大小写是敏感的，建议从BOS设计器中，直接复制字段的标识属性过来

                    // 单据主键：必须填写，系统据此判断是新增还是修改单据；新增单据，填0
                    model.Add("FID", 0);

                    // 采购组织：主业务组织，必须填写，是基础资料字段
// 基础资料类型字段填值，必须再构建一个JObject对象，设置基础资料编码
                    JObject basedata = new JObject();
                    basedata.Add("FNumber", "101.2");
                    model.Add("FPurchaseOrgId", basedata);

                    // 单据类型：必须填写，是基础资料字段                    
                    basedata = new JObject();
                    basedata.Add("FNumber", "CGDD01_SYS");
                    model.Add("FBillTypeID", basedata);

                    // 单据编号：可以忽略，由系统根据编码规则自动生成
                    model.Add("FBillNo", "JDCGDD15120001");

                    //采购日期（FDate）
                    model.Add("FDate", DateTime.Today);

                    // 录入业务上要求必须提前设置的字段
                    // 这些字段通常无需由用户手工录入，提前设好默认值，如汇率类型、本位币等

                    // 汇率类型(FExchangeTypeId):基础资料
                    basedata = new JObject();
                    basedata.Add("FNumber", "HLTX01_SYS");
                    model.Add("FExchangeTypeId", basedata);

                    // 本位币（FLocalCurrId）：基础资料
                    basedata = new JObject();
                    basedata.Add("FNumber", "PRE001");
                    model.Add("FLocalCurrId", basedata);

                    // 按手工录入顺序，录入其他关键业务字段

                    // 供应商(FSupplierId)：基础资料
                    basedata = new JObject();
                    basedata.Add("FNumber", "VEN00002");
                    model.Add("FSupplierId", basedata);

                    // 其他单据头字段，非必录，本示例代码忽略

                    // 开始构建单据体参数：集合参数JArray
                    JArray entryRows = new JArray();
                    
                    // 添加新行
                    JObject entryRow = new JObject();
                    entryRows.Add(entryRow);

                   // 给新行，设置关键字段值
                    // 单据体主键：必须填写，系统据此判断是新增还是修改行
                    entryRow.Add("FEntryID", 0);

                    //物料(FMaterialId)：基础资料，填写编码
                    basedata = new JObject();
                    basedata.Add("FNumber", "1.01.001.0055");
                    entryRow.Add("FMaterialId", basedata);

                    // 单位(FUnitId)：基础资料，填写编码
                    basedata = new JObject();
                    basedata.Add("FNumber", "Pcs");
                    entryRow.Add("FUnitId", basedata);

                    // 数量(FQty)：数量字段
                    entryRow.Add("FQty", 10);

                    // 单价(FPrice)：单价字段
                    entryRow.Add("FPrice", 11.7);

                    // 其他单据体字段，非必录，本示例代码忽略

                   // 把单据体行集合，添加到model中，以单据体Key为标识
                    model.Add("FPOOrderEntry", entryRows);

                    // 调用Web API接口服务，保存采购订单
                    result = client.Execute<string>(
                        "Kingdee.BOS.WebApi.ServicesStub.DynamicFormService.Save",
                        new object[] {"PUR_PurchaseOrder", jsonRoot.ToString() });
                }

                return result;

            }
            catch(Exception exp)
            {
                StringBuilder sb = new StringBuilder();
                sb.AppendLine("程序运行遇到了未知的错误：");
                sb.Append("错误提示：").AppendLine(exp.Message);
                sb.Append("错误堆栈：").AppendLine(exp.StackTrace);
                return sb.ToString();
            }
        }