pluggy-integration

Pluggy 連携

Pluggy Open Finance API の包括的な連携ガイドです。5 つのカテゴリにわたるルールを収録し、正確な実装を支援するため、影響度の高い順に優先順位を付けています。

適用するタイミング

次の場合に、これらのガイドラインを参照してください。

• Pluggy SDK と認証を設定するとき
• フロントエンドアプリケーションに Connect Widget を実装するとき
• Item（接続）を作成、更新、管理するとき
• MFA（多要素認証）フローを処理するとき
• リアルタイムのデータ同期用にウェブフックを設定するとき
• API キーとトークンを管理するとき
• 接続エラーやエッジケースを処理するとき

優先度別のルールカテゴリ

優先度	カテゴリ	影響度	接頭辞
1	認証	重大	auth-
2	Connect Widget	重大	widget-
3	ウェブフック設定	重大	webhook-
4	Item のライフサイクル	高	item-
5	エラー処理	中	error-

使用方法

詳細な説明とコード例については、各ルールファイルをお読みください。

rules/auth-api-keys.md
rules/widget-integration.md
rules/item-lifecycle.md

各ルールファイルには、次の内容が含まれています。

• 重要である理由の簡単な説明
• 説明付きの誤ったコード例
• 説明付きの正しいコード例
• 追加の背景情報と参考資料
• Pluggy 固有の注意事項

主な概念

接続同期とデータ同期

役割	担当	方法
接続同期	Pluggy	24／12／8 時間ごとに自動同期
更新のトリガー	ユーザー	ユーザーが明示的に要求した場合のみ
エンティティデータの同期	お客様	item/updated ウェブフックを受信したらすべて取得
トランザクションの同期	お客様	transactions/* ウェブフックイベントを使用

API キーと Connect トークン

• API Key：ユーザーデータへのアクセスに使用するバックエンドトークン（有効期限 2 時間）
• Connect Token：Connect Widget 専用のフロントエンドトークン（有効期限 30 分）

Item のライフサイクル

1. ユーザーが Connect Token を使用して Connect Widget を開きます
2. ユーザーがコネクターを選択して認証します
3. Pluggy が Item を作成し、データ同期を開始します
4. 同期が完了すると、ウェブフックで通知されます
5. バックエンドが API Key を使用してデータを取得します
6. Pluggy が毎日自動同期し、ウェブフックがデータの更新をトリガーします

完全版ドキュメント

すべてのルールを展開した完全なガイドについては、AGENTS.md をご覧ください。