# 請求書スクリプト

スクリプトを使用して、Stripe で直接実行されるカスタムの請求ロジックをプログラムします。

[Typescript のサブセット](https://docs.stripe.com/billing/scripts/script-language.md)を使用すると、Stripe でカスタムロジックを記述して送信できます。スクリプトを使用して、次のことが可能になります。

- 特定の Stripe オブジェクトに対して独自のロジックを定義する
- 特定のビジネスニーズに合わせて Stripe アカウントをカスタマイズする
- Stripe を標準機能を超えて拡張する

たとえば、スクリプトを使用して[新しいクーポンにカスタム割引ロジックを作成](https://docs.stripe.com/billing/subscriptions/script-coupons.md)し、そのクーポンをサブスクリプションと請求書に適用できます。

## スクリプトのライフサイクル

スクリプトの使用方法については、次のスクリプトのライフサイクルを参照してください。

- まず、サポートされているユースケースのカスタムロジックを作成します。
- スクリプト作成の一環として、構成値を定義できます。これらは、スクリプトユーザがカスタムオブジェクトの作成時に渡すパラメータです。
- レビューのためにスクリプトを送信した後、Stripe はそのスクリプトをスクリプトサービスに登録します。
- その後、`Coupon` オブジェクトや `Subscription` オブジェクトなどのオブジェクトを作成するときにスクリプトを呼び出すことができます。

## 関数の引数

関数の引数は、次の 2 つのカテゴリーに分類できます。

### 作成者が定義した値

作成者が定義した値は、次の 2 つを対象としている考えることができます。

- **スクリプト作成者**: スクリプト作成者は、関数 (つまり、実際のロジック) と関数への入力値を定義します。たとえば、スクリプト作成者が 2 つの入力値 (`percent` と `maximum`) を定義する “percent-up-to-a-maximum” スクリプトを作成できます。

- **スクリプトユーザー**: スクリプト作成者が値を定義した後、スクリプトユーザーはダッシュボードまたは API を介して 2 つの入力の値を定義できます (たとえば、最大 100 USD の 10% オフ)。

スクリプト作成者は、スクリプトのどの部分をスクリプト ユーザー向けにカスタマイズ可能にするかを決定します。その後、スクリプトユーザーは、スクリプトのカスタマイズ可能な部分に独自の値を適用します。

```typescript
export type scriptConfiguration = {
  max_discount_amount: {
    amount: number;
    currency: string;
  },
  discount_percent: number;
};
```

[SDK](https://github.com/stripe/scripts/blob/main/src/types.ts) には、構成定義の一部として使用できる組み込み型が用意されています。これらの組み込み型は、ダッシュボードの関連する入力フィールド UI でレンダリングされます。新しい組み込み型に関する提案がありましたら、[scripts-preview@stripe.com](mailto:scripts-preview@stripe.com) またはサポートチームまでご連絡ください。

```typescript
import type {PositiveMonetaryAmount, Percent} from '@stripe/scripts';

export type scriptConfiguration = {
  max_discount_amount: PositiveMonetaryAmount;
  discount_percent: Percent;
};
```

構成値には、スクリプトユーザーが値を設定しようとしたときのデフォルトのスキーマ検証があります。さらに、[スキーマ検証](https://docs.stripe.com/billing/scripts/script-language.md#schema-validation)を参照してカスタム検証を定義できます。検証のユースケースをサポートできない場合は、検証チェックを関数定義に組み込んで、[scripts-preview@stripe.com](mailto:scripts-preview@stripe.com) に問い合わせることをお勧めします。

### Stripe 定義の値

Stripe は、`Customer`オブジェクトや`DiscountableLineItem`オブジェクトなど、カスタマイズできない引数値を関数の実行時に提供します。具体的なオブジェクトは、関数インターフェイスによって異なります。必要なデータが不足している場合は、[scripts-preview@stripe.com](mailto:scripts-preview@stripe.com)にお問い合わせください。

また、現在の実行コンテキスト (実行中のアカウント、本番環境かどうか、現在のクロック時間など) を提供する `RunContext` オブジェクトを関数に渡します。これは、関数の最初の引数として使用できます (例: `context: RunContext`)。

```typescript
export interface RunContext {
  account_id: string;
  livemode: boolean;
  clock_time: Date;
}
```

```typescript
/**
 * DiscountableLineItem data structure
 *
 * @typedef {Object} DiscountableLineItem
 * @property {MonetaryAmount} subtotal
 * @property {number | null} quantity
 * @property {TimeRange} period
 * @property {Price | null} price
 */
export interface DiscountableLineItem {
  subtotal: MonetaryAmount;
  quantity?: number | null;
  period: TimeRange;
  price?: Price | null;
}
```

## 関数ロジック

スクリプト作成者は、スクリプト関数ロジックで使用されるカスタマイズを定義します。すべての引数は「値渡し」であり、関数内で引数値を変更しても、関数外の元の値には影響しません。

### 実行時エラーを適切に処理する

ほとんどの場合、エラーをキャッチし、フォールバック動作を行います。まれに、例外をスローすることがあります。例外をスローすると、スクリプトに関連付けられているコードの実行全体が停止するため、他のオプションが存在しない場合にのみ例外をスローします。

### テストを書く

スクリプト関数に自動テスト一式の使用を義務付けてはいませんが、Stripe ではそれを推奨しています。テストは、サンドボックス環境またはテストモードに対して書くことができます。もしガイダンスが必要であれば、[scripts-preview@stripe.com](mailto:scripts-preview@stripe.com) にご連絡ください。

### 関数の戻り値

関数の戻り値は、カスタマイズによって異なるインターフェイスに従う必要があります。特定のインターフェイス定義については [SDK](https://github.com/stripe/scripts) を参照し、関数がインターフェイスに準拠していることを確認します。

## See also

- [スクリプトクーポン](https://docs.stripe.com/billing/subscriptions/script-coupons.md)