# 腾讯广告 API 读取测试报告

**测试时间**: 2026-04-15
**账户 ID**: 80769799
**API 版本**: v3.0
**测试结果**: ✅ 通过

---

## 1. 环境配置

### Access Token
- ✅ 已通过 API 获取: `378156a33230df87e2ef6c56f37c7b76`
- 获取接口: `https://api.piaoquantv.com/ad/put/tencent/getAccessToken?accountId=80769799`

### 配置文件
- 已更新 `.env` 文件，添加腾讯广告配置
- 配置项:
  ```bash
  TENCENT_AD_ACCESS_TOKEN=378156a33230df87e2ef6c56f37c7b76
  TENCENT_AD_ACCOUNT_ID=80769799
  TENCENT_AD_BASE_URL=https://api.e.qq.com/v3.0
  ```

---

## 2. 读取操作测试

### 2.1 广告列表查询 ✅

**测试接口**: `GET /v3.0/adgroups/get`

**测试结果**: 成功

**账户数据概览**:
- 广告总数: **3 个**
- 状态分布:
  - 暂停 (AD_STATUS_SUSPEND): 2 个
  - 投放中 (AD_STATUS_NORMAL): 1 个

---

## 3. 广告详细信息

### 广告 1: 4.8-公众号小程序+朋友圈-R50退休-45+女

| 字段 | 值 |
|------|-----|
| **广告 ID** | 93278936685 |
| **配置状态** | AD_STATUS_SUSPEND (已暂停) |
| **系统状态** | ADGROUP_STATUS_SUSPEND |
| **出价** | 0.42 元 |
| **日预算** | 不限 |
| **营销目标** | MARKETING_GOAL_USER_GROWTH (用户增长) |
| **优化目标** | OPTIMIZATIONGOAL_PROMOTION_VIEW_KEY_PAGE (关键页面浏览) |
| **投放时间** | 2026-04-15 ~ (长期) |
| **创建时间** | 2026-04-08 15:39:07 |

---

### 广告 2: 4.8-公众号小程序+朋友圈-R50退休-45+男

| 字段 | 值 |
|------|-----|
| **广告 ID** | 93276255271 |
| **配置状态** | AD_STATUS_SUSPEND (已暂停) |
| **系统状态** | ADGROUP_STATUS_SUSPEND |
| **出价** | 0.40 元 |
| **日预算** | 不限 |
| **营销目标** | MARKETING_GOAL_USER_GROWTH (用户增长) |
| **优化目标** | OPTIMIZATIONGOAL_PROMOTION_VIEW_KEY_PAGE (关键页面浏览) |
| **投放时间** | 2026-04-15 ~ (长期) |
| **创建时间** | 2026-04-08 15:31:57 |

---

### 广告 3: 4.8-公众号小程序+朋友圈-R50退休-60+男女 ⭐

| 字段 | 值 |
|------|-----|
| **广告 ID** | 93269884383 |
| **配置状态** | **AD_STATUS_NORMAL (投放中)** |
| **系统状态** | **ADGROUP_STATUS_ACTIVE** |
| **出价** | 0.40 元 |
| **日预算** | 不限 |
| **营销目标** | MARKETING_GOAL_USER_GROWTH (用户增长) |
| **优化目标** | OPTIMIZATIONGOAL_PROMOTION_VIEW_KEY_PAGE (关键页面浏览) |
| **投放时间** | 2026-04-15 ~ (长期) |
| **创建时间** | 2026-04-08 15:14:09 |

> **注**: 这是唯一在投放中的广告，可用于后续测试

---

## 4. 测试命令记录

### 获取 Access Token
```bash
curl --location 'https://api.piaoquantv.com/ad/put/tencent/getAccessToken?accountId=80769799'
```

### 查询广告列表（基本信息）
```bash
curl "https://api.e.qq.com/v3.0/adgroups/get?access_token=${ACCESS_TOKEN}&timestamp=${TIMESTAMP}&nonce=${NONCE}&account_id=80769799&page=1&page_size=10"
```

### 查询广告详细信息（含出价、预算等）
```bash
FIELDS='["adgroup_id","adgroup_name","configured_status","system_status","bid_amount","daily_budget","marketing_goal","optimization_goal","begin_date","end_date","created_time"]'
FIELDS_ENC=$(python3 -c "import urllib.parse, sys; print(urllib.parse.quote(sys.argv[1]))" "$FIELDS")

curl "https://api.e.qq.com/v3.0/adgroups/get?access_token=${ACCESS_TOKEN}&timestamp=${TIMESTAMP}&nonce=${NONCE}&account_id=80769799&fields=${FIELDS_ENC}"
```

