Stripe: 技術リファレンス#

#目的

これは、主なStripeコネクタのドキュメントの技術的な補助資料です。認証の内部、完全なエンドポイントリファレンス、ページネーション、レート制限、出力形式、制限など、コネクタをデータパイプラインに統合するために必要なすべての内容をカバーしています。

#認証

#方法

Stripe Secret APIキーを使用したベアラートークンです。

Authorization: Bearer sk_test_XXXXXXXXXXXXXXXX

このキーは、コネクタが初期化される際に1回設定されます。その後のAPI呼び出しは、同じ認証セッションを再利用します。

#キーフォーマット

#ヘルスチェック

コネクタのヘルスチェックは、GET /v1/balanceを呼び出します。これは、すべてのStripeアカウントで利用可能な軽量エンドポイントです。成功した200の応答は、シークレットキーが有効であることを確認します。

#アーキテクチャ

#生JSON、プラットフォーム処理スキーマ

コネクタは、Stripe APIから生のJSONを返します。これは、完全なネスト構造を持つStripeオブジェクトの配列です。プラットフォームがその後を引き継ぎます。

1. JSONペイロードからスキーマが自動的に発見されます
2. ネストされたオブジェクトはドット表記の列にフラット化されます
3. データはレイクハウスに保存され、SQLでクエリ可能になります

スキーマを定義したり、列をリストしたり、変換コードを書いたりする必要はありません。Stripeがオブジェクトに追加した新しいフィールドは、次の抽出時に自動的に表示されます。

#一様なAPI、一様なコネクタ

Stripeのリストエンドポイントは非常に一様です。すべて同じエンベロープ、{"object":"list","data":[..],"has_more":bool}を返し、同じカーソルベースのページネーションを使用します。このため、コネクタは、76のサポートされているリソースすべてに対して、単一の抽出パスを使用します。新しいリソースを追加するには、そのAPIパスをレジストリに追加するだけで、新しい抽出ロジックは必要ありません。

#エンドポイントの解決

エンドポイントはUIで3層に組織化されています。

1. ドメイングループ (core, billing, products, ...): グループを選択し、ドロップダウンから特定のリソースを選択します（例: billing → invoices）。
2. スタンドアロンエンドポイント (payment_methods, tax_registrations, ...): エンドポイントが直接リソースを識別します。ドロップダウンは必要ありません。
3. カスタムエンドポイント (custom): Stripe APIパス（例: issuing/settlements）を入力し、コネクタは標準カーソルページネーションで呼び出します。

どのパスを選択しても、抽出の動作は同じです。認証、ページネーション、生のJSONを返します。

#コネクタが処理するものとプラットフォームが処理するもの

#エンドポイントリファレンス

すべてのリストエンドポイントは同じパターンに従います: GET /v1/{resource}?limit=100&starting_after={cursor}。レスポンスは同じエンベロープを共有します: {"object":"list","data":[...],"has_more":bool,"url":"/v1/..."}。

以下の表は、UIおよびStripeリソースに公開されている20のエンドポイントを文書化しています。

#core

主な支払いリソース。単一ドメイングループで「リソースタイプ」ドロップダウン（14のオプション）。

UIオプション: リソースタイプ（必須、上記の14リソースのドロップダウン）+ 最大アイテム数（オプション）。 ページネーション: カーソルベース。 出力: 生のJSON。Stripeリストエンベロープ。

#products

カタログと価格設定（7つのオプション）。

UIオプション: リソースタイプ（必須）+ 最大アイテム数（オプション）。 ページネーション: カーソルベース。 出力: 生のJSON。

#billing

定期請求（11のオプション）。

UIオプション: リソースタイプ（必須）+ 最大アイテム数（オプション）。 ページネーション: カーソルベース。 出力: 生のJSON。

注目すべきクセ: StripeのAPIドキュメントによると、subscriptionsリストエンドポイントはデフォルトでキャンセルされていないすべてのサブスクリプション（アクティブ、トライアル、過去の支払い、不完全、未払い、一時停止）を返します。 キャンセルされたサブスクリプションは、明示的に要求しない限り除外されます。 キャンセルされたものを含めるには、resource_path=subscriptions?status=canceledまたは?status=allを使用したカスタムエンドポイントを使用してください。

#checkout

ホストされたチェックアウトフロー（2つのオプション: checkout_sessions, payment_links）。

UIオプション: リソースタイプ（必須）+ 最大アイテム数（オプション）。 ページネーション: カーソルベース。

#connect

マーケットプレイス/プラットフォームリソース（5つのオプション: accounts, application_fees, transfers, top_ups, country_specs）。

