.NetCore对接各大财务软件凭证API——金蝶系列（2）

一.前言

今天我们来分析金蝶系列的第二个产品---K3wise，财务版本为15.0.不过好像14.3以上的K3wise就有专门的开放API接口了，这对于我们这些做对接开发的也是一种福利了。
曾经对接过14.2版本的k3wise，当时走的是WebService，过程也是够心塞。最近听说14.2的客户准备转金蝶K3Cloud了。但是我们的重点是15.0开放API接口的处理了。那么，对接开发API接口的第一步就是开发文档了，当时也是在金蝶社区看到不少小伙伴问为啥不见K3wise的开发文档，开发文档在财务系统的EBDI-->API平台-->API说明
如下图所示：

二.K3wise财务环境API接口补丁

2.1.接口API补丁

确保对接的客户所使用的财务环境的API接口已经打过补丁，且补丁已打全。当时就是因为客户的财务环境没有打补丁，导致财务对接凭证时科目、凭证各种问题不断，为了保证开发过程财务环境不会有大问题，请确保补丁打全。

凭证引出如果出现如下图所示的返回参数，说明补丁已经是最新的，如果不是，请在金蝶社区的补丁下载专区下载补丁https://club.kingdee.com/club/newclub/patch/list?productType=%E9%87%91%E8%9D%B6K/3

2.2所需补丁列表

请确保下载的补丁版本为自己所使用的k3wise的财务版本

补丁号：PT122970 ---增加缺少的API单据接口，包括：投料单,生产任务单,BOM单,工序计划单,生产任务汇报,工序汇报单,工艺路线,工序派工单,工序转移单,发货通知单,凭证,调拨单,其他出库单,其他入库单,退货通知单,收料通知/请检单,料通知单,盘盈入库,盘亏毁损单，客户上级组、物料上级组、部门上级组等等。
我们主要用到凭证接口--来进行凭证引入引出的操作。

补丁号 : PT125666 ---完善科目API接口，处理科目核算项目
该补丁用来解决科目API查询时，正确返回科目的辅助核算项。

补丁号 : PT127053 ---API科目GetList接口没有按照过滤条件返回数据
该补丁用来解决科目API列表查询时，过滤条件Filter不起作用。

补丁号 : PT134851---科目、部门、计量单位、仓位、自定义核算项目等基础资料API接口完善

三.K3wise对接所需参数以及接口列表

3.1Token的获取

在调用业务接口之前，我们需要先调用Token接口正确获取到Token，接着使用该Token去调用其他的业务接口，正确操作数据。
Token获取的请求示例：
http://127.0.0.1/K3API/Token/Create?authorityCode=635e8cd049f1407d0668651d54c90e8696e0ef1e98094961
其中authorityCode 授权码如何获取呢？

