K3Cloud WebAPI 接口说明书_V2.0
修改记录
Ver. No |
发版日期 |
编制人 |
批准人 |
修改的章节号 |
V1.0 |
2016/8/9 |
|
|
初始版本 |
V2.0 |
2017/1/19 |
附录6 |
||
目 录
4.1.1. Kingdee.BOS.WebApi.FormService.dll
4.1.2. Kingdee.BOS.WebApi.ServicesStub.dll
4.1.3. Kingdee.BOS.WebApi.Client.dll
为异构系统访问K/3Cloud系统数据提供通用的接口。
当企业规模逐渐增大时,作为支撑业务运营的IT建设也变得越来越重要,不过往往企业的IT建设过程中会发现某一家软件供应商基本不能完全覆盖企业所有的业务运营流程,这样的结果就是,企业上的IT系统很多很全,从ERP到HR、CRM、PDM、OA等,貌似所有的业务都覆盖到了,但实际上因为这些系统的不集成,而形成了企业很多新的信息孤岛,非常不利于企业的后续的管理和战略发展。K/3Cloud从现今和往后的发展趋势来看,也不可避免会遇到上述问题,毕竟企业经营的多样化,并不是所有的业务都能在K/3Cloud中完成,所以我们必须在产品架构上支持更好的与外部系统进行协同。
-
- 适用版本:V5.0和后续版本
本文档适用于:
- 开发工程师:参考,对系统集成的实现获取全局性的设计指导。
愿景 |
关注点 |
描述与示例 |
目标:
- 提供对K/3Cloud单据和基础信息的查看、保存、提交、审核、反审核和删除等功能;
- 提供对K/3Cloud单据和基础信息的查询功能;
约束:
- 数据操作接口仅支持以基础资料编码、单据编号或直接以表单主键去操作数据;
- 支持对某一具体单据的数据查询,但多单关联查询需要二开接口实现。
K/3 Cloud WebAPI是一种轻量级的、可维护的、可伸缩的 Web 服务。采用HTTP+JSON,也就是用RESTful的方式来开发。使用.NET Framework 4.0为开发平台,源代码使用C#编写。整个框架由三个组装件组成。
此组装件包含WebAPI主要接口的功能实现。部署在应用层服务器。
此组装件主要包含WebAPI接口定义,扩展接口定义以及登陆验证接口。部署在应用层服务器。
此组装件为WebAPI的客户端组件,封装了一些在异构系统客户端访问WebAPI的方法,适用于C#程序调用。由于它应用于异构系统客户端,所以此组装件需要拷贝到异构系统客户端环境中。非C#程序调用可以不用拷贝。
.Net FrameWork 4.0
Microsoft Visual Studio 2012
服务地址:
http://ServerIp/K3Cloud/Kingdee.BOS.WebApi.ServicesStub.AuthService.ValidateUser.common.kdsvc
接口参数:
参数列表 |
参数含义 |
备注 |
acctID |
账套Id,从管理中心数据库查询获得 |
必须 |
username |
用户登陆名 |
必须 |
password |
密码 |
必须 |
lcid |
语言id,选择哪种语言访问,参考:中文2052,英文1033,繁体3076 |
非必须,引用SDK组件辅助类调用则必须 |
返回参数:
参数列表 |
参数含义 |
备注 |
LoginResultType |
//激活 |
管理员登陆可能出现返回-5的情况,这种情况在api验证时也可认为是允许的,具体可以根据实际情况来定。 var result = JObject.Parse(ret)["LoginResultType"].Value<int>(); |
调用参考:
- 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:登陆成功处理业务
}
- 无引用组件示例(不引用金蝶的组件):
说明:以下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
{
/// <summary>
/// Seivice URL
/// </summary>
public string Url { get; set; }
/// <summary>
/// 内容
/// </summary>
public string Content { get; set; }
/// <summary>
/// Cookie,保证登录后,所有访问持有一个Cookie;
/// </summary>
static CookieContainer Cookie = new CookieContainer();
/// <summary>
/// HTTP访问
/// </summary>
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<object> Parameters = new List<object>();
Parameters.Add("558cbb01bfc79b");//帐套Id
Parameters.Add("Administrator");//用户名
Parameters.Add("888888");//密码
Parameters.Add(2052);
httpClient.Content = JsonConvert.SerializeObject(Parameters);
var iResult = JObject.Parse(httpClient.AsyncRequest())["LoginResultType"].Value<int>();
if (iResult == 1){
//todo:验证成功,处理业务
}
服务地址:
http://ServerIp/K3Cloud/Kingdee.BOS.WebApi.ServicesStub.DynamicFormService.View.common.kdsvc
接口参数:
参数列表 |
参数含义 |
备注 |
formid |
表单Id,格式参考:"IV_SALESIC"//表示发票 |
必须 |
data |
数据包,Number表示单据编号或者基础资料编码,Id为主键,CreateOrgId为创建组织Id。格式参考:"{\"CreateOrgId\":0,\"Id\":0,\"Number\":\"SVINV00000003\"}" |
CreateOrgId:非必须 |
返回参数:
参数列表 |
参数含义 |
备注 |
ResponseStatus |
操作状态 |
操作是否成功,如果失败,具体失败原因 |
Result |
单据数据包 |
单据完整数据内容 |
调用参考:
- SDK辅助类示例(引用Kingdee.BOS.WebAPI.Client.dll):
string sJson = "{\"Number\":\"SVINV00000003\"}";
var result = client.Execute<string>("Kingdee.BOS.WebApi.ServicesStub.DynamicFormService.View",
new object[] { "IV_SALESIC", sJson });
- 无引用组件示例(不引用金蝶的组件):
HttpClient httpClient = new HttpClient();
httpClient.Url = "http://192.168.66.60/k3cloud/Kingdee.BOS.WebApi.ServicesStub.DynamicFormService.View.common.kdsvc";
List<object> Parameters = new List<object>();
//业务对象Id
String formid = "IV_SALESIC";//发票
Parameters.Add(formid);
//Json字串
string data = "{\"Number\":\"SVINV00000003\"}";
Parameters.Add(data);
httpClient.Content = JsonConvert.SerializeObject(Parameters);
var result = httpClient.AsyncRequest();
服务地址:
http://ServerIp/K3Cloud/Kingdee.BOS.WebApi.ServicesStub.DynamicFormService.Save.common.kdsvc
接口参数:
参数列表 |
参数含义 |
备注 |
formid |
表单Id,格式参考:"BD_Currency"//表示币别 |
必须 |
data |
数据包,数据格式参考以币别为例:"{\"Creator\":\"\", |
Creator:非必须 |
返回参数:
参数列表 |
参数含义 |
备注 |
ResponseStatus |
操作状态 "IsSuccess":false, "Errors":[{"FieldName":"", "Message":"","DIndex":0}], "SuccessEntitys":[{"Id":"","Number":"","DIndex":0}], "SuccessMessages":[{"FieldName":"","Message":"","DIndex":0}]} |
IsSuccess:操作是否成功, |
调用参考:
1)SDK辅助类示例(引用Kingdee.BOS.WebAPI.Client.dll):
//业务对象Id
string sFormId = "SAL_OUTSTOCK"; //销售出库单
//Model字串
string sContent = "{\"Creator\":\"\",\"NeedUpDateFields\":[],\"Model\":" + "{\"FID\":\"0\",\"FStockOrgId\":{\"FNumber\":\"210\"},\"FBillTypeID\":{\"FNumber\":\"XSCKD01_SYS\"},\"FBillNo\":\"CSDGBC21002\",\"FCustomerID\":{\"FNumber\":\"CUST0073\"},\"SubHeadEntity\":{\"FExchangeRate\":6.51},\"FEntity\":[{\"FEntryID\":\"0\",\"FMATERIALID\":{\"FNumber\":\"03.001\"},\"FStockID\":{\"FNumber\":\"CK002\"},\"FRealQty\":324,\"FBaseUnitQty\":324},{\"FEntryID\":\"0\",\"FMATERIALID\":{\"FNumber\":\"03.001\"},\"FStockID\":{\"FNumber\":\"CK004\"},\"FRealQty\":220,\"FBaseUnitQty\":220}]]}}";
object[] saveInfo = new object[]
{
sFormId,
sContent
};
//调用保存接口
var ret = client.Execute<string>("Kingdee.BOS.WebApi.ServicesStub.DynamicFormService.Save", saveInfo);
以下示例说明如何更新单据的表体信息:
更新内码为100017的单据,新增两行表体数据,原有100024和100025行数据保留,如果源单中还有其他分录则删除。
string sFormId = "STK_MISCELLANEOUS";//其他入库单
string sContent = "{\"Creator\":\"\",\"NeedUpDateFields\":[],\"Model\":{\"FID\":\"100017\",\"FEntity\":[{\"FEntryID\":\"100024\"},{\"FEntryID\":\"100025\"}," + "{\"FMATERIALID\":{\"FNumber\":\"A.0060480933\"},\"FUnitID\":{\"FNumber\":\"03\"},\"FSTOCKID\":{\"FNumber\":\"PRTSH\"},\"FQty\":\"200\",\"FBASEQTY\":\"200\",\"FPlanAmount\":\"132856\",\"FBASEUNITID\":{\"FNumber\":\"03\"},\"FEntryNOTE\":\"2015-7-29\",\"FAmount\":\"132856\",\"FPRICE\":\"664.28\",\"FEntrySelfA9725\":\"2015072802\",\"FEntrySelfA9733\":\"19881\",\"FEntrySelfA9734\":\"2015-6-3\",\"FEntrySelfA9737\":\"200\",\"FEntrySelfA9740\":\"0\",\"FEntrySelfA9738\":\"1\",\"FEntrySelfA9739\":\"2\",\"FEntrySelfA9735\":\"664.28\"}," +
"{\"FMATERIALID\":{\"FNumber\":\"A.0060480933"},\"FUnitID\":{\"FNumber\":\"03\"},\"FSTOCKID\":{\"FNumber\":\"PRTSH\"},\"FQty\":\"200\",\"FBASEQTY\":\"200\",\"FPlanAmount\":\"132856\",\"FBASEUNITID\":{\"FNumber\":\"03\"},\"FEntryNOTE\":\"2015-7-29\",\"FAmount\":\"132856\",\"FPRICE\":\"664.28\",\"FEntrySelfA9725\":\"2015072802\",\"FEntrySelfA9733\":\"19881\",\"FEntrySelfA9734\":\"2015-6-3\",\"FEntrySelfA9737\":\"200\",\"FEntrySelfA9740\":\"0\",\"FEntrySelfA9738\":\"1\",\"FEntrySelfA9739\":\"2\",\"FEntrySelfA9735\":\"664.28\"}]}}";
object[] saveInfo = new object[]
{
sFormId,
sContent
};
//调用保存接口
var ret=
client.Execute<string>("Kingdee.BOS.WebApi.ServicesStub.DynamicFormService.Save", saveInfo);
2)无引用组件示例(不引用金蝶的组件):
HttpClient httpClient = new HttpClient();
httpClient.Url = "http://192.168.66.60/k3cloud/Kingdee.BOS.WebApi.ServicesStub.DynamicFormService.Save.common.kdsvc";
List<object> Parameters = new List<object>();
//业务对象Id
String formid = "SAL_OUTSTOCK";//销售出库为例
Parameters.Add(formid);
//Json字串
string data = "{\"Creator\":\"\",\"NeedUpDateFields\":[],\"Model\":" + "{\"FID\":\"0\",\"FStockOrgId\":{\"FNumber\":\"210\"},\"FBillTypeID\":{\"FNumber\":\"XSCKD01_SYS\"},\"FBillNo\":\"CSDGBC21002\",\"FCustomerID\":{\"FNumber\":\"CUST0073\"},\"SubHeadEntity\":{\"FExchangeRate\":6.51},\"FEntity\":[{\"FEntryID\":\"0\",\"FMATERIALID\":{\"FNumber\":\"03.001\"},\"FStockID\":{\"FNumber\":\"CK002\"},\"FRealQty\":324,\"FBaseUnitQty\":324},{\"FEntryID\":\"0\",\"FMATERIALID\":{\"FNumber\":\"03.001\"},\"FStockID\":{\"FNumber\":\"CK004\"},\"FRealQty\":220,\"FBaseUnitQty\":220}]]}}";
Parameters.Add(data);
httpClient.Content = JsonConvert.SerializeObject(Parameters);
var result = httpClient.AsyncRequest();
服务地址:
http://ServerIp/K3Cloud/Kingdee.BOS.WebApi.ServicesStub.DynamicFormService.BatchSave.common.kdsvc
接口参数:
参数列表 |
参数含义 |
备注 |
formid |
表单Id,格式参考:"SAL_SaleOrder"//表示销售订单 |
必须 |
data |
数据包,格式参考以销售订单为例: "{\"NeedUpDateFields\":[],\"BatchCount\":\"2\", \"Model\":[{\"FID\":\"0\",\"FBILLTYP |