UIオプション: リソースタイプ（必須）+ 最大アイテム数（オプション）。 ページネーション: カーソルベース。

#radar

不正検出: Stripe Radarが必要（3つのオプション: early_fraud_warnings, reviews, value_lists）。

UIオプション: リソースタイプ（必須）+ 最大アイテム数（オプション）。 ページネーション: カーソルベース。

#issuing

カード発行: Stripe Issuingのアクティベーションが必要（7つのオプション: authorizations, cardholders, cards, transactions, disputes, personalization_designs, physical_bundles）。

UIオプション: リソースタイプ（必須）+ 最大アイテム数（オプション）。 ページネーション: カーソルベース。 製品が有効でない場合の動作: Stripeは400 Bad Requestを返し、「Your account is not set up to use Issuing」というメッセージが表示されます。 抽出に失敗します、制限事項を参照してください。

#treasury

資金移動: Stripe Treasuryのアクティベーションが必要（9つのサブリソース）。

UIオプション: リソースタイプ（必須）+ 金融口座ID（必須、形式fa_xxx）+ 最大アイテム数（オプション）。 ページネーション: カーソルベース。

#terminal

物理カードリーダー（3つのオプション: terminal_locations, terminal_readers, terminal_configurations）。

UIオプション: リソースタイプ（必須）+ 最大アイテム数（オプション）。 ページネーション: カーソルベース。

#identity

身元確認: Stripe Identityが必要（2つのオプション: identity_verification_sessions, identity_verification_reports）。

#climate

炭素除去: Stripe Climateが必要（3つのオプション: climate_orders, climate_suppliers, climate_products）。

#reporting

レポートとSigma（3つのオプション: report_runs, report_types, sigma_scheduled_query_runs）。

注目すべきクセ: /v1/reporting/report_typesはlimitパラメータを拒否します。 コネクタはこれを検出し、パラメータを削除して自動的に再試行します。 あなたの側で必要なアクションはありません。

#payment_methods (filtered standalone)

UIオプション: 顧客ID（必須、形式cus_xxx）+ 最大アイテム数（オプション）。 特定の顧客に紐づけられた支払い方法をリストします。 Stripeは顧客フィルタを必要とし、顧客IDが欠如している場合、コネクタはAPIコールを実行する代わりに空のリストを返します。

#setup_attempts (filtered standalone)

UIオプション: セットアップインテントID（必須、形式seti_xxx）+ 最大アイテム数（オプション）。

#subscription_items (filtered standalone)

UIオプション: サブスクリプションID（必須、形式sub_xxx）+ 最大アイテム数（オプション）。

#financial_connections_transactions (filtered standalone)

UIオプション: アカウントID（必須、形式fca_xxx）+ 最大アイテム数（オプション）。

#financial_connections_accounts (standalone)

UIオプション: 最大アイテム数のみ。 StripeアカウントにリンクされたすべてのFinancial Connectionsアカウントをリストします。

#tax_registrations (standalone)

UIオプション: 最大アイテム数のみ。

#treasury_financial_accounts (standalone)

UIオプション: 最大アイテム数のみ。 注意: 個々のトランザクションエンドポイントはtreasuryドメイングループにあります。 このスタンドアロンエンドポイントはアカウントリスト自体のみです。

#custom

UIオプション: リソースパス（必須）+ 最大アイテム数（オプション）。

フリーテキストのStripe APIパス。 コネクタはv1/プレフィックス付きまたは非付きのパスを受け入れ、標準カーソルページネーションでエンドポイントを呼び出します。

例:

• issuing/settlements → GET /v1/issuing/settlements
• v1/capital/financing_offers → GET /v1/capital/financing_offers（ダブルプレフィックスなし）

このエンドポイントは、名前付きエンドポイントでカバーされていないStripeリソース、または名前付きスロットが必要でないニッチ/ベータエンドポイントに使用してください。

#ページネーション

すべてのリストエンドポイントは、Stripeのカーソルベースのページネーションを使用します。

GET /v1/{resource}?limit=100&starting_after={last_id}

レスポンス:

{
  "object": "list",
  "url": "/v1/...",
  "has_more": true,
  "data": [ ... ]
}

期待される動作:

• コネクタは、1リクエストあたり100レコードを取得します（Stripeの最大ページサイズ）
• Stripeがhas_more: trueを報告している限り、ページネーションを続けます
• has_moreがfalseの場合、またはMax Itemsに達した場合に停止します

#ノーリミットフォールバック

