# kingdee调用WebApi工具

**Repository Path**: dihl/kingdee.webapi.tool

## Basic Information

- **Project Name**: kingdee调用WebApi工具
- **Description**: 一个基于 WinForms 的桌面工具，用于快速调用金蝶云星空（K3 Cloud）WebAPI，方便在日常开发、联调、测试过程中调试第三方接口。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-08-07
- **Last Updated**: 2026-08-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 金蝶 K3 Cloud WebAPI 调用工具

一个基于 WinForms 的桌面工具，用于快速调用金蝶云星空（K3 Cloud）WebAPI，方便在日常开发、联调、测试过程中调试第三方接口。

## 解决的问题

在对接金蝶云星空第三方 WebAPI 时，通常需要反复地：

- 拼接并构造完整的 WebAPI 请求（登录鉴权、接口地址、JSON 参数等）
- 使用 Postman 等工具手动维护登录 Token，接口参数无法直接复用
- 查看接口返回的原始 JSON，排查参数格式问题

本工具将「第三方应用登录鉴权 + 接口调用 + 耗时统计」封装为一体，只需填写一次环境信息即可持续调试接口，主要解决：

1. **登录鉴权繁琐**：内置金蝶官方 SDK，自动完成 `LoginByAppSecret`（账密 + AppId/AppSec）登录流程，无需手动维护 Session。
2. **接口地址拼接**：只需输入接口标识（如 `ExecuteBillQuery`），工具自动补全 `.common.kdsvc` 后缀。
3. **参数调试困难**：直接粘贴接口 JSON 参数即可调用，返回结果与耗时一屏展示，便于定位问题。
4. **配置重复录入**：环境配置、输入参数、返回结果自动保存，下次启动自动回填。

## 环境要求

| 项目 | 要求 |
| ---- | ---- |
| 操作系统 | Windows（WinForms 桌面程序） |
| 开发环境 | Visual Studio 2022 |
| 运行时 | .NET 6.0 SDK / Runtime |
| 目标框架 | net6.0-windows |
| 第三方依赖 | 金蝶官方 SDK（`Kingdee.CDP.WebApi.SDK.dll`，位于 `resources` 目录） |
| NuGet 依赖 | Newtonsoft.Json 13.0.3 |

## 使用前提

在金蝶云星空服务器端完成以下配置，才能正常调用 WebAPI：

1. 在「管理后台 → 系统管理 → 第三方系统登录」中登记第三方应用，获取 **AppID** 与 **AppSec**。
2. 拥有可登录金蝶云的 **账号**（Name）及其密码对应账号体系，以及对应的 **账套 DbID**。
3. 确保服务器地址可通过网络访问（如 `http://host:port` 或完整云星空地址）。

## 编译运行

使用 Visual Studio 2022 打开解决方案 `调用WebApi工具.sln`：

1. 还原 NuGet 包（`Newtonsoft.Json` 等）。
2. 确认 `resources\Kingdee.CDP.WebApi.SDK.dll` 存在（若缺失需将金蝶官方 SDK 放入该目录）。
3. 直接运行（F5）或发布：

   - 项目右键 → **发布** → 选择 FolderProfile（已内置 `Properties\PublishProfiles\FolderProfile.pubxml`）。
   - 或在项目目录执行：

     ```bash
     dotnet publish -c Release -r win-x64
     ```

## 界面用法

### 1. 环境设置（左上区域）

| 字段 | 说明 |
| ---- | ---- |
| 地址 | 金蝶云星空服务器地址（`ThirdPassPortInfo.CloudUrl`） |
| DbID | 账套 ID（数据库标识） |
| 账号 | 登录金蝶云的账号 |
| AppID | 第三方应用 AppID |
| AppSec | 第三方应用 AppSec（密钥） |
| 语言ID | 语言编号，简体中文为 `2052`（默认值） |

### 2. 接口（右上区域）

| 字段 | 说明 |
| ---- | ---- |
| 接口地址 | 接口标识，如 `ExecuteBillQuery`、`Save`、`QueryBusinessInfo` 等。若未带 `.common.kdsvc` 后缀，执行时自动追加 |
| 执行 | 点击后先自动登录，再调用接口 |
| 耗时 | 接口调用耗时（毫秒） |

### 3. 输入参数（左下区域）

粘贴接口的 JSON 参数，例如 `ExecuteBillQuery`：

```json
{
  "FormId": "BD_MATERIAL",
  "FieldKeys": "FNumber,FName,FSpecification",
  "FilterString": "FForbidStatus = 'A'"
}
```

### 4. 返回结果（右下区域）

展示接口返回的原始 JSON。若未登录成功会提示「暂未登陆或者登陆失败」，接口异常会直接展示异常信息。

## 配置持久化

所有字段（环境设置、接口地址、输入参数、返回结果）在点击「执行」后自动保存到用户配置中（`App.config` 对应的 userSettings），下次启动自动回填，无需重复录入。

## 目录结构

```
kingdee调用WebApi工具/
├── 调用WebApi工具.sln                 # 解决方案
├── README.md
└── 调用WebApi工具/
    ├── Program.cs                    # 程序入口
    ├── MainFrame.cs                  # 主窗体逻辑
    ├── MainFrame.Designer.cs         # 界面布局
    ├── WebApiClient.cs               # 金蝶 WebAPI 封装（登录 + 执行）
    ├── App.config                    # 用户配置
    ├── resources/
    │   └── Kingdee.CDP.WebApi.SDK.dll  # 金蝶官方 SDK
    └── Properties/
        ├── Settings.settings         # 配置项定义
        └── PublishProfiles/          # 发布配置
```

## 核心调用流程

```
填写环境信息
    ↓
Init(url, dbid, name, appId, appSec, language)   # 初始化 K3CloudApi
    ↓
LoginByAppSecret(dbid, name, appId, appSec, language)  # 第三方应用登录
    ↓
Execute(execUrl, input)              # 执行接口，返回原始 JSON
    ↓
展示返回结果与耗时
```

> 说明：登录采用金蝶「账密 + AppId/AppSec」的第三方应用鉴权方式，具体接口地址与参数格式请参考金蝶官方 WebAPI 文档。