Dingtalk Document

# dingtalk-document API 参考

> 所有接口均已验证可用。
> `NEW_TOKEN` = 新版 token（`api.dingtalk.com` 用），获取方式 `bash scripts/dt_helper.sh --token`
> `OPERATOR_ID` = 用户 unionId，获取方式 `bash scripts/dt_helper.sh --get DINGTALK_MY_OPERATOR_ID`
> ⚠️ **重要**：所有接口均需传 `operatorId`（unionId），缺少则返回 `MissingoperatorId` 错误。

---

## 1. 查询知识库列表

```
GET https://api.dingtalk.com/v2.0/wiki/workspaces?operatorId={OPERATOR_ID}&maxResults=20&nextToken=
Header: x-acs-dingtalk-access-token: {NEW_TOKEN}
```

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `operatorId` | string | ✅ | 用户 unionId |
| `maxResults` | int | ❌ | 每页数量，默认 20 |
| `nextToken` | string | ❌ | 分页令牌，首次为空 |

响应：
```json
{
  "workspaces": [
    {
      "workspaceId": "QXvd5SLN2AxOQz0Z",
      "name": "团队知识库",
      "description": "...",
      "rootNodeId": "P0MALyR8kl3qpB7qTkM1xn3mW3bzYmDO",
      "type": "TEAM",
      "url": "https://alidocs.dingtalk.com/i/spaces/.../overview",
      "createTime": "2024-01-01T00:00Z",
      "modifiedTime": "2024-06-01T00:00Z"
    }
  ],
  "nextToken": "..."
}
```

> 翻页：`nextToken` 非空时传入下次请求继续获取。

---

## 2. 查询知识库信息

```
GET https://api.dingtalk.com/v2.0/wiki/workspaces/{workspaceId}?operatorId={OPERATOR_ID}
Header: x-acs-dingtalk-access-token: {NEW_TOKEN}
```

响应：单个 workspace 对象（结构同列表项）

---

## 3. 查询节点列表

```
GET https://api.dingtalk.com/v2.0/wiki/nodes?parentNodeId={nodeId}&operatorId={OPERATOR_ID}&maxResults=50&nextToken=
Header: x-acs-dingtalk-access-token: {NEW_TOKEN}
```

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `parentNodeId` | string | ✅ | 父节点 ID，传知识库的 `rootNodeId` 可列出顶层内容 |
| `operatorId` | string | ✅ | 用户 unionId |
| `maxResults` | int | ❌ | 每页数量，默认 20 |
| `nextToken` | string | ❌ | 分页令牌 |

响应：
```json
{
  "nodes": [
    {
      "nodeId": "LeBq413JAw31yaz1fB0BBdLGWDOnGvpb",
      "name": "使用文档.adoc",
      "type": "FILE",
      "category": "ALIDOC",
      "extension": "adoc",
      "workspaceId": "QXvd5SnBnzmZdZ0Z",
      "url": "https://alidocs.dingtalk.com/i/nodes/...",
      "createTime": "2026-03-04T16:58Z",
      "modifiedTime": "2026-03-04T17:51Z"
    }
  ],
  "nextToken": "..."
}
```

> `type`：`FILE`（文档/文件）| `FOLDER`（文件夹）

---

## 4. 查询单个节点

```
GET https://api.dingtalk.com/v2.0/wiki/nodes/{nodeId}?operatorId={OPERATOR_ID}
Header: x-acs-dingtalk-access-token: {NEW_TOKEN}
```

响应：`{ "node": { nodeId, name, type, category, workspaceId, url, ... } }`

---

## 5. 通过 URL 查询节点

```
POST https://api.dingtalk.com/v2.0/wiki/nodes/queryByUrl?operatorId={OPERATOR_ID}
Header: x-acs-dingtalk-access-token: {NEW_TOKEN}
```

请求体：
```json
{
  "url": "https://alidocs.dingtalk.com/i/nodes/<nodeId>",
  "operatorId": "{OPERATOR_ID}"
}
```

响应：与 GET 单个节点相同的 node 结构。

---

## 6. 创建文档

```
POST https://api.dingtalk.com/v1.0/doc/workspaces/{workspaceId}/docs
Header: x-acs-dingtalk-access-token: {NEW_TOKEN}
```

请求体：
```json
{
  "operatorId": "{OPERATOR_ID}",
  "docType": "DOC",
  "name": "文档标题"
}
```

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `operatorId` | string | ✅ | 用户 unionId |
| `docType` | string | ✅ | 固定填 `"DOC"`（ALIDOC 富文本格式） |
| `name` | string | ✅ | 文档标题 |

响应：
```json
{
  "dentryUuid": "aaa",
  "nodeId": "xxx",
  "docKey": "yyy",
  "workspaceId": "zzz",
  "url": "https://..."
}
```

> **重要**：
> - `docKey` / `dentryUuid`：用于 `/v1.0/doc/suites/documents/{id}` 内容读写
> - `nodeId`：用于 `/v1.0/doc/workspaces/{workspaceId}/docs/{nodeId}` 删除/管理

---

## 7. 删除文档

```
DELETE https://api.dingtalk.com/v1.0/doc/workspaces/{workspaceId}/docs/{nodeId}?operatorId={OPERATOR_ID}
Header: x-acs-dingtalk-access-token: {NEW_TOKEN}
```

> `workspaceId` 和 `nodeId` 均使用创建文档响应中的值。成功返回 `200 {}`。

---

## 8. 读取文档内容（Block 结构）

```
GET https://api.dingtalk.com/v1.0/doc/suites/documents/{docKey}/blocks?operatorId={OPERATOR_ID}
Header: x-acs-dingtalk-access-token: {NEW_TOKEN}
```

> **docKey 的来源**：
> - 通过 wiki nodes 接口查到的 `nodeId` 本质是 `dentryUuid`，可直接用于正文读写
> - 通过创建文档接口新建的文档：可使用响应中的 `docKey` 或 `dentryUuid`
> - 创建响应中的 `nodeId`（通常出现在 `/docs/<nodeId>` 链接中）不能直接用于正文读写

响应：
```json
{
  "result": {
    "data":