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

QCode の承認済みパートナーになると、アクセストークンでリセラーアカウントをプログラムから管理できます：残高・使用量の確認、再販用サブ API キーの作成と有効/無効化。前提条件、申請方法、認証、エンドポイント一覧、レート制限、セキュリティを解説。

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

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

⚠️ 前提条件：先に承認済みパートナーになる必要があります。 この API は 承認済みの QCode パートナー専用 です。まだパートナーでない場合は、先に申請してください。承認後にアクセストークンを発行し、API を呼び出せます。

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

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

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

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

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

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

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

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

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

承認後：

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

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

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

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

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

すべてのエンドポイントは /api/v1/reseller/ プレフィックス配下です。

6. サブ API キーの作成¶

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

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

7. レート制限¶

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

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

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

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

9. セキュリティ¶

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

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

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