K3 CLOUD API接口说明书V2.0

K3Cloud WebAPI 接口说明书_V2.0

修改记录

Ver. No	发版日期	编制人	批准人	修改的章节号
V1.0	2016/8/9			初始版本
V2.0	2017/1/19			附录6

目   录

1. 概述 

1.1. 目的 

1.2. 范围 

1.3. 适用对象 

1.4. 参考资料 

2. 问题与解决策略 

3. 目标和约束 

4. WebAPI架构 

4.1. 采用的技术 

4.1.1. Kingdee.BOS.WebApi.FormService.dll 

4.1.2. Kingdee.BOS.WebApi.ServicesStub.dll 

4.1.3. Kingdee.BOS.WebApi.Client.dll 

4.1.4. 开发工具 

5. WebAPI接口详细描述 

5.1.1. 登陆验证接口 

5.1.2. 查看表单数据接口 

5.1.3. 保存表单数据接口 

5.1.4. 批量保存表单数据接口 

5.1.5. 提交表单数据接口 

5.1.6. 审核表单数据接口 

5.1.7. 反审核表单数据接口 

5.1.8. 删除表单数据接口 

5.1.9. 表单数据查询接口 

5.1.10. 自定义WebAPI接口 

6. 附录（集成相关知识分享） 

1. 概述
   1. 目的

为异构系统访问K/3Cloud系统数据提供通用的接口。

当企业规模逐渐增大时，作为支撑业务运营的IT建设也变得越来越重要，不过往往企业的IT建设过程中会发现某一家软件供应商基本不能完全覆盖企业所有的业务运营流程，这样的结果就是，企业上的IT系统很多很全，从ERP到HR、CRM、PDM、OA等，貌似所有的业务都覆盖到了，但实际上因为这些系统的不集成，而形成了企业很多新的信息孤岛，非常不利于企业的后续的管理和战略发展。K/3Cloud从现今和往后的发展趋势来看，也不可避免会遇到上述问题，毕竟企业经营的多样化，并不是所有的业务都能在K/3Cloud中完成，所以我们必须在产品架构上支持更好的与外部系统进行协同。

1. 1. 范围

• • 适用版本：V5.0和后续版本

1. 1. 适用对象

本文档适用于：

• 开发工程师：参考，对系统集成的实现获取全局性的设计指导。

1. 1. 参考资料

1. 问题与解决策略

愿景	关注点	描述与示例

1. 目标和约束

目标：

• 提供对K/3Cloud单据和基础信息的查看、保存、提交、审核、反审核和删除等功能；
• 提供对K/3Cloud单据和基础信息的查询功能；

约束：

• 数据操作接口仅支持以基础资料编码、单据编号或直接以表单主键去操作数据；
• 支持对某一具体单据的数据查询，但多单关联查询需要二开接口实现。

1. WebAPI架构

1. 1. 采用的技术

K/3 Cloud WebAPI是一种轻量级的、可维护的、可伸缩的 Web 服务。采用HTTP+JSON，也就是用RESTful的方式来开发。使用.NET Framework 4.0为开发平台，源代码使用C#编写。整个框架由三个组装件组成。

1. 1. 1. Kingdee.BOS.WebApi.FormService.dll

此组装件包含WebAPI主要接口的功能实现。部署在应用层服务器。

1. 1. 1. Kingdee.BOS.WebApi.ServicesStub.dll

此组装件主要包含WebAPI接口定义，扩展接口定义以及登陆验证接口。部署在应用层服务器。

1. 1. 1. Kingdee.BOS.WebApi.Client.dll

此组装件为WebAPI的客户端组件，封装了一些在异构系统客户端访问WebAPI的方法，适用于C#程序调用。由于它应用于异构系统客户端，所以此组装件需要拷贝到异构系统客户端环境中。非C#程序调用可以不用拷贝。

1. 1. 1. 开发工具

.Net FrameWork 4.0

Microsoft Visual Studio 2012

1. WebAPI接口详细描述
   1. 1. 登陆验证接口

服务地址：

