# K3Cloud WebAPI 协议要点

> 需要 URL/JSON 示例、参数表时读本文。工作流与索引见 [SKILL.md](../SKILL.md)。

## 传输与会话

- HTTP POST，`Content-Type: application/json`
- URL：`{server_url}{ServiceName}.common.kdsvc`，`server_url` 以 `/k3cloud/` 结尾
- 请求体：JSON **数组**，参数顺序与服务方法签名一致
- 登录后响应 Header 带 `kdservice-sessionid`；**同一 HTTP 客户端 / Cookie 容器**复用于后续调用，否则会话过期

### 服务名前缀

| 类别 | 前缀 |
|------|------|
| 认证 | `Kingdee.BOS.WebApi.ServicesStub.AuthService.*` |
| 单据 | `Kingdee.BOS.WebApi.ServicesStub.DynamicFormService.*` |
| 查询 | `Kingdee.BOS.WebApi.ServicesStub.BusinessDataService.*` |

## 认证

**应用授权（第三方推荐）** `LoginByAppSecret`：参数 `[acct_id, app_id, app_secret, lcid]`（lcid 2052=简体中文）

**账号密码** `ValidateUser`：`[acct_id, user_name, password, lcid]`

配置项：`server_url`、`acct_id`；`app_id`+`app_secret` 或 `user_name`+`password` 二选一。密钥只存安全配置，不进日志。

流程示例：[assets/snippets/LoginFlow.md](../assets/snippets/LoginFlow.md)

## 核心操作（DynamicFormService / BusinessDataService）

| 操作 | 服务方法 | 说明 |
|------|----------|------|
| ExecuteBillQuery | BusinessDataService | 返回二维数组；`FormId`、`FieldKeys`、`FilterString`、分页 |
| View | DynamicFormService | 整单数据包 |
| Save | DynamicFormService | 仅保存不审；`Model` 内 `FID=0` 新建 |
| Delete / Submit / Audit / UnAudit | DynamicFormService | `Numbers` 或 `Ids` |
| Push | DynamicFormService | `Ids`、`RuleId`、可选 `TargetFormId` |
| ExcuteOperation | DynamicFormService | 第三参为操作编码 |

`FormId` 是表单标识不是物理表名。基础资料引用用 `{"FNumber":"..."}`。

`FDocumentStatus`：`A` 暂存、`B` 提交、`C` 审核、`D` 工作流/重新审核。

Save/Query/下推的 JSON 示例见 [assets/snippets/SaveSubmitAuditFlow.md](../assets/snippets/SaveSubmitAuditFlow.md)、[QueryPagingFlow.md](../assets/snippets/QueryPagingFlow.md)、[PushFlow.md](../assets/snippets/PushFlow.md)。

## 响应

- **查询**：解析为二维数组
- **操作**：`Result.ResponseStatus.IsSuccess`、`Errors`、`SuccessEntitys`；部分 SDK 键名大小写不一致，解析时兼容
- **登录**：`LoginResultType === 1` 为成功

## 典型流程（摘要）

- 新建：登录 → Save → Submit → Audit
- 修改：UnAudit（若已审）→ Save（`IsDeleteEntry` 按需）→ Submit → Audit
- 下推：源单状态 C → Push → View/Save 目标单
- 分页同步：ExecuteBillQuery 循环 `StartRow`/`Limit`

销售链 Save Model、Push RuleId 见 [form-id-catalog.md](form-id-catalog.md)、[push-rules-catalog.md](push-rules-catalog.md) 与 `assets/snippets/Sal*.md` 等。

## 高级操作

分配、工作流审批、QueryBusinessInfo、报表等见 [advanced-operations.md](advanced-operations.md)。

## 多语言实现

见 [language-implementations.md](language-implementations.md)（SDK 与裸 HTTP）。