代码示例：

    private static long? timestamp;
        private const long MILLISECONDS_EXPIRED = 3300000; //1000 * 60 * 60  - 1000 * 60 * 5 (55分钟);
        private static string token = String.Empty;
  
  public string GetToken()
        {
            long nowTimestamp = (long)DateTime.Now.Subtract(DateTime.Parse("1970-1-1")).TotalMilliseconds;
            if ((timestamp == null)
                || (nowTimestamp - timestamp > MILLISECONDS_EXPIRED))
            {
                var result = APIClient.CreateAPIOperation<GetToken>(_Config.URL)
                 .SetAuthorityCode(_Config.AuthorityCode)
                 .ToAPIRequest().GetToken<GetTokenResult>();
                if (result != null && result.StatusCode == 200)
                {
                    timestamp = (long)DateTime.Now.Subtract(DateTime.Parse("1970-1-1")).TotalMilliseconds;
                    token = result.Data.Token;
                }
            }
            return token;

得到授权码后我们就可以正确调用该Token接口了，看一下正确返回的Token

{
  "StatusCode": 200,
  "Message": "Token申请成功!",
  "Data": {
    "AcctID": 2,
    "UserID": 16394,
    "Token": "4CB9FA43B24FFE35DEB4AC14FC2903421182845FC6F634B9B0661FF924E154EB346C18446F7A514D",
    "Code": "001",
    "Validity": 3600.0,
    "IPAddress": "1.196.178.5",
    "Language": "CHS",
    "Create": "2020-05-14 11:00:21"
  }
}

3.2调用业务接口

得到上面的Token后，我们就可以来调用业务接口返回数据了，我们以科目为例，来看一下如何获取科目列表

请求示例： http://127.0.0.1/K3API/Account/GetList?token=63FD9BBF16FC2C343D708CEA56157C1861945458A7E95B1D4838FFC120BBB0F1A2304662E019DF94

请求参数：

{
	"Data": {
		"Top": "100",
		"PageSize": "10",
		"PageIndex": "1",
		"Filter": "FNumber like '%003%' ",
		"OrderBy": "FNumber asc",
		"Fields": "FNumber,FName"
	}
}

返回参数：

{
  "StatusCode": 200,
  "Message": "Success",
  "Data": {
    "ROWCOUNT": 0,
    "PAGESIZE": 10,
    "PAGEINDEX": 1,
    "DATA": null
  }
}

我们要获取的字段为科目名称，科目编码，是否末级科目，科目全称等信息。如下代码所示

        public List<AccountListModel> GetAccountList()
        {
            var tokenStr = GetToken();
            var result = APIClient.CreateAPIOperation<GetList>(_Config.URL)
              .SetObjectTypeId(OrderTypeIDConsts.科目)
              .SetToken(tokenStr)
              .AddFieldKey("FName")
              .AddFieldKey("FNumber")
              .AddFieldKey("FDetail")
              .AddFieldKey("FFullName")
              .ToAPIRequest().Excute<GetListResult>();
            var list = new List<AccountListModel>();
            if (result.StatusCode == 200)
            {
                list = JsonConvert.DeserializeObject<List<AccountListModel>>(result.Data.DATA.ToString());
                list.ForEach(t =>
                {
                    t.FItemDetailName = t.FAccountItem == null ? "" : string.Join(",", t.FAccountItem.Select(x => x.FItemClassName).Distinct().ToList());
                });
            }
            return list;
        }

3.3 凭证接口

凭证引入

请求示例：

http://127.0.0.1/K3API/VoucherData/UpdateVoucher?token=63FD9BBF16FC2C343D708CEA56157C1861945458A7E95B1D4838FFC120BBB0F1A2304662E019DF94

请求参数：

{
  "Replace": "false",
  "VoucherData": {
    "Entries": [
      {
        "FAccountName": "管经理现金",
        "FAccountNumber": "1001.01",
        "FAmount": 500,
        "FAmountFor": 500,
        "FCurrencyName": "人民币",
        "FCurrencyNumber": "RMB",
        "FDC": 1,
        "FEntryID": 1,
        "FExchangeRate": 1,
        "FExplanation": "test_s1",
        "FMeasureUnit": null,
        "FMeasureUnitUUID": 621,
        "FQuantity": 50,
        "FSettleNo": null,
        "FSettleTypeName": "",
        "FTransNo": "",
        "FUnitPrice": 10
      },
      {
        "FAccountName": "应收股利",
        "FAccountNumber": "1131",
        "FAmount": 500,
        "FAmountFor": 500,
        "FCurrencyName": "人民币",
        "FCurrencyNumber": "RMB",
        "FDC": 0,
        "FEntryID": 0,
        "FExchangeRate": 1,
        "FExplanation": "test97_s1",
        "FMeasureUnit": null,
        "FMeasureUnitUUID": 279,
        "FQuantity": 50,
        "FSettleNo": null,
        "FSettleTypeName": "",
        "FTransNo": "",
        "FUnitPrice": 10
      }
    ],
    "FAttachments": 0,
    "FCashier": "NONE",
    "FDate": "2018-01-31",
    "FExplanation": "66666",
    "FGroup": "记",
    "FHandler": "",
    "FNumber": 19,
    "FPeriod": 1,
    "FPoster": "NONE",
    "FPreparer": "Administrator",
    "FReference": "",
    "FSerialNum": 2,
    "FTransDate": "2018-01-31",
    "FYear": 2018
  }
}

Replace为true表示修改，此时FVoucherID必传，为要修改的凭证ID；false表示新增

  public SaveVoucherResult UpdateVoucher(object model, string IsReplace)
        {
            var tokenStr = GetToken();
            var result = APIClient.CreateAPIOperation<UpdateVoucher>(_Config.URL)
            .SetObjectTypeId<UpdateVoucher>(OrderTypeIDConsts.凭证)
            .SetToken(tokenStr)
           .SetModel(model)
           .SetReplace(IsReplace)
            .ToAPIRequest().Excute<SaveVoucherResult>();
            return result;
        }

四.源码下载

此部分的代码封装逻辑思路和K3Cloud的处理大致一致，通过APIClient的调用来处理各个接口的逻辑。

源码下载：k3wise15.0源码下载
微信搜索【程序猿贝塔】回复“金蝶” 即可获取金蝶系列文章中的源代码