---

## 5. 已测试的读取接口

| 接口 | 方法 | 状态 | 说明 |
|------|------|------|------|
| `/adgroups/get` | GET | ✅ 成功 | 查询广告列表，支持字段过滤 |

---

## 6. 未测试的接口

### 6.1 其他读取接口

| 接口 | 用途 | 优先级 |
|------|------|--------|
| `/dynamic_creatives/get` | 查询创意列表 | 高 |
| `/daily_reports/adgroups/get` | 查询广告数据报表 | 高 |
| `/accounts/get` | 查询账户信息 | 中 |
| `/custom_audiences/get` | 查询人群包 | 中 |
| `/material_infos/get` | 查询素材库 | 低 |

### 6.2 写入接口 ⚠️

| 接口 | 用途 | 风险等级 |
|------|------|----------|
| `/adgroups/update` | 修改广告（出价/预算/状态） | **高危** |
| `/adgroups/add` | 创建广告 | 高 |
| `/dynamic_creatives/update` | 修改创意 | 中 |
| `/dynamic_creatives/add` | 创建创意 | 中 |

> ⚠️ **重要**: 所有写入操作需要格外小心，建议先在测试账户验证

---

## 7. 下一步计划

### 7.1 继续读取测试 (安全)

1. 测试创意列表查询
   ```bash
   curl "https://api.e.qq.com/v3.0/dynamic_creatives/get?access_token=${TOKEN}&timestamp=${TS}&nonce=${NONCE}&account_id=80769799&page=1&page_size=10"
   ```

2. 测试数据报表查询
   - 注意: 该接口在之前测试中返回"未知接口"错误
   - 可能需要特殊权限或不同的 API 路径

### 7.2 写入操作测试 (谨慎)

**建议测试流程**:

1. **第一步**: 测试修改广告名称（影响最小）
   ```json
   POST /v3.0/adgroups/update
   {
     "account_id": 80769799,
     "adgroup_id": 93269884383,
     "adgroup_name": "测试-修改名称"
   }
   ```

2. **第二步**: 测试调整出价（可恢复）
   - 选择已暂停的广告进行测试
   - 调整幅度 ±5%
   - 记录原始值，测试后恢复

3. **第三步**: 测试暂停/开启（可逆操作）
   - 先暂停一个投放中的广告
   - 立即恢复
   - 观察是否成功

**安全建议**:
- ✅ 始终在已暂停的广告上测试
- ✅ 记录所有原始值，以便恢复
- ✅ 单次只测试一个操作
- ✅ 测试后立即验证结果
- ❌ 不要在投放中的广告上做高风险操作

---

## 8. 系统配置建议

### 8.1 config.py 安全设置

当前配置（已正确）:
```python
DRY_RUN_MODE = True           # ✅ 不实际执行
EXECUTION_ENABLED = False     # ✅ 执行引擎关闭
GUARDRAILS_ENABLED = True     # ✅ 护栏开启
```

### 8.2 测试账户推荐

建议使用广告 **93269884383** (投放中) 作为测试对象:
- ✅ 状态正常
- ✅ 出价较低 (0.40 元)
- ✅ 无日预算限制
- ⚠️ 需要先暂停，避免影响实际投放

---

## 9. 已知问题

### 9.1 报表接口错误

**问题**: `/daily_reports/adgroups/get` 返回 code 12007 "未知接口"

**可能原因**:
1. 账户权限不足
2. API 路径错误
3. 该账户不支持该接口

**待验证**: 联系腾讯广告技术支持确认

### 9.2 代理问题

**问题**: Python 环境中配置了代理，导致 httpx 库报错

**解决方案**:
- 测试脚本中禁用代理
- 或使用 curl 命令直接测试

---

## 10. 总结

### ✅ 成功项

1. Access Token 获取成功
2. 环境变量配置完成
3. 广告列表查询成功
4. 广告详细信息获取成功
5. 腾讯广告 API v3.0 连接正常

### ⏳ 待测试项

1. 创意列表查询
2. 数据报表查询（需解决"未知接口"问题）
3. 写入操作（修改/创建/删除）

### 🎯 建议

1. **优先测试**: 创意列表查询（低风险）
2. **谨慎测试**: 写入操作（建议先修改名称）
3. **暂缓测试**: 数据报表（需确认 API 权限）

---

**测试人员**: Claude (AI Assistant)
**审核状态**: 待人工确认
**下一步操作**: 等待用户指令