# パートナー向けオープン API ガイド

QCode の**パートナー向けオープン API** を使うと、リセラー（パートナー）アカウントをプログラムから管理できます——残高や使用量の確認、再販するサブ API キーの作成・管理——ので、開通・突合・キー発行を自社システムに組み込み、毎回 Web パネルを手作業で操作する必要がなくなります。

> ⚠️ **前提条件：先に承認済みパートナーになる必要があります。**
> この API は **承認済みの QCode パートナー専用** です。まだパートナーでない場合は、[先に申請](https://qcode.cc/partner-program)してください。承認後にアクセストークンを発行し、API を呼び出せます。

---

## 1. この API でできること

QCode のパートナーになると、リセラーアカウント（前払い残高、ティアに応じた割引倍率）を持ち、自分の顧客やチームに再販する**サブ API キー**を複数作成でき、キーごとにクォータを設定できます。オープン API はパネルのこれらの機能を REST エンドポイントとして提供します：

- **参照系** — アカウント残高と使用量、直近 7 / 30 日の日次消費、すべてのサブ API キーとキーごとの消費の一覧。
- **更新系** — サブ API キーの作成（平文キーは 1 回だけ返却）、サブキーの有効化 / 無効化、キーのクォータと同時実行数の変更。

自社の課金システムにキー発行・突合を組み込みたい、下流の顧客向けに自動でキーを発行したい、使用量を定期的に取得して監視したいパートナーに最適です。

---

## 2. パートナーになる方法（前提条件）

この API は **パートナーアクセスが承認された後** にのみ利用できます。

- **まだパートナーでない** → [パートナープログラム](https://qcode.cc/partner-program) でティアと料金を確認し、「申請方法」セクションから申請してください（メール `hi@qcode.cc`）。承認されると、アカウントがパートナーとして有効化されます。
- **すでにパートナー** → [パートナーダッシュボード](https://qcode.cc/reseller/dashboard) にログインしてください。

> 開通には前払いチャージとパートナーティア（A〜E、それぞれ割引倍率が異なる）が含まれます。詳細は [パートナープログラム](https://qcode.cc/partner-program) ページをご覧ください。未承認のアカウントでこの API を呼び出すと `403` が返ります。

---

## 3. クイックスタート：アクセストークンの取得

承認後：

1. [qcode.cc](https://qcode.cc) にログイン → **パートナーダッシュボード** を開く。
2. **「Open API / アクセストークン」** を開く。
3. **トークンを生成** をクリックして、`rsk_xxxxxxxx` 形式のトークンを取得。

> 🔑 **トークンの全体が表示されるのは生成 / リセット時の 1 回だけです。** すぐにコピーして安全な場所に保管してください（サーバーにはハッシュのみを保存します）。紛失・漏洩した場合は、同じページで **リセット** すると新しいトークンに置き換わり、**古いトークンは即座に無効** になります。

---

## 4. 認証とエンドポイント

| 項目 | 値 |
|---|---|
| ベース URL（推奨） | `https://api.r.qcode.cc` |
| 予備 | `https://qcode.cc`（同じ API） |
| 認証 | ヘッダー `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"
```

---

## 5. エンドポイント一覧

すべてのエンドポイントは `/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 キーの一覧 + キーごとの消費 |
| GET | `/api/v1/reseller/keys/{id}` | 単一キーの詳細 |
| POST | `/api/v1/reseller/keys` | サブキーを作成（**平文キーは 1 回だけ返却**） |
| POST | `/api/v1/reseller/keys/{id}/enable` | キーを有効化 |
| POST | `/api/v1/reseller/keys/{id}/disable` | キーを無効化 |
| PATCH | `/api/v1/reseller/keys/{id}` | クォータ / 同時実行数を変更 |

---

## 6. サブ API キーの作成

上限は **アップストリーム USD** 建てです。`daily_cost_limit_usd` と `total_cost_limit_usd` は **0 より大きい** 必要があります。`Idempotency-Key` ヘッダーを付けるとリトライが安全になります（タイムアウト再試行でキーが 2 つ作られるのを防止）。平文の `cr_…` キーは **1 回だけ** 返却されるので、保存して顧客に渡してください。

```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}'
```

---

## 7. レート制限

これらは低頻度の管理用エンドポイントで、トークン漏洩時のリスクを下げるためレート制限があります：

- トークンあたり：**60 回 / 分**、**1000 回 / 日**。
- キー作成（`POST /keys`）：トークンあたり **5 回 / 時**。
- 制限を超えると HTTP **429** と `Retry-After` ヘッダー（秒）を返します。

---

## 8. レスポンスとエラー

- 成功：`{"ok": true, "data": { ... }}`
- エラー：対応する HTTP ステータス + `{"detail": "..."}`

| ステータス | 意味 |
|---|---|
| 401 | トークンが無効または欠落 |
| 403 | アカウントが有効でない（パートナーアクセス未承認 / 停止中） |
| 404 | キーが存在しない、または自分のものでない |
| 422 | バリデーション / クォータエラー |
| 429 | レート制限に到達 |

---

## 9. セキュリティ

- アクセストークンはパスワードと同様に扱ってください：サーバー側にのみ保持し、HTTPS のみで使用し、リポジトリにコミットしたりブラウザに露出させたりしないでください。
- トークンが漏洩したら → ただちにパネルで **リセット**（古いトークンは無効化）し、必要に応じて影響を受けたサブキーを無効化してください。
- 作成する各サブキーに適切な `total` / `daily` の上限を設定し、1 つのキーが漏洩した際の損害を限定してください。
- 発行した `cr_…` サブキーはアカウント残高を消費します。管理と突合を慎重に行ってください。

---

## 10. 詳細リファレンスとサポート

- 承認後、パートナーダッシュボード内の **「API Docs」** ページ（`/reseller/api-docs`）が、バージョン管理された開発者向けの公式リファレンスです。
- まだパートナーでない方は → [プログラムの詳細と申請](https://qcode.cc/partner-program)
- ご質問は → サイト内のライブチャット、またはメール `hi@qcode.cc`。