billing-integration

Credyt の統合

手作業で HTTP 呼び出しを実装するより、公式 SDK（TypeScript 用の @credyt/api-client、Python 用の credyt-api）を優先してください。認証、再試行、フィールドのマッピングを SDK が処理します。どちらの SDK も技術スタックに合わない場合（TypeScript や Python 以外の言語など）は、以下で HTTP を直接呼び出す方法も説明しています。先に billing-setup を実行せずにここにたどり着いた場合は、作業を中断し、先にそのスキルを実行するようユーザーに依頼してください。

ユーザーがアプリケーションのコードに Credyt を組み込めるよう支援します。このスキルでは、ユーザーの実際のコードベースを確認し、既存のコードを読み取ったうえで、適切な箇所に Credyt の統合を追加します。

統合ガイドの全文は docs.credyt.ai/ai-integration.md にあります。以下の各セクションから、HTTP、TypeScript、Python の例を含む専用ドキュメントに移動できます。統合分野について詳しい情報が必要な場合は、こちらを参照してください。

フィールド名について： Credyt API では、すべてのフィールド名に snake_case を使用します。TypeScript SDK はこれらを自動的に camelCase にマッピングします。Python SDK では snake_case のままです。リンク先のドキュメントにあるコード例では、3 つのパターンすべてを紹介しています。

まずコードベースを理解する

コードを書く前に、ユーザーの環境を把握してください。

「プロジェクトを確認して、技術スタックと課金を組み込む場所を把握します。」

次の点を確認します。

• 言語とフレームワーク（Node/Express、Next.js、Python/FastAPI など）
• 認証の設定（ユーザーのサインアップとログインの方法）
• 課金対象のアクティビティがコード内で発生する場所
• 既存の環境変数の設定パターン

統合方法を選択する

状況に応じて適切な方法を判断してください。判断できない場合に限り、ユーザーに質問してください。

自動判定（次の順に確認）：

1. 既知の AI プラットフォーム — Lovable、Bolt、Replit、V0 はいずれもデフォルトで TypeScript を使用します。これらの環境で動作している場合は、TypeScript SDK を使用してください。
2. 既存の技術スタック — 上記でスキャンしたコードベースを確認します。package.json があれば TypeScript/Node.js SDK、requirements.txt または pyproject.toml があれば Python SDK を使用します。
3. 不明な場合 → 「TypeScript/Node.js、Python、または別の言語のどれをお使いですか？」 と尋ね、最初の 2 つについては SDK を優先して案内します。

判断できたら、コードを書く前に推奨方法を伝え、ユーザーが変更を希望できるようにしてください。

「お使いの技術スタックに基づき、TypeScript SDK（@credyt/api-client）を使用します。Python または HTTP の直接呼び出しをご希望の場合はお知らせください。」

SDK パッケージ：

• TypeScript/Node.js → @credyt/api-client（npm install @credyt/api-client）
• Python → credyt-api（pip install credyt-api）
• その他の言語、または生の HTTP を希望する場合 → X-CREDYT-API-KEY ヘッダーを使った API の直接呼び出し

3 つすべての方法の例を含む SDK リファレンス全文は、docs.credyt.ai/sdk にあります。

統合する分野

各分野を順に確認してください。ユーザーによって必要な分野は異なるため、どれが必要か尋ねてください。

1. API キーの設定

Credyt API キーはサーバー側で安全に保管する必要があります。ブラウザーで実行されるコードには、絶対に含めないでください。

他のシークレットとともに CREDYT_API_KEY を環境変数に追加し、クライアントを一度だけ初期化して、リクエスト間で再利用します。

TypeScript：

import { CredytApiClient } from "@credyt/api-client";
const client = new CredytApiClient({ key: process.env.CREDYT_API_KEY! });

Python：

from corehttp.credentials import ServiceKeyCredential
from credytapi import CredytApiClient

