# 腾讯文档 API 404 问题诊断与修复
## 问题现象
调用腾讯文档 API 时返回 404 Not Found 错误：
```
Caused by: java.lang.RuntimeException: 请求被代理拦截，返回了HTML页面。请检查系统代理设置或网络配置。响应: 404 Not Found404 Not Found
nginx
```
## 可能的原因分析
### 1. API 基础 URL 可能不正确
我们当前使用的基础 URL 是：`https://docs.qq.com/openapi/v3`
但根据腾讯文档API的文档路径结构，可能的正确基础 URL 有以下几种：
| 候选URL | 说明 |
|---------|------|
| `https://docs.qq.com/open/api/v3` | 推测1：/open/api/v3 |
| `https://docs.qq.com/openapi/v3` | 推测2：/openapi/v3（当前使用）|
| `https://docs.qq.com/v3` | 推测3：直接 /v3 |
| `https://api.docs.qq.com/v3` | 推测4：使用 api 子域名 |
### 2. 可能需要使用不同的接口路径
腾讯文档 V3 API 可能不支持直接的 REST 风格的 ranges 路径，而是使用：
- **批量更新接口（batchUpdate）**：用于写入数据
- **批量查询接口（getGridData 或类似）**：用于读取数据
## 诊断步骤
### 步骤1：测试不同的基础 URL
建议创建一个测试方法，尝试不同的基础URL：
```java
// 测试代码示例
public void testApiBaseUrls() {
String[] candidateUrls = {
"https://docs.qq.com/open/api/v3",
"https://docs.qq.com/openapi/v3",
"https://docs.qq.com/v3",
"https://api.docs.qq.com/v3"
};
for (String baseUrl : candidateUrls) {
try {
String testUrl = baseUrl + "/spreadsheets/{fileId}";
log.info("测试URL: {}", testUrl);
// 发送GET请求测试
JSONObject result = callApi(accessToken, testUrl, "GET", null);
log.info("成功！正确的基础URL是: {}", baseUrl);
return;
} catch (Exception e) {
log.warn("URL {} 失败: {}", baseUrl, e.getMessage());
}
}
}
```
### 步骤2：检查腾讯文档开放平台的实际API文档
访问以下链接查看实际的API调用示例：
1. 腾讯文档开放平台首页：https://docs.qq.com/open/
2. 开发文档总览：https://docs.qq.com/open/document/app/
3. 查找实际的API调用示例（cURL命令或SDK示例）
### 步骤3：检查是否需要使用 batchUpdate 接口
如果直接的 ranges 路径不可用，可能需要使用批量操作接口：
**读取数据**可能需要使用类似的接口：
- POST `/open/api/v3/spreadsheets/{fileId}:getGridData`
- 或 POST `/open/api/v3/spreadsheets/{fileId}/values:batchGet`
**写入数据**可能需要使用：
- POST `/open/api/v3/spreadsheets/{fileId}:batchUpdate`
- 或 POST `/open/api/v3/spreadsheets/{fileId}/values:batchUpdate`
## 临时解决方案
### 方案1：修改基础URL为 /open/api/v3
尝试修改配置：
```yaml
# application-dev.yml 和 application-prod.yml
tencent:
doc:
api-base-url: https://docs.qq.com/open/api/v3
```
```java
// TencentDocConfig.java
private String apiBaseUrl = "https://docs.qq.com/open/api/v3";
```
### 方案2：联系腾讯文档技术支持
由于官方文档可能没有详细的API调用示例，建议：
1. 在腾讯文档开放平台提交工单
2. 咨询实际的API基础URL和调用方式
3. 获取完整的API调用示例代码
## 后续行动
1. 首先尝试修改基础URL为 `/open/api/v3`
2. 如果仍然404，需要查看腾讯文档开放平台控制台的SDK示例或API文档
3. 考虑使用腾讯文档提供的官方SDK（如果有）
4. 联系腾讯文档技术支持获取准确的API地址
## 参考信息
- 文档页面路径：`/open/document/app/openapi/v3/...`（这是文档站点）
- 可能的API路径：`/open/api/v3/...`（这可能是实际API）
- 当前使用路径：`/openapi/v3/...`（返回404）
---
**更新时间**：2025-11-05
**状态**：待测试验证