# 合作伙伴开放 API 指南

QCode **合作伙伴开放 API** 让你以编程方式管理自己的分销账户——查询余额与消耗、创建并管理对外销售的子 API Key——把开通、对账、发卡等动作集成进你自己的系统或后台，无需每次登录网页面板手动操作。

> ⚠️ **使用前提：必须先开通「合作伙伴权益」。**
> 本 API 仅对**已审批的 QCode 合作伙伴**开放。如果你还不是合作伙伴，请先在 [合作伙伴计划](https://qcode.cc/partner-program) 申请开通，开通后才能生成访问令牌、调用接口。

---

## 一、这套 API 能做什么

成为 QCode 合作伙伴后，你拥有一个分销账户（含预付余额、按合作等级享受的折扣倍率），可以创建多个**子 API Key** 分发给你自己的客户或团队，并为每个 Key 独立设置配额。开放 API 把面板里的这些能力暴露成 REST 接口：

- **只读类**：查看账户余额与已用、近 7 / 30 天每日消耗、列出所有子 API Key 及各自消耗。
- **写操作类**：创建子 API Key（明文仅返回一次）、启用 / 停用子 API Key、修改子 Key 的配额与并发。

适合：要把发卡 / 对账接入自有计费系统、自动为下游客户开 Key、定期拉取用量做监控告警的合作伙伴。

---

## 二、如何开通合作伙伴权益（前提）

本 API **仅对已开通的合作伙伴可用**。

- **还不是合作伙伴** → 前往 [合作伙伴计划](https://qcode.cc/partner-program) 了解合作等级与计费方式，并按页面「如何申请」提交申请（邮件至 `hi@qcode.cc`）。审核通过后，你的账户会被激活为合作伙伴。
- **已经是合作伙伴** → 直接登录 [分销面板](https://qcode.cc/reseller/dashboard)。

> 开通涉及预付充值与合作等级（A–E，对应不同折扣倍率），具体以 [合作伙伴计划](https://qcode.cc/partner-program) 页面说明为准。未开通账户调用本 API 会返回 `403`。

---

## 三、快速开始：获取访问令牌

开通后：

1. 登录 [qcode.cc](https://qcode.cc) → 进入**分销面板**。
2. 打开 **「开放 API / 访问令牌」**。
3. 点击**生成令牌**，得到形如 `rsk_xxxxxxxx` 的访问令牌。

> 🔑 **令牌只在生成 / 重置时完整显示一次**，请立即复制并妥善保存（服务端只存储其哈希）。遗失或泄露时，在同一页面点击**重置**即可换发新令牌，**旧令牌立即失效**。

---

## 四、鉴权与入口

| 项 | 值 |
|---|---|
| 主入口（推荐） | `https://api.r.qcode.cc` |
| 备用入口 | `https://qcode.cc`（同一套接口） |
| 鉴权 | 请求头 `Authorization: Bearer rsk_xxxxxxxx` |
| 写操作请求体 | JSON，需带 `Content-Type: application/json` |

```bash
curl https://api.r.qcode.cc/api/v1/reseller/balance \
  -H "Authorization: Bearer rsk_xxxxxxxx"
```

---

## 五、接口一览

所有接口都在 `/api/v1/reseller/` 前缀下。

| 方法 | 路径 | 说明 |
|---|---|---|
| GET | `/api/v1/reseller/me` | 账户概况（合作等级、区域、结算币种、状态） |
| GET | `/api/v1/reseller/balance` | 余额与已用（你的结算币种） |
| GET | `/api/v1/reseller/usage?range=7d` | 每日消耗序列（`range` 可选 `7d` / `30d`） |
| GET | `/api/v1/reseller/keys` | 列出你的所有子 API Key + 各自消耗 |
| GET | `/api/v1/reseller/keys/{id}` | 单个子 Key 详情 |
| POST | `/api/v1/reseller/keys` | 创建子 Key（**明文仅返回一次**） |
| POST | `/api/v1/reseller/keys/{id}/enable` | 启用子 Key |
| POST | `/api/v1/reseller/keys/{id}/disable` | 停用子 Key |
| PATCH | `/api/v1/reseller/keys/{id}` | 修改配额 / 并发 |

---

## 六、创建子 API Key

配额单位为**上游 USD**。`daily_cost_limit_usd` 与 `total_cost_limit_usd` 必须 **大于 0**。可携带 `Idempotency-Key` 请求头让重试安全（避免超时重试创建出两把 Key）。返回的明文 `cr_…` Key **仅此一次**，请立即保存并分发给你的客户。

```bash
curl -X POST https://api.r.qcode.cc/api/v1/reseller/keys \
  -H "Authorization: Bearer rsk_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 每次创建唯一" \
  -d '{"description":"client-a","daily_cost_limit_usd":5,"total_cost_limit_usd":100,"concurrency_limit":5}'

# → {"ok":true,"data":{"id":"...","name":"...","api_key":"cr_...","warnings":[]}}
```

启用 / 停用、修改配额：

```bash
# 停用
curl -X POST https://api.r.qcode.cc/api/v1/reseller/keys/{id}/disable \
  -H "Authorization: Bearer rsk_xxxxxxxx"

# 改每日配额上限
curl -X PATCH https://api.r.qcode.cc/api/v1/reseller/keys/{id} \
  -H "Authorization: Bearer rsk_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"daily_cost_limit_usd":10}'
```

---

## 七、频率限制

这些接口是低频管理用途，设有频率限制以降低令牌泄露后的风险：

- 每个令牌：**60 次 / 分钟**、**1000 次 / 天**。
- 创建子 Key（`POST /keys`）：每个令牌 **5 次 / 小时**。
- 超出限制返回 HTTP **429**，并带 `Retry-After` 响应头（单位：秒）。

---

## 八、响应与错误

- 成功：`{"ok": true, "data": { ... }}`
- 错误：对应的 HTTP 状态码 + `{"detail": "..."}`

| 状态码 | 含义 |
|---|---|
| 401 | 令牌无效或缺失 |
| 403 | 账户未激活（合作伙伴权益未开通或已暂停） |
| 404 | 子 Key 不存在或无权限 |
| 422 | 参数或配额错误 |
| 429 | 触发频率限制 |

---

## 九、安全建议

- 把访问令牌当作密码：只放在服务端、只走 HTTPS，**不要**提交进代码库或暴露到前端。
- 令牌泄露 → 立即在面板**重置**（旧令牌即失效），并酌情停用受影响的子 Key。
- 创建子 Key 时为每个 Key 设置合理的 `total` / `daily` 上限，缩小单把 Key 泄露的损失面。
- 你分发出去的 `cr_…` 子 Key 会消耗你账户的余额，请妥善管理与对账。

---

## 十、完整参考与支持

- 开通后，分销面板内的 **「API 文档」**（`/reseller/api-docs`）是随版本更新的权威开发者参考。
- 还没开通？→ [了解并申请合作伙伴计划](https://qcode.cc/partner-program)
- 有疑问？→ 站内在线客服，或邮件 `hi@qcode.cc`。