Back to Details

pluggy-integration

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Pluggy Integration

Pluggy集成

Comprehensive integration guide for Pluggy Open Finance API. Contains rules across 5 categories, prioritized by impact to guide accurate implementation.
这是Pluggy开放金融API的全面集成指南，包含5个类别的规则，按影响优先级排序，以指导准确实现。

When to Apply

适用场景

Reference these guidelines when:
  • Setting up Pluggy SDK and authentication
  • Implementing the Connect Widget in frontend applications
  • Creating, updating, or managing Items (connections)
  • Handling MFA (Multi-Factor Authentication) flows
  • Configuring webhooks for real-time data sync
  • Managing API keys and tokens
  • Handling connection errors and edge cases
在以下场景中参考本指南：
  • 设置Pluggy SDK与身份验证
  • 在前端应用中实现Connect Widget
  • 创建、更新或管理Items（连接）
  • 处理MFA（多因素认证）流程
  • 配置webhooks以实现实时数据同步
  • 管理API密钥与令牌
  • 处理连接错误与边缘情况

Rule Categories by Priority

按优先级划分的规则类别

PriorityCategoryImpactPrefix
1AuthenticationCRITICAL
auth-
2Connect WidgetCRITICAL
widget-
3Webhook ConfigurationCRITICAL
webhook-
4Item LifecycleHIGH
item-
5Error HandlingMEDIUM
error-
优先级类别影响程度前缀
1身份验证关键
auth-
2Connect Widget关键
widget-
3Webhook配置关键
webhook-
4Item生命周期高
item-
5错误处理中
error-

How to Use

使用方法

Read individual rule files for detailed explanations and code examples:
rules/auth-api-keys.md
rules/widget-integration.md
rules/item-lifecycle.md
Each rule file contains:
  • Brief explanation of why it matters
  • Incorrect code example with explanation
  • Correct code example with explanation
  • Additional context and references
  • Pluggy-specific notes
阅读单个规则文件获取详细说明与代码示例：
rules/auth-api-keys.md
rules/widget-integration.md
rules/item-lifecycle.md
每个规则文件包含：
  • 简要说明规则的重要性
  • 错误代码示例及解释
  • 正确代码示例及解释
  • 额外背景信息与参考资料
  • Pluggy专属注意事项

Key Concepts

核心概念

Connection Sync vs Data Sync

连接同步 vs 数据同步

ResponsibilityWho HandlesHow
Connection syncPluggyAuto-sync every 24/12/8h
Triggering updatesUserOnly when user explicitly requests
Entity data syncYouFetch all on 
item/updated
webhook
Transaction syncYouUse 
transactions/*
webhook events
职责处理方方式
连接同步Pluggy每24/12/8小时自动同步
触发更新用户仅当用户明确请求时
实体数据同步您的系统在
item/updated
webhook触发时获取全部数据
交易同步您的系统使用
transactions/*
webhook事件

API Key vs Connect Token

API密钥 vs Connect令牌

  • API Key: Backend token (2h expiration) for accessing user data
  • Connect Token: Frontend token (30min expiration) for Connect Widget only
  • API Key：后端令牌（2小时过期），用于访问用户数据
  • Connect Token：前端令牌（30分钟过期），仅适用于Connect Widget

Item Lifecycle

Item生命周期

  1. User opens Connect Widget with Connect Token
  2. User selects connector and authenticates
  3. Pluggy creates Item and starts data sync
  4. Webhook notifies when sync completes
  5. Backend retrieves data using API Key
  6. Pluggy auto-syncs daily; webhook triggers data refresh
  1. 用户使用Connect Token打开Connect Widget
  2. 用户选择连接器并完成身份验证
  3. Pluggy创建Item并开始数据同步
  4. 同步完成时Webhook发送通知
  5. 后端使用API Key获取数据
  6. Pluggy每日自动同步；Webhook触发数据刷新

Full Compiled Document

完整编译文档

For the complete guide with all rules expanded: 
AGENTS.md
如需查看包含所有扩展规则的完整指南，请参阅：
AGENTS.md