Stripeの一部のエンドポイント（特に/v1/reporting/report_types）は、limitパラメータを受け付けません。コネクタは、その結果として発生する400エラーを検出し、limitなしでリクエストを再試行し、抽出を透明に続けます。設定する必要はありません。再試行は自動的に行われ、最初のリクエストでのみ発生します。

完全な仕様については、Stripe Pagination docsを参照してください。

#レート制限

Stripeは、docs.stripe.com/rate-limitsでレート制限をドキュメント化しています。正確な数値はエンドポイントとアカウントタイプによって異なります。現在の制限については、公式ドキュメントを参照してください。

#レート制限の処理

429 Too Many Requestsの場合、コネクタは自動的に待機して再試行します。

1. Stripeによって送信されたRetry-Afterヘッダー（秒単位）を読み取ります
2. ヘッダーが欠落している場合、2秒の待機にフォールバックします
3. 同じリクエストを再試行し、抽出を続けます

その他のエラーコード（400、401、403、404、500など）は失敗として伝搬します。コネクタはそれらをキャッチしたりスキップしたりしません。抽出はStripeによって返されたエラーとともに即座に停止します。

#出力形式

#生のJSON（コネクタ出力）

コネクタは、Stripe APIからの生のJSONを返します。Stripeオブジェクトの配列で、完全なネスト構造を持ち、Stripeのオブジェクトスキーマに正確に一致します。

すべてのStripeオブジェクトには以下が含まれます。

リソース固有のフィールドはオブジェクトごとに異なります。各オブジェクトのスキーマについては、Stripe API referenceを参照してください。

#フラット化された出力（Lakehouse）

プラットフォームは、生のJSONをフラットなテーブルにフラット化します。ネストされたキーは、アンダースコアで区切られた列名になります。

列名は正規化されます。小文字、ドットと特殊文字はアンダースコアに置き換えられ、常に文字またはアンダースコアで始まります。

#制限事項

• 削除の追跡なし: コネクタは各リソースの現在の状態を抽出します。削除されたオブジェクトは、通常、リストエンドポイントから返されません。監査トレールが必要な場合は、eventsを抽出してください（これは削除を*.deletedイベントタイプとして記録します）。
• Unixタイムスタンプ: StripeはUnix秒（整数）を使用します。ISO 8601文字列ではありません。ダウンストリームのクエリでタイムスタンプにキャストしてください。
• Stripe製品のゲーティング: イシューイング、トレジャリー、アイデンティティ、ターミナル、および気候には、アカウントで対応するStripe製品がアクティブになっている必要があります。アクティブでない場合、Stripeは「Your account is not set up to use X」のようなメッセージとともに400エラーを返し、抽出に失敗します。コネクタはスキップしたり再試行したりしません。
• 権限エラーはスキップされません: 例えば、Restricted API Keyにリソースへの読み取りアクセスがない場合、Stripeが403（権限拒否）を返した場合、抽出は即座に失敗します。コネクタは403を空の結果に変換するための特別な処理を行いません。429レート制限応答のみを再試行します。
• subscriptionsデフォルトフィルタ: StripeのAPIドキュメントによると、リストエンドポイントはデフォルトでキャンセルされていないすべてのサブスクリプションを返します。キャンセルされたサブスクリプションを含めるには、resource_path=subscriptions?status=canceledまたは?status=allを使用したカスタムエンドポイントを使用してください。
• カスタムエンドポイントのページネーション: カスタムエンドポイントは、Stripeの標準リスト応答形式（{"object":"list","data":[...],"has_more":bool}）を想定しています。非標準の応答形状（例: /v1/balanceのようなシングルトン）を持つエンドポイントは、空のリストを返します。
• テストモード vs ライブモードの分離: シークレットキーは、コネクタが読み取る環境を決定します。sk_test_とsk_live_のデータは完全に分離されています。環境間の抽出はありません。
• 自動展開なし: Stripeはexpand[]=fieldをサポートして関連オブジェクトをインライン表示できますが、コネクタはこれを設定しません。関連オブジェクトは出力にID参照として表示されます。別の抽出を介してダウンストリームで結合してください。

#さらに進む

当社のソリューションを実装するためのトレーニングや技術サポートが必要な場合は、営業担当者にお問い合わせください、またはこのリンクをクリックして、プロフェッショナルサービスの専門家にカスタム分析を依頼するための見積もりを取得してください。

Data Platformを構築するチームと直接やり取りし、質問をしたり、フィードバックを送信したり、Discordの専用チャネルに参加してください。

OVHcloudサービスについてサポートが必要な場合は、ヘルプセンターでリクエストを作成してください。

ユーザーコミュニティに参加してください。