GET /checkout/sessions における簡略化レスポンススキーマの問題点整理

[reiroop]

GET /checkout/sessions における簡略化レスポンススキーマの問題点整理

解決したい課題

現在定義されている GetCheckoutSessionsResponse のスキーマは、Stripe の物理的な Checkout Session オブジェクトから一部の属性を抽出した簡略化スキーマになっています。

この設計は「1回の決済につき1商品」という特定の前提に依存しており、商品ID（product_id）がフラットに定義されているなど、Stripe API の本来のデータモデル（1:N の line_items リスト構造）と乖離しています。このため、将来的な複数商品の一括決済や請求項目の多様化に安全に対応できず、拡張性が欠如しています。また、決済された具体的な価格プランを特定するための価格ID（price）の取得も不可能になっています。

将来の検討・対応事項 (TODO)

将来的に決済履歴（GET /checkout/sessions）の拡張が必要になった際、以下のいずれかのアプローチを評価・選択して実装を行います。

• アプローチA：Stripe API スキーマのサブセット（部分スキーマ）を手動で定義する
  • 本システムに必要な主要プロパティに絞り込んだ部分定義スキーマを定義し、OpenAPI ファイルの肥大化を防ぎつつ、拡張性をカバーするアプローチ。
• アプローチB：Stripe の公式 OpenAPI 仕様書から定義を部分インポートする
  • フィルタリングツール等を活用し、Stripe の公式 Checkout Session / LineItem などのリソース定義そのものを同期・インポートして完全な物理仕様を採用するアプローチ。