client = CredytApiClient(
    credential=ServiceKeyCredential(key=os.getenv("CREDYT_API_KEY")),
)

HTTP の直接呼び出し： すべてのリクエストに X-CREDYT-API-KEY: <key> を付けます。このヘッダーを自動的に設定するヘルパー関数または設定済みの HTTP クライアントインスタンスを作成してください。

2. 顧客の作成 — ドキュメント

アプリに新しいユーザーが登録したときは、対応する Credyt の顧客を作成します。登録／サインアップを処理するハンドラーを見つけ、アカウント作成が成功した後に顧客の作成処理を追加してください。

重要なポイント：

• external_id を使用して、Credyt の顧客とアプリのユーザー ID を紐付けます
• 作成時に、関連するプロダクトに顧客を登録します
• ユーザーレコードと併せて、Credyt の顧客 ID をデータベースに保存します
• 顧客がすでに存在する場合（409／422）の処理を実装します。その場合は external_id で検索してください

SDK メソッド： client.customers.create(...)

定額の継続料金 — 保留中のサブスクリプション

プロダクトに定額の継続料金（例：月額 $20）が設定されている場合、サブスクリプションが有効になる前に顧客が前払いする必要があります。この場合、API はただちに有効化するのではなく、pending ステータスを返します。

支払い後に Credyt が顧客をどこへ送ればよいか判断できるよう、サブスクリプションに return_url、failure_url、redirect_to を設定してください。

• return_url — 支払い成功後に顧客を送る URL（例：https://yourapp.com/account）
• failure_url — 支払いに失敗した場合に顧客を送る URL（例：https://yourapp.com/callbacks/payment-failed）
• redirect_to — 顧客が Credyt の請求ポータルにとどまらず、サイトに戻るよう "return_url" に設定します（これがデフォルトですが、明示的に設定してください）

レスポンスのステータスが pending の場合：

• required_actions 配列から type: "payment" のアクションを探し、その redirect_url を取得します
• 顧客をその URL にリダイレクトします。Credyt が支払いフォームを処理し、return_url または failure_url に自動的に案内します
• まだユーザーのアカウントを有効化しないでください。支払いが確認されるまで、データベースで保留中として保存します
• 顧客が支払いを完了する前にリダイレクトリンクの有効期限が切れた場合は、Credyt の顧客 ID で顧客を取得し、新しいリンクを取得します

顧客が支払いを完了すると、Credyt は subscription.activated ウェブフックを送信します。バックエンドでこのイベントをリッスンし、ユーザーのアカウント有効化に使用してください。

プロモーションまたはバンドルされたサインアップクレジット

ユーザーのプランにプロモーションクレジット（例：「最初に $10 分を無料で利用」）やバンドルクレジット（例：サインアップ時に 1,000 件の API 呼び出しを無料で利用）が含まれる場合、適用方法は 2 つあります。

1. 顧客作成後に一度だけ調整する — サインアップ後に顧客のウォレットへ直接クレジットを付与します。シンプルな一度限りのプロモーション金額に使用します。docs.credyt.ai/advanced-topics/adjustments-charges-gifts を参照してください。
2. エンタイトルメント — プロダクト定義の一部としてプロモーションクレジットを設定すると、新しいサブスクリプションごとに自動適用されます。標準プランに含まれるクレジットに使用します。docs.credyt.ai/features/product-catalog/entitlements を参照してください。

サインアップクレジットを含めるかどうかユーザーに確認し、含める場合は、どちらの方法が用途に合うか尋ねてください。

3. 使用状況イベントの追跡 — ドキュメント

コード内で課金対象のアクティビティが発生する箇所を見つけ、それぞれの実行後にイベント送信処理を追加します。各イベントには次の情報が必要です。

• 同じイベントが二重に課金されないよう、一意の ID（UUID）
• プロダクト設定に一致する正しい event_type
• 発生時刻を示すタイムスタンプ（occurred_at）
• 料金計算に必要なデータフィールド（数量フィールド、ディメンション）

