# ワークフローの仕組み ワークフローの機能とコンポーネントについて説明します。 [Stripe ダッシュボード](https://dashboard.stripe.com/workflows)には Workflows のビジュアルビルダーが用意されており、順番に実行される一連のアクションを定義することで、タスクやプロセスを自動化できます。Workflows は複数ステップのプロセスに最適で、複数の Stripe プロダクト間で互換性があるため、プロセスの合理化、ビジネスルールの適用、手作業の削減が可能になります。 各ワークフローは、トリガーと、順番に実行される一連のステップで構成されます。ステップは、アクションまたは条件のいずれかです。ワークフローは、次のコンポーネントで構成されています。 | **コンポーネント** | **説明** | | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [トリガー](https://docs.stripe.com/workflows/define-workflows.md#triggers) | ワークフローを開始する特定の Stripe イベントまたはプログラムによる呼び出し。各ワークフローには 1 つのトリガーがあります。トリガー条件により、ワークフローを開始するイベントがフィルタリングされますが、これらはステップとしてはカウントされません。 | | **ステップ** | ワークフローのステップは、アクションまたは条件のいずれかです。各ワークフローには、最大 12 のステップ (アクションまたは条件) を含めることができます。 | | [アクション](https://docs.stripe.com/workflows/define-workflows.md#actions) | 決済の返金やメールの送信など、ワークフローがトリガーされた後に実行される自動タスクです。各アクションは 1 ステップとしてカウントされます。ループ内のアクションは、反復ごとに 1 回カウントされます。 | | [条件](https://docs.stripe.com/workflows/define-workflows.md#conditions) | データに基づいてワークフローの進行方法を決定する制御フローです。条件は分岐パスを作成しますが、ステップ数にはカウントされません。カウントされるのは、各分岐内のアクションのみです。 | | [ループ](https://docs.stripe.com/workflows/define-workflows.md#loops) | Stripe オブジェクトのコレクションを反復処理する for-each 構文です。ループ自体はステップとしてカウントされず、ループ本体内のアクションのみが、反復ごとに 1 回カウントされます。詳細は、[コレクションをループ処理する](https://docs.stripe.com/workflows/loops.md)をご覧ください。 | ワークフローは、トリガーと条件に基づいて一連のアクションを順番に実行することで、タスクを自動化します。複数のワークフローが同じトリガーイベントを共有する場合、各ワークフローは、独自に定義されたステップとビジネスロジックに従って独立して実行されます。 ## アクティブなワークフローと非アクティブなワークフロー ワークフローは、有効化、無効化、または削除できます。ワークフローを無効化すると、Stripe はそのワークフローを無効と見なし、トリガーに応答できなくなります。無効なワークフローはいつでも再有効化できます。一度に維持できる有効なワークフローは最大 50 で、有効 / 無効の合計も最大 50 です。 ワークフローが 50 個ある場合、別のワークフローを作成できません。有効なワークフローが 50 個ある状態で新しいワークフローを有効化するには、まず既存の有効なワークフローを無効化する必要があります。 ## バージョン管理 ワークフローを有効化するたびに、Stripe はその設定の番号付きバージョンを保存します。各バージョンに変更の理由を説明する注釈を付けることもできます。 これにより、チーム全体の更新履歴について、明確で共有された記録が時間とともに蓄積されます。ワークフロー自体が、文脈情報の一元的な保管場所になります。 ワークフローの履歴で過去のすべてのバージョンを表示できます。 以前のバージョンに戻す必要がある場合は、設定を Workflow Editor に復元して再度アクティブ化できます。 ## 下書き 下書きモードでは、アクティブなワークフローを編集するための独立したワークスペースが提供されます。下書きモードを使用するには、エディターで **下書きを保存** をクリックします。 この機能を使用すると、本番バージョンに影響を与えることなく、条件の変更、ステップの追加、ブランチの再編成を行うことができます。反復プロセスを本番ロジックから分離することで、導入前に安全かつ自分のペースでワークフローを改善できます。 ## トリガー Workflows は、Stripe API イベントまたはプログラムによる呼び出しによって開始されます。各ワークフローにはトリガーが 1 つあり、常にワークフローの最初のステップになります。トリガーはワークフローにデータを提供します。データは、イベントペイロード (イベントに基づくトリガーの場合) またはカスタム入力データ ([プログラムによるトリガー](https://docs.stripe.com/workflows/programmatic-triggers.md)の場合) のいずれかです。このデータはワークフローに渡されるため、後続のステップで使用できます。トリガーが実行されてデータが提供されると、ワークフローはそのデータを使用してアクションを実行します。 顧客に関連するワークフローを発生させる場合は、次のトリガーを適用できます。 | **トリガー** | **説明** | | -------------------------------------------------------------------------------------- | ------------------------------------ | | [顧客が作成されました](https://docs.stripe.com/api/events/types.md#event_types-customer.created) | 新しい顧客が作成されたときに発生します | | [顧客更新情報](https://docs.stripe.com/api/events/types.md#event_types-customer.updated) | メールアドレスやメタデータなど、顧客の詳細が変更されたときに発生します。 | Stripe を使用して決済 ([Stripe Checkout](https://docs.stripe.com/payments/checkout.md) や CheckoutSessions API など) を受け付けている場合、次のトリガーを適用できます。 | **トリガー** | **説明** | | ------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Checkout セッションが完了しました](https://docs.stripe.com/api/events/types.md#event_types-checkout.session.completed) | 顧客が決済プロセスを正常に完了したときに送信されます。これは、決済が正常に処理され、必要な顧客情報、決済情報、注文情報が収集されたことを示します。トランザクションが想定どおりに完了し、[設定に応じて](https://docs.stripe.com/checkout/fulfillment.md?payment-ui=embedded-page#immediate-versus-delayed-payment-methods)資金をキャプチャーする準備が整っているか、すでにキャプチャーされていることを確認するものです。 | | [Checkout セッションの期限が切れています](https://docs.stripe.com/api/events/types.md#event_types-checkout.session.expired) | Checkout セッションが完了せずに期限切れになり、取引が起こらなくなったときに発生します。デフォルトでは、セッションは作成後 24 時間で期限切れになります。 | | [支払いインテントが失敗しました](https://docs.stripe.com/api/events/types.md#event_types-payment_intent.payment_failed) | 処理中のいずれかの時点で決済の試行が失敗したときに発生します。原因としては、カードの有効期限切れ、残高不足、認証の失敗、その他の問題などが考えられます | | [支払いインテントが成功しました](https://docs.stripe.com/api/events/types.md#event_types-payment_intent.succeeded) | 認証 (3D セキュア)、オーソリ、売上キャプチャーなど、決済が完全に完了すると発生します。これは決済ライフサイクル全体を表し、確認および完了した決済に依存するワークフローに最適です。これは、決済が成功する最も一般的なトリガーです | | [請求書の支払いに失敗しました](https://docs.stripe.com/api/events/types.md#event_types-invoice.payment_failed) | 多くの場合、カードの有効期限が切れていたり、残高が不足していたりして、顧客の請求書の支払いに失敗したときに発生します。 | Stripe を使用して、[銀行振込](https://docs.stripe.com/payments/payment-methods/overview.md#bank-transfers)や [BNPL](https://docs.stripe.com/payments/payment-methods/overview.md#buy-now-pay-later) (支払いの詳細を確認するためにさらに時間がかかる) などの非同期の決済手段を受け付けている場合、次のトリガーを適用できます。 | **トリガー** | **説明** | | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | | [非同期決済セッションの支払いに失敗しました](https://docs.stripe.com/api/events/types.md#event_types-checkout.session.async_payment_failed) | 口座振替などの遅延型の決済手段が失敗した場合に発生します。企業はこのイベントを利用して、顧客への通知や支払いの再試行などのアクションを実行し、ユーザーエラーや残高不足などの問題に対処できます。 | | [非同期決済セッションの支払いに成功しました](https://docs.stripe.com/api/events/types.md#event_types-checkout.session.async_payment_succeeded) | 口座振替などの遅延型の決済手段が成功し、十分な残高や本人確認などの条件が満たされていることが確認された場合に発生します。一部のビジネスでは、注文をすぐにフルフィルメントし、決済に失敗した場合は後でアクセスを取り消す場合があります。 | 資金移動の結果、または支払いの成否に基づいてワークフローをトリガーする場合は、次のトリガー条件を適用できます。ほとんどの Stripe システムでは、支払いイベントを直接リッスンする代わりに、Checkout イベントまたは PaymentIntent イベント (例: [Checkout セッションが完了しました](https://docs.stripe.com/api/events/types.md#event_types-checkout.session.completed)) が使用されます。 | **トリガー** | **説明** | | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | | [支払いに失敗しました](https://docs.stripe.com/api/events/types.md#event_types-charge.failed) | 顧客の支払い方法への請求が失敗したときに発生します。支払いとは、お金の移動の試みを表します。このイベントは、支払いインテントのライフサイクルの一部として発生することがあります (たとえば、支払いが支払いステージで失敗した場合など)。 | | [支払いに成功しました](https://docs.stripe.com/api/events/types.md#event_types-charge.succeeded) | 支払いが正常に処理されたときに発生します。これにより、支払いが承認され、キャプチャーされたことが確認され、入金スケジュールに従って顧客のカードからお客様のアカウントに売上が移動したことを確認できます。 | ### サポートされているトリガー ワークフローは、Stripe [v1](https://docs.stripe.com/api/events/types.md) と [v2](https://docs.stripe.com/api/v2/core/events.md) の両方のトリガーとしてほとんどのイベントをサポートします。サポートされていないイベントは、ダッシュボードでは使用できません。 ### 連結アカウントのイベント [Connect](https://docs.stripe.com/connect.md) を使用している場合は、プラットフォームアカウントではなく、連結アカウントのイベントでトリガーされるようにワークフローを設定できます。トリガーを作成または編集するときに、ワークフローでプラットフォームアカウントのイベントを監視するか、連結アカウントのイベントを監視するかを選択します。 ワークフローは、プラットフォームアカウントまたは連結アカウントのいずれか一方、1 つのソースからのイベントを監視します。両方に同じワークフローロジックが必要な場合は、イベントソースごとに個別のワークフローを作成します。 ワークフローが連結アカウントのイベントによってトリガーされると、連結アカウント ID はワークフロー全体でコンテキストとして使用できます。後続のアクションでこの ID を参照して、その連結アカウントのリソースを操作できます。 ### プログラムによるトリガー ダッシュボードから、または API を通じてカスタム入力データを使用して、オンデマンドでワークフローをトリガーできます。プログラムによるトリガーは、人がプロセスを開始する必要がある場合や、外部システムが Stripe のロジックを呼び出す必要がある場合に便利です。詳細は、[プログラムでワークフローをトリガーする](https://docs.stripe.com/workflows/programmatic-triggers.md)をご覧ください。 ## アクション アクションは、トリガーまたは前のステップからのデータに基づいて自動的に実行されるタスクです。すべてのワークフローには少なくとも 1 つのアクションが必要で、ほとんどのワークフローには複数のアクションが順次含まれています。 一般的なアクションには、次のようなものがあります。 - [顧客を更新する](https://docs.stripe.com/api/customers/update.md): 追跡やレポート作成の目的でメタデータフィールドを使用してカスタムデータを追加するなど、既存の顧客の詳細を変更します。 - [請求書を取得する](https://docs.stripe.com/api/invoice-payment/retrieve.md): ステータスなど、特定の請求書の最新の詳細を取得します。これは通常、請求書の更新や現在の状態に基づく意思決定など、後のステップで使用されるデータを収集するために使用されます。 - [サブスクリプションを取得する](https://docs.stripe.com/api/subscriptions/retrieve.md)を参照してください。プランや請求サイクルなど、顧客のサブスクリプションの最新の詳細を取得します。これは通常、サブスクリプションの更新や条件ロジックの適用など、後のステップで使用するサブスクリプションデータを収集するために使用されます。 - [サブスクリプションを更新する](https://docs.stripe.com/api/subscriptions/update.md): プランの変更、請求サイクルの更新、割引の適用など、アクティブなサブスクリプションを変更します。 ワークフローステップは、トリガーイベントの後に開始され、順番に実行されます。各ステップは、動的フィールドを使用して、トリガーおよび前のステップからの情報にアクセスできます。これらのフィールドはスマートプレースホルダーとして機能し、ワークフローの進行に合わせてリアルタイムのデータが自動的に入力されます。このシステムにより、各ステップがワークフローを流れるデータに適応し、柔軟で応答性の高いワークフローが可能になります。 アクションは、アクションが実行された時点でのオブジェクトの最新の状態に対して動作します。つまり、最初のトリガーと後続のアクションの間にオブジェクトが変更された場合、アクションはオブジェクトの最新バージョンに影響します。ただし、動的参照は、最後に取得された時点のオブジェクトの状態を使用します。 ### サポートされているアクション Workflows は、Stripe [v1](https://docs.stripe.com/api.md) と [v2](https://docs.stripe.com/api/v2.md) の両方のほとんどの API アクションに対応しています。対応していないアクションはダッシュボードでは使用できません。 リストアクション (たとえば、顧客をリストする、サブスクリプションをリストする、請求書をリストするなど) はループ内で使用できます。リストアクションは、ループが反復処理するコレクションを返します。詳細は、[コレクションをループ処理する](https://docs.stripe.com/workflows/loops.md)をご覧ください。 ### 連結アカウントに対するアクション ワークフローが連結アカウントのイベントでトリガーされると、アクションは連結アカウントのリソースに対して実行されます。ワークフローは、`Stripe アカウント`ヘッダーを、イベントをトリガーした連結アカウントに設定して API コールを送信します。 各アクションは、次のいずれかのコンテキストで動作するように設定できます。 - **プラットフォームアカウント**: アクションはプラットフォームアカウントに対して実行されます (デフォルトの動作) - **連結アカウント**: アクションは、`Stripe アカウント`ヘッダーを使用して、ワークフローをトリガーした連結アカウントに対して実行されます すべての連結アカウントに同じ権限があるわけではありません。連結アカウントにアクションの権限がない場合、実行時にアクションは失敗し、権限エラーが返されます。 アクションは、プラットフォームと連結アカウントの両方のリソースに対して実行できます。Connect のトリガーとアクションの設定の詳細については、[Connected account events](https://docs.stripe.com/workflows/define-workflows.md#connected-account-events) をご覧ください。 ### ワークフローに固有のアクション 以下はワークフローに固有のアクションであり、ダッシュボードのビジュアルビルダーを使用してのみ使用でき、パブリック API の一部ではありません。 | **アクション** | **説明** | **目的** | **結果** | **例** | | -------------------- | ------------------------------------- | ------------------------------------------- | ------------------------- | ---------------------------------------------- | | **チームメンバーにメールを送信する** | Stripe アカウントに関連付けられている内部メールを生成して送信します | ワークフローがトリガーされ、特定の条件が満たされた後に内部チームメンバーに通知するため | ワークフローが実行されると、チームに通知が届きます | 顧客の合計支出額が 1,000 USD を超える場合は、社内チームに通知メールを送信します。 | ## 条件 条件を使用すると、ワークフローにロジックを追加して、ワークフローを続行するかどうか、およびどのように処理すべきかを制御するルールを定義できます。条件は、通常、トリガーまたはそれ以前のステップからのデータを評価するチェック機構です。使用方法に応じて、条件によって、ワークフローを実行するかどうか、続行するかどうか、またはどのパスをたどる必要があるかが決まります。使用できる条件は、ワークフローが参照する予定のデータによって異なります。 ### トリガー条件 トリガー条件は、ワークフローを開始するイベントを絞り込みます。ワークフローは、トリガー条件が true の場合にのみ実行されます。これらは、ワークフローを特定のユースケースに絞り込む場合 (たとえば、特定の金額を超える支払いが成功した場合にのみワークフローを実行する、など) に便利です。その主な目的は、ワークフローを実行する必要があるかどうかを判断することです。 ![トリガー条件](https://b.stripecdn.com/docs-statics-srv/assets/trigger-condition.b9ed9f06218d15b81ea93e33f98583f3.png) ダッシュボードでのトリガー条件の設定 仕組みは以下のとおりです。 1. Stripe アカウントでイベントが発生します。 1. トリガー条件は、このイベントが特定の基準を満たしているかどうかをチェックします。 1. 条件が満たされると、ワークフローが開始されます。満たされない場合、何も起こりません。 1 つの条件を作成して、1 つのトリガーに適用できます。以下に例を挙げます。 | | | | | **トリガー** | 請求書が作成される | | **トリガー条件** | 請求書のステータスは確定済みに *一致* します。すなわち、請求書は変更できなくなっています。 | | **結果** | 「ワークフローは、確定された請求書に対してのみ実行されます。 | また、複数の条件を作成してトリガーに適用することもできます。以下に例を挙げます。 | | | | | **トリガー** | 支払いに失敗しました | | **トリガー条件** | 支払い金額は 100 USD を *超過* しています。 | | **トリガー条件** | 最後の支払いエラーコードは残高不足に「一致」します。 | | **結果** | このワークフローは、残高不足が原因でエラーコードが発生した 100 USD を超える支払いの失敗に対してのみ実行されます。 | 条件は、ワークフローを特定の状況に絞り込むのに役立ち、ワークフローの精度を調整するのに役立ちます。 ### ステップとしての条件 トリガー条件に加えて、ワークフロー内に条件ステップを追加できます。これらの条件ステップにより、ワークフロー開始後の動作を制御できます。 たとえば、特定の条件が満たされているかどうかをチェックし、ワークフローを続行する必要があるかどうかを判断するための条件を、ステップとしてワークフローに追加できます。条件ステップを追加することで、値を評価し、続行するかどうかを決定できます。条件が true の場合、ワークフローは次のステップに進みます。ただし、false の場合、ワークフローは停止し、成功としてマークされます。このアプローチを使用して、アクション完了後に結果を確認します。 ### 分岐条件 条件ステップの別の例は、条件を分岐として使用することです。これにより、ワークフロー内に決定ポイントを導入し、指定した条件に基づいて複数のパスに分岐させることができます。条件ステップから複数のパスを構築して、ワークフローがさまざまなパスをたどり、さまざまな条件に基づいてさまざまなアクションを実行するようにできます。このアプローチは、顧客の国や購入金額に基づいて異なるメールをアカウントチームごとに送信するなど、複数のシナリオを処理する場合に使用します。 #### 2 つの分岐を作成する条件の例: | | | | | **トリガー** | 顧客が作成されました | | **アクション** | 条件を追加します。 - 条件に当てはまる場合 (顧客の住所の国が `US` または `CA` である場合)。 - 条件に当てはまらない場合 (顧客の住所が `US` または `CA` 以外である場合)。 | | **アクション** | 次の条件が true の場合、顧客のメタデータを更新して、北米の店舗 (メタデータ キー: `店舗`と値: `北米`) を割り当てます。 | | **アクション** | 次の条件が false の場合: 顧客のメタデータを更新して、グローバルの店舗 (メタデータ キー: `店舗`、値: `グローバル`) を割り当てます。 | | **結果** | このワークフローでは、条件ステップを使用して顧客の国を確認し、異なるパスに振り分けます。各パスには、顧客のメタデータを地域固有のラベルで更新するアクションが含まれており、レポートやロジックなどのダウンストリームで使用することが可能です。 | 条件を追加して、2 つ以上の分岐を作成することもできます。これにより、ワークフローは 1 つの決定ポイントから複数のシナリオを処理できます。 #### 3 つの分岐を作成する条件の例: | | | | | **トリガー** | 顧客が作成されました | | **アクション** | 条件を追加します。 - 顧客の住所の国が `US` または `CA` の場合。 - 顧客の住所の国が `FR`、`DE`、または `IT` の場合。 | | **アクション** | 次の条件が true の場合、顧客のメタデータを更新して、北米の店舗 (メタデータ キー: `店舗`と値: `北米`) を割り当てます。 | | **アクション** | 次の条件が true の場合、顧客のメタデータを更新して、ヨーロッパの店舗 (メタデータ キー: `店舗`と値: `ヨーロッパ`) を割り当てます。 | | **アクション** | どちらの条件にも当てはまらない場合:顧客のメタデータを更新して、グローバルの店舗を割り当てます(メタデータ キー:`店舗`、値:`グローバル`)。 | | **結果** | このワークフローでは、条件ステップを使用して顧客の国を確認し、異なるパスに振り分けます。各パスには、顧客のメタデータを地域固有のラベルで更新するアクションが含まれており、レポートやロジックなどのダウンストリームで使用することが可能です。 | 各条件は、ビジュアルビルダーで左から右の順に評価されます。ワークフローは、最初に一致したパスをたどり、他のパスはスキップします。トリガー条件は、ワークフローを実行する必要があるかどうかを決定します。条件ステップは、ワークフローの開始後の動作を制御し、続行するか、別のパスに分岐するかを決定します。 多くの場合、トリガーごとまたはステップごとに同じ条件ロジックが適用されます。条件を適用する場所は、制御する内容、ワークフローを開始する必要があるかどうか、開始後に続行する必要があるかどうか、または実行中にどのパスをたどる必要があるか、によって異なります。 ## ループ ループを使用すると、Stripe オブジェクトのコレクションを反復処理し、各項目に対して一連のアクションを実行できます。たとえば、顧客のすべてのサブスクリプションをループ処理して、それぞれのメタデータを更新できます。 ループを追加するには、ワークフロービルダーで for-each ステップを選択します。ループはコレクションを入力として受け取り (通常は一覧表示 API アクションの結果)、ループ本体内のアクションを項目ごとに 1 回実行します。 ループの設定、対応するコレクション、失敗時の処理、および制限の詳細については、[Loop over collections](https://docs.stripe.com/workflows/loops.md) を参照してください。 ## カスタムアクション カスタムアクションは、ワークフロービルダーで組み込みの Stripe アクションとともに表示される、ユーザー定義のアクションです。アプリ開発者は、`extend.workflows.custom_action` 拡張インターフェイスを使用してカスタムアクションを構築します。 カスタムアクションは、Stripe のサンドボックスで実行される TypeScript スクリプトとして、または独自の HTTP エンドポイントを呼び出すリモート関数として実装できます。ドロップダウン、条件付きフィールド、バリデーションなどの動的な設定に対応しています。 カスタムアクションの構築とデプロイの詳細については、[カスタムアクションを作成する](https://docs.stripe.com/workflows/custom-actions.md)を参照してください。 ## See also - [ユースケース](https://docs.stripe.com/workflows/use-cases.md) - [ワークフローを設定](https://docs.stripe.com/workflows/set-up.md) - [コレクションの反復処理](https://docs.stripe.com/workflows/loops.md) - [カスタムアクションの作成](https://docs.stripe.com/workflows/custom-actions.md) - [プログラムでワークフローをトリガーする](https://docs.stripe.com/workflows/programmatic-triggers.md)