http://ServerIp/K3Cloud/Kingdee.BOS.WebApi.ServicesStub.AuthService.ValidateUser.common.kdsvc

接口参数：

参数列表	参数含义	备注
acctID	账套Id，从管理中心数据库查询获得 参考查询：select FDATACENTERID from T_BAS_DATACENTER	必须
username	用户登陆名	必须
password	密码	必须
lcid	语言id,选择哪种语言访问，参考：中文2052，英文1033，繁体3076	非必须，引用SDK组件辅助类调用则必须

返回参数：

参数列表	参数含义	备注
LoginResultType	//激活         Activation = -7,         //云通行证未绑定Cloud账号         EntryCloudUnBind = -6,                 //需要表单处理         DealWithForm = -5,         //登录警告         Wanning = -4,         //密码验证不通过（强制的）         PWInvalid_Required = -3,         //密码验证不通过（可选的）         PWInvalid_Optional = -2,         //登录失败         Failure = -1,         //用户或密码错误         PWError = 0,         //登录成功         Success = 1	管理员登陆可能出现返回-5的情况，这种情况在api验证时也可认为是允许的，具体可以根据实际情况来定。 var result = JObject.Parse(ret)["LoginResultType"].Value();             if (result == 1||result==-5)             {                 return true;             }

调用参考：

1. SDK辅助类示例（引用Kingdee.BOS.WebAPI.Client.dll）：

说明：下文中出现的client都为此处进行过登陆验证的ApiClient实例。

            ApiClient client = new ApiClient("http://192.168.66.60/k3cloud/");

            string dbId = "5756960b27b1aa"; //AotuTest117

            bool bLogin = client.Login(dbId, "demo", "888888", 2052);

            if (bLogin)

            {

                //todo:登陆成功处理业务

            }

1. 无引用组件示例（不引用金蝶的组件）：

说明：以下HttpClient为自定义客户端调用辅助类，下文中所指HttpClient都表示这个类。

using System;

using System.Collections.Generic;

using System.IO;

using System.Net;

using System.Text;

using Newtonsoft.Json.Linq;

using Newtonsoft.Json;

public class HttpClient

    {

        ///

        /// Seivice URL

        ///

        public string Url { get; set; }

        ///

        /// 内容

        ///

        public string Content { get; set; }

        ///

        /// Cookie，保证登录后，所有访问持有一个Cookie；

        ///

        static CookieContainer Cookie = new CookieContainer();

        ///

        /// HTTP访问

        ///

        public string AsyncRequest()

        {

            HttpWebRequest httpRequest = HttpWebRequest.Create(Url) as HttpWebRequest;

            httpRequest.Method = "POST";

            httpRequest.ContentType = "application/json";

            httpRequest.CookieContainer = Cookie;

            httpRequest.Timeout = 1000 * 60 * 10;//10min

            using (Stream reqStream = httpRequest.GetRequestStream())

            {

                JObject jObj = new JObject();

                jObj.Add("format", 1);

                jObj.Add("useragent", "ApiClient");

                jObj.Add("rid", Guid.NewGuid().ToString().GetHashCode().ToString());

                jObj.Add("parameters", Content);

                jObj.Add("timestamp", DateTime.Now);

                jObj.Add("v", "1.0");

                string sContent = jObj.ToString();

                var bytes = UnicodeEncoding.UTF8.GetBytes(sContent);

                reqStream.Write(bytes, 0, bytes.Length);

                reqStream.Flush();

            }

            using (var repStream = httpRequest.GetResponse().GetResponseStream())

            {

                using (var reader = new StreamReader(repStream))

                {

                    return ValidateResult(reader.ReadToEnd());

                }

            }

        }

        private static string ValidateResult(string responseText)

        {

            if (responseText.StartsWith("response_error:"))

            {

                return responseText.TrimStart("response_error:".ToCharArray());

            }

            return responseText;

        }

    }

登陆验证参考：

HttpClient httpClient = new HttpClient();

httpClient.Url = "http://192.168.66.60/k3cloud/Kingdee.BOS.WebApi.ServicesStub.AuthService.ValidateUser.common.kdsvc";

List