# 企微微盘/文档 API 开通与使用

> 来源：
> - 微盘概述：https://developer.work.weixin.qq.com/document/path/93654
> - 文档概述：https://developer.work.weixin.qq.com/document/path/97392
> 验证时间：2026-06-22

## 开通流程

两个 API **分开配置**，都是自建应用需先加入「可调用接口的应用」列表：

```
微盘：管理后台 →「协作」→「微盘」→「API」→ 勾选自建应用
文档：管理后台 →「协作」→「文档」→「API」→ 勾选自建应用
```

> ⚠️ 不在「应用管理」里。不在「自建应用」→「接口权限」里。都在「协作」菜单下。

## API 调用流程

```
# 1. 获取 token（两个 API 共用）
GET /cgi-bin/gettoken?corpid={corpid}&corpsecret={corpsecret}
  → {"errcode":0, "access_token":"...", "expires_in":7200}

# 2. 调具体接口（token 放 query string）
POST /cgi-bin/wedoc/document/get?access_token={token}
POST /cgi-bin/wedrive/file_list?access_token={token}
```

## 文档 API (wedoc) 完整端点

### 管理文档
| 接口 | 端点 | 文档 path | 「仅限应用自己创建」 |
|------|------|-----------|:---:|
| 新建文档 | `POST /cgi-bin/wedoc/create_doc` | — | N/A |
| 获取文档基础信息 | `POST /cgi-bin/wedoc/get_doc_base_info` | 97743 | ❌ |
| 分享文档 | `POST /cgi-bin/wedoc/doc_share` | 97733 | ✅ |
| 重命名文档 | `POST /cgi-bin/wedoc/rename_doc` | 97736 | ✅ |
| 删除文档 | `POST /cgi-bin/wedoc/del_doc` | 97735 | ✅ |

### 管理文档内容
| 接口 | 端点 | 文档 path | 「仅限应用自己创建」 |
|------|------|-----------|:---:|
| 编辑文档内容 | `POST /cgi-bin/wedoc/document/batch_update` | — | ✅ |
| **获取文档数据** | `POST /cgi-bin/wedoc/document/get` | **101161** | **❌ 未写** |

### 管理表格内容
| 接口 | 端点 | 「仅限应用自己创建」 |
|------|------|:---:|
| 编辑表格内容 | `POST /cgi-bin/wedoc/spreadsheet/batch_update` | ✅ |
| 获取表格数据 | `POST /cgi-bin/wedoc/spreadsheet/get_sheet` | 待验证 |

### 设置文档权限
| 接口 | 端点 |
|------|------|
| 获取文档权限信息 | `POST /cgi-bin/wedoc/doc_get_auth` |
| 修改文档成员与权限 | `POST /cgi-bin/wedoc/mod_doc_member` |

## 微盘 API (wedrive) 完整端点

### 管理空间
| 接口 | 端点 | 「仅限应用自己创建」 |
|------|------|:---:|
| 获取空间列表 | `POST /cgi-bin/wedrive/space_list` | 待验证 |
| 获取空间信息 | `POST /cgi-bin/wedrive/space_info` | 待验证 |

### 管理文件
| 接口 | 端点 | 文档 path | 「仅限应用自己创建」 |
|------|------|-----------|:---:|
| **获取文件列表** | `POST /cgi-bin/wedrive/file_list` | **93657** | **❌ 未写** |
| 下载文件 | `POST /cgi-bin/wedrive/file_download` | 97881 | 待验证 |
| 上传文件 | `POST /cgi-bin/wedrive/file_upload` | — | 待验证 |

## 权限粒度发现（2026-06-22）

官网概述页宣称「应用仅可读取和编辑自己创建的文档」，但**逐接口检查发现读操作和写操作的权限粒度不同**：

- **写操作**（分享/重命名/删除/编辑）→ 明确写了「只能访问该应用创建的文档」
- **读操作**（获取文档数据/获取文档基础信息/获取文件列表）→ **没有**这个限制

这意味着通过 API 读取已存在的企业文档和文件**理论上可行**，但需开通权限后实际验证。

## 错误排查

| errcode | 含义 | 排查 |
|---------|------|------|
| 0 | 成功 | — |
| 48002 | api forbidden | 自建应用未在「协作→微盘→API」或「协作→文档→API」中授权 |

## 测试命令

```bash
CORPID="your_corp_id"
CORPSECRET="your_secret"

# 获取 token
TOKEN=$(curl -s "https://qyapi.weixin.qq.com/cgi-bin/gettoken?corpid=$CORPID&corpsecret=$CORPSECRET" | python3 -c "import sys,json;print(json.load(sys.stdin)['access_token'])")

# 文档——获取基础信息（验证权限）
curl -s -X POST "https://qyapi.weixin.qq.com/cgi-bin/wedoc/get_doc_base_info?access_token=$TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"docid":"DOC_ID_FROM_URL"}'

# 文档——获取文档数据（读内容）
curl -s -X POST "https://qyapi.weixin.qq.com/cgi-bin/wedoc/document/get?access_token=$TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"docid":"DOC_ID_FROM_URL"}'

# 微盘——获取文件列表
curl -s -X POST "https://qyapi.weixin.qq.com/cgi-bin/wedrive/file_list?access_token=$TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"spaceid":"SPACE_ID","fatherid":"SPACE_ID","sort_type":5,"start":0,"limit":10}'
```

## 常见踩坑

1. **在应用管理里找权限** → 找不到。微盘和文档的权限入口都在「协作」菜单，是两个独立入口。
2. **48002 就折腾 token** → token 没问题，是应用没授权对应的 API。
3. **以为微盘和文档是同一个 API** → 微盘是 wedrive（文件/空间管理），文档是 wedoc（内容读写），两套不同的接口路径和开通入口。
4. **根据概述页推断所有接口都不能读** → 概述声明和单接口权限说明可能不一致，必须逐接口查文档。