パートナー API

パートナー向けのサーバー間 API：キーの発行、ストアフロントの設定とロケーションの読み取り、顧客の作成、プランの付与、サブスクリプションリンクの管理を、独自のサイトや Telegram ボットから行えます。

パートナー API を使うと、CreateYourVPN の上に独自のサイト、独自のダッシュボード、Telegram ボットを構築できます。

API が扱うのは顧客、サブスクリプション、プラン、ストアフロントの設定です。サーバー、ノード、パネル、SSH の認証情報などのインフラは、公開コントラクトの対象外です。

サーバー間通信専用です。 API キーはサーバーに保存し、フロントエンドのコードには含めないでください。ブラウザーのヘッダーが付いたリクエストは 403 browser_forbidden で拒否されます。

キーの取得

ダッシュボードでアカウントメニュー → 「API」を開き、「キー」タブを選びます。

キーに名前を付け（Telegram ボット、ランディングページ）、必要な権限だけを選びます。

「キーを発行」を選び、値全体をコピーします。保存されるのはハッシュだけなので、secret が表示されるのは一度だけです。

パートナーごとに有効なキーは最大 5 個です。キーをローテーションするには、新しいキーを発行し、連携先を更新してから、古いキーを失効させます。

認証

キーは bearer トークンとして送信します。

curl https://api.createyourvpn.com/api/v1/partner-api/me \
  -H "Authorization: Bearer cyv_live_<key_id>_<secret>"

プロキシが Authorization を使用しているクライアントでは、X-API-Key: cyv_live_… も使えます。

キーの形式は cyv_live_<key_id>_<secret> です。前半（key_id）は公開情報です: ダッシュボードに表示され、サポートに伝えても問題ありません。後半は secret です。

権限（スコープ）

権限	許可される操作
`config:read`	ストアフロントの設定、プラン、ロケーション、`/me` の読み取り。
`users:read`	顧客と、そのサブスクリプションと通信量の読み取り。
`users:write`	顧客の作成、プランの付与、サブスクリプションリンクのリセット、顧客の削除。

ストアフロントのデータを読むだけの連携なら、config:read で十分です。users:read や users:write は、連携に対応する顧客操作が必要な場合にだけ追加してください。

API コントラクトとサンプル

実行可能な完全なコントラクトは、公開 Postman コレクションにあります。すべてのエンドポイント、権限、パラメーター、リクエストボディ、レスポンスの例、安定したエラーコードが含まれています。コレクションはバックエンドのコントラクトから生成され、リクエストとレスポンスのスキーマの最新の情報源です。

公開 Postman コレクションを開く

すべてのエンドポイントを確認し、コレクションを自分のワークスペースにフォークします。

レート制限

制限は、リクエストの IP アドレスとは関係なく、キーごとに個別にカウントされます。

キー全体で毎分 120 リクエスト。
GET /users には別途毎分 10 リクエスト。

GET /users に個別の制限があるのは、リクエストのたびに顧客の一覧全体を読み込むためです。日常的な参照には、GET /users/{id} か externalId による検索を使ってください。

推奨するアクセス方法。 作成時に返される CreateYourVPN の顧客 ID を保存し、以降の参照には GET /users/{id} を使ってください。externalId を使えば、独自の識別子と関連付けられます。

冪等性

Idempotency-Key ヘッダーが必要な操作は 3 つです: プランの付与、サブスクリプションリンクのリセット、顧客の削除。

curl -X POST .../users/u_9f3a…/grant \
  -H "Authorization: Bearer $CYV_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"tariffId":"monthly"}'

同じキーでのリクエストを 24 時間以内に繰り返すと、操作を再実行する代わりに、保存済みのレスポンスが返されます。これにより、タイムアウト後に連携先が再試行しても、変更が重複しません。

ビジネスイベント（例えば 1 件の支払いや 1 つの操作）ごとにキーを 1 つ作成し、そのイベントのすべての再試行で使い回してください。

最初の試行がまだ実行中か、その結果が一時的に不明な場合、API は操作を再実行せずに 409 conflict を返します。再試行するかどうかを決める前に、顧客の現在の状態を確認してください。

リクエストとレスポンスのスキーマは、上記の公開 Postman コレクションを正としてください。