# 拡張の仕組み

拡張ポイントを使用して Stripe をカスタマイズする方法をご紹介します。

拡張機能を使用すると、[拡張ポイント](https://docs.stripe.com/extensions/extension-points.md)と呼ばれる Stripe の指定された場所でカスタムロジックを実行できます。Stripe がこれらの拡張ポイントでロジックを実行する必要がある場合、拡張機能が拡張ポイントに接続されているかどうかを確認し、接続されている場合はその拡張機能内のカスタムロジックを実行します。

たとえば、Stripe は[比例配分](https://docs.stripe.com/extensions/scripts/build-prorations-extension.md)の拡張ポイントを定義しています。比例配分の計算ステップに達すると、デフォルトの比例配分ロジックの代わりに拡張機能のロジックが実行されます。拡張機能によって比例配分する方法が決定されて金額が返されると、Stripe はその結果を使用して請求フローを続行します。

また、Stripe は [Workflows](https://docs.stripe.com/extensions/custom-actions/how-custom-actions-work.md) のカスタムアクション拡張ポイントも定義しています。ワークフローがトリガーされると、Stripe によって拡張機能が呼び出され、メールの送信、CRM の更新、または定義したその他の操作が実行されます。

## モデルの仕組み

Stripe は、コードを実行できる拡張ポイント (Stripe 製品内の指定された場所) を定義します。各拡張ポイントは以下を指定します。

- **入力**: 拡張ポイントに達したときに Stripe が拡張に送信するデータ。拡張ユーザーからの入力も含まれます。
- **出力**: 拡張が Stripe に返す必要があるデータ
- **許可されている実装タイプ**: その拡張ポイントで使用できる実装タイプ (スクリプト、リモート関数、またはその両方)

(See full diagram at https://docs.stripe.com/extensions/how-extensions-work)

```text
[ユーザー入力] --> [検証]
[検証] --> [拡張コード]
[Stripe 入力] --> [拡張コード]
[拡張コード] --> [出力]
```

まず、ユースケースの[拡張ポイント](https://docs.stripe.com/extensions/extension-points.md)を見つけます。

カスタムロジックは、拡張ポイントに接続する拡張機能として構築します。拡張機能は [Stripe Apps](https://docs.stripe.com/stripe-apps.md) の一部としてパッケージ化され、インストール、権限、配布が処理されます。同じアプリ内に、[スクリプト](https://docs.stripe.com/extensions/how-extensions-work.md#scripts)、[リモート関数](https://docs.stripe.com/extensions/how-extensions-work.md#remote-functions)、[UI 拡張機能](https://docs.stripe.com/extensions/how-extensions-work.md#ui-extensions)など、任意の実装タイプの複数の拡張機能をパッケージ化できます。アプリには [Custom Objects](https://docs.stripe.com/custom-objects.md) を含めることもできます。

## 実装タイプ

各拡張ポイントは、1 つ以上の実装タイプに対応しています。実装タイプによって、コードが実行される場所と外部サービスとのやり取り方法が決まります。

### 実装タイプを選択

拡張ポイントがスクリプトとリモート関数の両方に対応している場合は、次の表を使用して判断してください。

| 検討事項 | スクリプト | リモート関数 |
| --- | --- | --- |
| 実行場所 | Stripe のマネージドランタイム | お客様のインフラストラクチャ |
| 言語 | TypeScript | 任意の言語 (HTTP エンドポイント) |
| 外部 API コール | 拡張ポイントによって異なります。カスタムアクションでは `endpointFetch()` を通じて使用できます。請求拡張ポイントでは使用できません。 | はい。サーバーから直接呼び出しを行います |
| 外部サービスの認可 | Stripe は、エンドポイント設定と [Secret Store](https://docs.stripe.com/stripe-apps/store-secrets.md) (外部 API コールが許可される場所) を通じてシークレットを注入します | お客様自身で認証を管理します |
| Stripe からコードへの認可 | 該当なし。コードは Stripe 上で実行されます | Stripe では各リクエストに署名が付与されます。[Webhook 署名を検証](https://docs.stripe.com/webhooks.md#verify-signature)してください。 |
| 最適な用途 | 独自のインフラを必要としないロジック | 独自のシステム、変換処理、または TypeScript 以外の言語を必要とするロジック |
| 制限事項 | サードパーティーへの依存関係なし、直接の `fetch()` は使用不可、TypeScript のみ | ホスティング、可用性、デプロイを自社で管理します |

### スクリプト

スクリプトは、Stripe のフルマネージドランタイム上で実行される TypeScript のメソッドです。Stripe がコードを実行するため、インフラをホストする必要はありません。アプリは Stripe CLI を通じてアップロードしてデプロイします。

スクリプトは、Stripe が拡張ポイントに到達するとビジネスロジックを実行します。スクリプトは、次の場合に使用します。

- 顧客の購入履歴や販売イベントに基づいて割引を計算するなど、コードを使用して複雑なビジネスルールを適用します。
- 顧客が利用資格を満たしているかどうかを確認するなど、Stripe が処理する前にデータを検証または変換します。
- Webhook を構築および維持することなく、外部データを Stripe のオペレーションに統合します。
- 独自のサービスをデプロイおよび管理することなく、迅速にプロトタイプを作成できます。

スクリプトで実行できることは、拡張ポイントによって異なります。

- **Billing 拡張ポイント** (顧客残高、項目処理、比例配分)では、スクリプトは Stripe からデータを受け取り、ロジックを実行して結果を返します。外部 API コールは許可されていません。これらの拡張ポイントは Billing パイプラインで実行され、Stripe は信頼性を維持するために副作用を制限します。
- **カスタムアクションの拡張ポイント** (Workflows 用): スクリプトは、`endpointFetch()` を使用して外部の HTTP 呼び出しを実行できます。[アプリマニフェスト](https://docs.stripe.com/stripe-apps/reference/app-manifest.md?manifestVersion=manifest-v2)でエンドポイントを宣言すると、Stripe により、[Secret Store](https://docs.stripe.com/stripe-apps/store-secrets.md) を通じてシークレットの保存と認証情報の挿入が処理されます。これは、インフラストラクチャを管理することなく外部サービスにアクセスするアクション向けに設計されています。

#### ユースケース

| ユースケース | 請求処理の動作 | スクリプト | 説明 |
| --- | --- | --- | --- |
| 請求の最小しきい値を設定します。 | 顧客残高 | [回収前の最小金額](https://docs.stripe.com/billing/scripts/stripe-authored/customer-balance.md#minimum-amount-before-collection) | このスクリプトを使用すると、支払義務のある合計額が定義したしきい値に達するまで顧客残高に繰り越すことで、少額の請求書の回収を回避できます。回収前に複数の請求サイクルにわたって請求額を累計したい場合や、顧客への少額請求を回避したい場合に使用します。 |
| 単一の請求に適用するクレジットの最大額を設定します。 | 顧客残高 | [請求書あたりの最大クレジット](https://docs.stripe.com/billing/scripts/stripe-authored/customer-balance.md#maximum-credit-per-invoice) | このスクリプトは、クレジットを一度にすべて適用するのではなく複数の請求サイクルに分散したい場合や、事業ルール上、請求書ごとのクレジット利用額を制限する必要がある場合に使用します。 |
| 従量課金項目とライセンス項目を別々の請求書に分けます。 | 請求書項目の作成とルーティング | [従量課金項目用の別請求書](https://docs.stripe.com/billing/scripts/stripe-authored/invoice-item-creation-and-routing.md#separate-invoice-for-metered-items) | このスクリプトは、財務チームが継続的なシート料金やライセンス料金とは別に使用量料金を照合する必要がある場合や、顧客がそれぞれについて別の請求書を想定している場合に使用します。 |
| 比例配分を時間、日、週、または月単位で計算します。 | 比例配分 | [カスタム間隔での比例配分](https://docs.stripe.com/billing/scripts/stripe-authored/proration.md#prorate-by-custom-interval) | このスクリプトは、地域の請求慣習に合わせるため、契約条件に準拠させるため、または端数金額によって生じる顧客の混乱を減らすためなど、ビジネスにおいて秒単位より大きい単位で比例配分を計算する必要がある場合に使用します。 |
| サブスクリプションに含まれる一部の項目の全額返金または全額請求を行います。 | 比例配分 | [商品価格の全額をクレジットおよびデビット](https://docs.stripe.com/billing/scripts/stripe-authored/proration.md#credit-and-debit-full-product-price) | このスクリプトは、サブスクリプション上の特定の製品が比例配分されない場合に使用します。たとえば、サブスクリプションがいつ変更されたかに関わらず、常に全額が請求される定額のサポート手数料やプラットフォーム利用料などです。 |
| 上限額を指定して定率割引を適用します。 | 割引計算 | [上限額付き定率割引](https://docs.stripe.com/billing/scripts/stripe-authored/discount-calculation.md#percent-off-up-to-maximum) | このスクリプトを使用すると、請求書に対する割引額の上限を設けながら、定率割引を提供できます。 |
| 選択した商品の数量を無料で提供します。 | 割引計算 | [BOGO および数量プロモーション](https://docs.stripe.com/billing/scripts/stripe-authored/discount-calculation.md#bogo-and-quantity-promos) | このスクリプトは、メタデータで選択された商品に対する数量ベースのプロモーションに使用します。 |
| 選択した価格に定額割引を適用します。 | 割引計算 | [価格指定の定額割引](https://docs.stripe.com/billing/scripts/stripe-authored/discount-calculation.md#price-targeted-amount-off) | このスクリプトを使用すると、関係のない請求書項目を割り引くことなく、メタデータで選択された価格に定額割引を適用できます。 |
| 選択した価格に定率割引を適用します。 | 割引計算 | [価格指定の定率割引](https://docs.stripe.com/billing/scripts/stripe-authored/discount-calculation.md#price-targeted-percent-off) | このスクリプトを使用すると、関係のない請求書項目を割り引くことなく、メタデータで選択された価格に定率プロモーションを適用できます。 |

#### 制限事項

ほとんどの [TypeScript](https://www.typescriptlang.org/docs/handbook/intro.html#get-started) 機能は Stripe のランタイムで動作しますが、次のパターンは使用できません。ビルドとアップロードのステップで、これらは自動的に検出されます。

- `eval()` や `new Function()` などのコード評価
- `setTimeout()`、`setInterval()`、`setImmediate()` などのタイマー関数
- `global` または `globalThis` を使用したグローバルスコープへのアクセス
- `process.exit()` や `process.env` などのプロセス API
- `console.log()`。スクリプトの実行ログを表示するには、[ワークベンチ](https://docs.stripe.com/workbench.md) を使用します。
- API キーやシークレットを埋め込まないでください。機密性の高い値は [Stripe secret store](https://docs.stripe.com/stripe-apps/store-secrets.md) で管理してください。
- `fetch()` などのネットワークアクセス API。[スクリプトからエンドポイントを呼び出す](https://docs.stripe.com/extensions/invoke-endpoints.md)には、`endpointFetch()` を使用します。

現在、Stripe はサードパーティーのライブラリを依存関係としてサポートしていません。

### リモート関数

リモート関数は、独自のインフラストラクチャでホストする HTTP エンドポイントです。拡張ポイントに到達すると、Stripe からエンドポイントが呼び出され、各リクエストに [Webhook 署名](https://docs.stripe.com/webhooks.md#verify-signature)が付与されるため、そのリクエストが Stripe から送信されたことを検証できます。

コードから外部サービスを呼び出す際の認証は、開発者側で管理します。Stripe はリモート関数にシークレットを注入しません。受信する Stripe の署名を検証し、送信時の認可も開発者側で処理します。

次のような場合にリモート関数を使用します。

- 自社サーバーまたは自社環境でロジックを実行できます
- ERP や CRM などの自社システムと連携できます
- TypeScript 以外の言語を使用できます

#### 制限事項

現在、リモート関数には以下の制限があります。

- ホスティング、可用性、デプロイはユーザー側が管理します。
- エンドポイントは、拡張ポイントで定義されたタイムアウト以内に応答する必要があります (たとえば、カスタムアクションでは 20 秒)。

### UI 拡張

Stripe ダッシュボード内に表示される React コンポーネントです。UI 拡張機能を使用すると、Stripe ダッシュボードのユーザーにカスタム UI を表示できます。 [UI 拡張機能](https://docs.stripe.com/stripe-apps/how-ui-extensions-work.md)を参照してください。

## 権限

拡張機能を構築する際には、拡張機能に必要な権限を宣言する必要があります。拡張機能は、読み取りまたは書き込みの権限が付与されたデータにのみアクセスできます。拡張機能のユーザーは、拡張機能を含むアプリをインストールする際にこれらの権限を付与します。すべての[権限](https://docs.stripe.com/stripe-apps/reference/permissions.md)の一覧をご覧ください。

## 連結アカウント

設定された拡張機能は連結アカウントには適用されません。連結アカウントは、インストール済みアプリで拡張機能を個別に設定する必要があります。

## ライフサイクル

拡張機能のライフサイクルは次のように進みます。バージョン管理、公開、非推奨化、アーカイブは任意です。

1. **構築**: Stripe アプリ内で拡張機能を構築します。
2. **アップロード**: Stripe CLI を使用してアプリをアップロードします。Stripe がアプリを処理し、インストールできるようにします。
3. (オプション)** バージョン管理**: 開発を進めながら、新しいバージョンをアップロードします。
4. (オプション)** 公開**: [外部テストチャネル](https://docs.stripe.com/stripe-apps/test-app.md)または [Stripe App Marketplace](https://docs.stripe.com/stripe-apps/publish-app.md) を通じてアプリを共有できます。共有したアプリは、相手のアカウントにインストールできるようになります。
5. **インストール**: ユーザーまたはアプリの共有先がインストールし、関連する権限を受け入れます。
6. **有効化**: アプリのユーザーが拡張ポイントで拡張機能を有効化します。
7. **呼び出し**: Stripe は、拡張ポイントに到達するたびに、有効化された拡張機能を呼び出します。
8. (任意) [非推奨化](https://docs.stripe.com/extensions/manage-extension-lifecycle.md): アプリユーザーは拡張機能の特定のバージョンを有効化できなくなりますが、そのバージョンですでに有効化された拡張機能は引き続き実行されます。
9. (任意) [アーカイブ](https://docs.stripe.com/extensions/manage-extension-lifecycle.md): 有効化された拡張機能は、互換性のあるバージョンに移行されるか、バージョンが指定されていない場合は実行できなくなります。
10. **無効化**: アプリのユーザーが拡張機能を無効化します。アカウントには残りますが、拡張ポイントに到達すると Stripe から呼び出されなくなります。
11. **アンインストール**: アプリのユーザーがアカウントからアプリとその拡張機能を削除します。

## 構築を開始

請求のカスタマイズについては、まずステップバイステップガイド[請求スクリプト拡張機能の作成](https://docs.stripe.com/extensions/scripts/build-prorations-extension.md)を参照してください。前提条件、アプリの作成、CLI コマンド、アップロードについて説明しています。

それ以外の場合は、どの拡張ポイント向けに構築するかによって、参照するガイドが異なります。

- 顧客残高、項目処理、または比例配分の動作をカスタマイズするには、[Billing スクリプト拡張機能を作成](https://docs.stripe.com/extensions/scripts/build-prorations-extension.md)します。
- [スクリプトを使用してカスタムワークフローアクションを作成](https://docs.stripe.com/extensions/custom-actions/build-with-script.md)するか、[リモート関数](https://docs.stripe.com/extensions/custom-actions/build-with-remote-function.md)を使用します。[カスタムアクションの仕組み](https://docs.stripe.com/extensions/custom-actions/how-custom-actions-work.md)の詳細をご確認ください。

利用可能な拡張ポイントとサポートされる実装タイプの完全な一覧については、[拡張ポイント](https://docs.stripe.com/extensions/extension-points.md)をご覧ください。