qwencloud-payment

QwenCloud Payment

QwenCloud アカウントの支払い方法のステータス、カードの登録、利用限度額を管理します。

前提条件

• QwenCloud CLI >= 1.3.0 がインストールされている必要があります。次のコマンドで確認してください。

qwencloud version

インストールされていない場合は、次を実行してください。

npm install -g @qwencloud/qwencloud-cli

Node.js >= 18 が必要です。

• すべての請求関連コマンドには認証が必要です。以下の認証フローを参照してください。

認証フロー（エージェント向け）

CLI は TTY 以外の環境を自動検出し、安全に処理を切り替えます。

要約 — 認証の3ステップ

1. qwencloud auth status --format json → authenticated: true → コマンドに進みます
2. qwencloud auth login --init-only --format json → verification_url を取得 → ブラウザーで開きます
3. qwencloud auth login --complete --format json → success イベントが発生するまでポーリングします

ステップ1で authenticated: true の場合は、そのまま支払いコマンドに進んでください。

2段階ログインフロー（init-only → complete）の詳細については、qwencloud-usage スキルまたは qwencloud-ops-auth スキルのドキュメントを参照してください。

支払いステータスのコマンド

支払い方法のステータス

qwencloud billing payment-method list --format json

レスポンスのフィールド：

• items[] — 支払い方法の一覧
• items[].status — ステータスが VALID の項目のみが有効と見なされます

有効な支払い方法の件数と種類を提示してください。

利用限度額

現在の利用限度額の設定を照会または表示します。

qwencloud billing limit --format json

設定されている利用限度額と、その限度額に対する現在の利用状況を返します。ステータスが INACTIVE の場合は、現在、利用限度額が設定されていないことをユーザーに伝えてください。

数値の表記： 大きな値を表示するときは、K = 1000、M = 1000000 を使用してください（例：$5K、$1.2M）。

カードを登録する

このコマンドは公式のウェブコンソールページを開きます。会話内で取引を実行することはありません。

確認フロー

カード登録を実行する前に、エージェントは必ず次の操作を行う必要があります。

1. 影響を説明する — この操作で何が行われるか（カード登録用のウェブページを開くこと）を説明します
2. ユーザーから明示的な確認を得る — 確認されていない場合は confirmation_required ステータスを返します
3. 確認を得てから実行する

状態

状態	意味
confirmation_required	ユーザーの確認待ちです — 実行しないでください
confirmed	ユーザーが明示的に同意しました — コマンドを実行してください

手順

1. ユーザーがカード登録を依頼します
2. エージェントが次のように提示します：「ブラウザーで公式のカード登録ページを開きます。続行しますか？」
3. ユーザーが確認した場合 → コマンドを実行します
4. ユーザーが拒否した場合、または応答しない場合 → confirmation_required を返し、何も実行しません

実行

qwencloud billing payment-method bind --format json

ユーザーのブラウザーで公式のカード登録ページを開きます。CLI 経由でカード情報が送信されることはありません。

出力とエージェントの表示ルール

CLI コマンドは、エージェント環境またはパイプ環境ではデフォルトで JSON を返します。 必ず --format json を渡し、構造化されたレスポンスを解析してから、人が読める要約を提示してください。

出力の提示方法

1. JSON を解析し、ユーザーの質問に関連するデータを抽出します
2. 人が読める要約を提示します — 生の JSON をそのまま出力しないでください
3. 要約の後に分析を追加します — --- で明確に区切ってください

エラー処理

• 認証エラー： 元の CLI エラーメッセージを返してください。ログインを繰り返し再試行しないでください。
• ログイン成功後： 失敗したコマンドを一度だけ再試行してください。
• ネットワークエラー： エラーを報告し、接続を確認するようユーザーに案内してください。
• 不明なエラー： デバッグ用に CLI の標準エラー出力をそのまま返してください。

結果のステータス

ステータス	条件
success	コマンドが実行され、データがすべて返された場合
partial	コマンドは実行された（終了コード 0）が、想定されるフィールドの一部が欠落または null の場合 — 例：payment-method list で項目は返されるものの、フィールドが null の場合や、billing limit が INACTIVE を返し、一部のフィールドが欠落している場合。利用可能なデータを提示し、詳細をウェブコンソールで確認するようユーザーに伝えてください
empty	コマンドは実行されたが、データがない場合（例：支払い方法が紐付けられていない）
confirmation_required	カード紐付けアクションでユーザーの確認が必要な場合
error	コマンドが失敗した場合 — エラーの詳細を含めてください

絶対に行わないこと

• ❌ ユーザーの明示的な確認なしに bind を実行しない
• ❌ 会話内で実際のカード送信や取引を行わない
• ❌ 明示的な基準なしに、支払い方法を「不十分」と判断しない
• ❌ サポートチケットを扱わない（対象範囲外）
• ❌ 請求履歴や使用状況を照会しない（代わりに qwencloud-usage を使用）
• ❌ サブスクリプションのステータスを照会しない（代わりに qwencloud-usage を使用）
• ❌ 認証に失敗した場合、ログインをループして再試行しない