SDK メソッド： client.events.sendUsage(...)（TS）または client.events.send_usage(...)（Python）。

数量ベースのプロダクトでは、イベントデータに数量フィールド（例：total_tokens: 1500）を含める必要があります。 ディメンションベースのプロダクトでは、ディメンションの値（例：model: "gpt-4"）を含めてください。

4. コスト追跡 — ドキュメント

ユーザーが /credyt:billing-setup でベンダーを設定している場合は、使用イベントにコストデータを追加します。各イベントには、ベンダー ID、コストの金額、通貨を含む costs 配列を指定できます。

通常は、コストが判明した時点（トークン数を含む AI API のレスポンスを受け取った後など）で、課金対象のアクションが完了した直後に追加します。

「まだユーザーへの課金を始めていなくても、すべてのイベントにコストを紐付けておけば、Credyt がユニットエコノミクスを算出し、実際のデータに基づいて価格を決定できます。」

5. 残高チェック — ドキュメント

コストのかかる処理を実行する前に、顧客のウォレット残高を確認します。残高が不足している場合は、アクションをブロックし、ユーザーにチャージを促します。

SDK メソッド： ウォレット全体を取得するには client.wallets.customerWalletOps.getCustomerWallet(customerId) を、特定のアカウント残高を確認するには client.wallets.customerWalletOps.getAccount(customerId, "accountName:ASSET") を使用します。

課金対象のアクションが開始される箇所（API ルート、ボタンハンドラーなど）を見つけ、アクションの実行前に残高チェックを追加します。残高が不足している場合は、わかりやすいメッセージを返します。

これから実行するアクションのコストを見積もり、利用可能な残高と比較します。

6. 請求ポータル／チャージ UI — ドキュメント

Credyt の請求ポータルを通じて、ユーザーが資金を追加できるようにします。これは支払いを処理する最も簡単な方法です。Credyt がページをホストし、Stripe を処理して、ユーザーをアプリにリダイレクトします。

アプリの設定ページまたはアカウントページに、「請求」または「資金を追加」のリンク／ボタンを追加します。クリックされたら、バックエンドで請求ポータルのセッションを作成し、ユーザーをその URL にリダイレクトします。

SDK メソッド： client.billingPortal.createPortalSession(...)

主なポイント：

• ポータルセッションの有効期限は 10 分です
• 完了後にユーザーを遷移させる先を return_url に設定します
• 支払いに失敗した場合の遷移先を failure_url に設定します

7. 残高表示 — ドキュメント

アプリの UI にユーザーの現在の残高を表示します。ウォレットエンドポイントから取得し、利用可能な金額を表示します。

SDK メソッド： client.wallets.customerWalletOps.getCustomerWallet(customerId)。

アプリ内での表示場所（サイドバー、ヘッダー、アカウントページなど）を決め、そこに追加します。

実装手順

コードを一度にすべて提示しないでください。各項目を順番に進めます。

1. API キーの設定と顧客の作成から始めます。これらは基盤となる部分です
2. 次に、使用イベントの追跡を追加します。これは課金連携の中核です
3. コストのかかる処理を制御するため、残高チェックを追加します
4. ユーザー向け機能として、請求ポータルと残高表示を追加します
5. 該当する場合は、最後にコスト追跡を追加します

各項目の後に、テストを提案します。

「アプリで新しいアカウントを作成して、Credyt ダッシュボードを確認してみてください。新しい顧客が表示されるはずです。次に、使用状況の追跡に進みましょう。」

リファレンス

コード例、エラー処理のパターン、ハイブリッド課金、返金、自動チャージなどの高度なトピックについては、以下を案内してください。

• SDK リファレンス（TypeScript および Python）：docs.credyt.ai/sdk
• 統合ガイド全文：docs.credyt.ai/ai-integration.md
• API リファレンス：docs.credyt.ai
• サンプル：github.com/credyt/learn