合作伙伴开放 API 指南

成为 QCode 合作伙伴后，用访问令牌程序化管理你的分销账户：查询余额与消耗、创建与启停对外销售的子 API Key。含开通前提、申请方式、鉴权、接口一览、频率限制与安全建议。

合作伙伴开放 API 指南¶

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

⚠️ 使用前提：必须先开通「合作伙伴权益」。 本 API 仅对已审批的 QCode 合作伙伴开放。如果你还不是合作伙伴，请先在 合作伙伴计划 申请开通，开通后才能生成访问令牌、调用接口。

一、这套 API 能做什么¶

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

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

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

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

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

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

开通涉及预付充值与合作等级（A–E，对应不同折扣倍率），具体以 合作伙伴计划 页面说明为准。未开通账户调用本 API 会返回 403。

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

开通后：

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

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

四、鉴权与入口¶

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

五、接口一览¶

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

六、创建子 API Key¶

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

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":[]}}

启用 / 停用、修改配额：

# 停用
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": "..."}

九、安全建议¶

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

十、完整参考与支持¶

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