ToolJet 集成 Stripe 数据源完全指南连接配置、查询操作与 API 底层实现解析【免费下载链接】ToolJetOpen-source foundation of ToolJet AI - the enterprise app generation platform for internal tools, dashboards, business applications, workflows and AI agents. Build visually, from a prompt, or from Claude Code, Codex and Cursor over MCP 项目地址: https://gitcode.com/GitHub_Trending/to/ToolJetToolJet 可以通过 Stripe 官方 REST API 连接你的 Stripe 账户实现对客户、支付、退款、账户等核心数据的读写操作。本文基于 ToolJet 仓库中的 Stripe 数据源插件与官方文档完整讲解从获取 API Key、建立数据源连接到在查询面板中执行各类操作的完整流程并深入解析插件源码中的认证、路径参数替换与表单编码原理帮助你快速在内部工具、仪表盘或业务应用中落地 Stripe 集成。概述为什么在 ToolJet 中使用 Stripe 数据源Stripe 是广泛使用的在线支付与业务管理平台其 REST API 覆盖账户、客户、支付、退款、订阅、发票等大量资源。ToolJet 将 Stripe 封装为开箱即用的 API 类型数据源使得非后端开发人员也能在可视化编辑器里直接调用 Stripe 接口——无需编写任何服务端代码即可读取和写入客户、支付等数据。在 ToolJet 中Stripe 数据源是一个典型的「API 类型」插件。从仓库中的插件清单 plugins/packages/stripe/lib/manifest.json 可以看到它被声明为type: api、kind: stripe并且只要求一个必填配置项——api_key同时还开启了customTesting用于自定义连通性测试。这意味着接入成本极低只要有一个 Stripe API Key就能完成连接。本文基于仓库中 3.0.0-LTS 版本的文档 docs/versioned_docs/version-3.0.0-LTS/data-sources/stripe.md 以及对应插件源码整理。一、获取 Stripe API Key在建立连接之前首先需要从 Stripe 账户后台获取 API 密钥。操作步骤如下登录你的 Stripe 账户仪表盘点击右上角的Developers开发者入口在左侧边栏进入API KeysAPI 密钥页面在Secret key密钥区域点击Reveal test key显示密钥复制后粘贴到 ToolJet 中。需要注意的关键点密钥类型Stripe 提供 Publishable key可发布密钥与 Secret key密钥两类ToolJet 需要的是Secret key测试模式与生产模式Stripe 控制台区分 Test mode测试模式和 Live mode生产模式二者对应不同的密钥开发阶段建议先使用测试密钥验证无误后再切换生产密钥密钥保密Secret key 等同于账户的访问凭证切勿提交到代码仓库或暴露在客户端。在 ToolJet 中该密钥会以加密形式存储manifest 中api_key被标记为encrypted: true但使用时仍应遵循最小权限原则。二、在 ToolJet 中建立 Stripe 数据源连接连接 Stripe 数据源有两种入口任选其一即可在查询面板query panel点击 Add new Data source按钮或从 ToolJet 仪表盘导航到Data Sources页面在数据源列表中选择Stripe。选择 Stripe 后只需填写一项配置配置项说明是否必填API key上一步从 Stripe 开发者控制台获取的 Secret key是从插件清单 plugins/packages/stripe/lib/manifest.json 可以印证这一设计properties.api_key被定义为type: password类型的输入框输入内容以密码形式掩码显示并且位于required列表中即未填写 API Key 将无法保存数据源。保存后密钥以加密形式持久化界面上会显示 Encrypted 标签。配置完成后点击Save保存数据源即可在查询面板中开始使用。三、查询 Stripe基本操作流程在查询管理器中执行 Stripe 查询的操作步骤如下点击编辑器底部查询管理器的 Add按钮新建查询在数据源下拉列表中选择上一步创建的Stripe数据源从操作下拉框中选择所需操作并填写对应参数点击Preview按钮预览输出结果或点击Run按钮实际触发查询。查询面板中的操作选择器由 plugins/packages/stripe/lib/operations.json 定义operation字段使用react-component-api-endpoint-old类型渲染一个下拉选择组件其选项数据直接来源于 Stripe 官方 OpenAPI 规范spec_url指向 Stripe 的openapi/spec3.json。这意味着操作列表与 Stripe API 规范保持同步凡是 Stripe API 支持的端点都可以在 ToolJet 中选择执行。提示查询返回的结果可以通过 ToolJet 的 Transformations数据转换功能进一步处理例如过滤、聚合或映射字段详见 Transformations 文档。四、支持的操作一览完整端点清单ToolJet 对 Stripe 数据源的支持覆盖 Stripe API 的全部操作文档按资源类别列出了完整的端点矩阵。以下为各操作类别及其端点、HTTP 方法与说明的完整清单。Account 操作针对当前账户方法端点说明DELETE/v1/account删除账户GET/v1/account获取账户详情POST/v1/account创建或更新账户Bank AccountsAccount 下方法端点说明POST/v1/account/bank_accounts添加银行账户DELETE/v1/account/bank_accounts/{id}删除银行账户GET/v1/account/bank_accounts/{id}获取银行账户详情POST/v1/account/bank_accounts/{id}更新银行账户详情CapabilitiesAccount 下方法端点说明GET/v1/account/capabilities获取账户能力列表GET/v1/account/capabilities/{capability}获取指定能力详情POST/v1/account/capabilities/{capability}更新指定能力External AccountsAccount 下方法端点说明GET/v1/account/external_accounts获取外部账户列表POST/v1/account/external_accounts添加外部账户DELETE/v1/account/external_accounts/{id}删除外部账户GET/v1/account/external_accounts/{id}获取外部账户详情POST/v1/account/external_accounts/{id}更新外部账户详情PeopleAccount 下方法端点说明GET/v1/account/people获取关联人员列表POST/v1/account/people为账户添加人员DELETE/v1/account/people/{person}删除人员GET/v1/account/people/{person}获取人员详情POST/v1/account/people/{person}更新人员详情PersonsAccount 下方法端点说明POST/v1/account/persons添加人员DELETE/v1/account/persons/{person}删除人员GET/v1/account/persons/{person}获取人员详情POST/v1/account/persons/{person}更新人员详情其他 Account 操作方法端点说明POST/v1/account/login_links为账户创建登录链接POST/v1/account_links创建账户链接Accounts指定账户操作方法端点说明GET/v1/accounts获取账户列表POST/v1/accounts创建新账户DELETE/v1/accounts/{account}删除指定账户GET/v1/accounts/{account}获取指定账户详情POST/v1/accounts/{account}更新指定账户详情Bank Accounts指定账户下方法端点说明POST/v1/accounts/{account}/bank_accounts添加银行账户DELETE/v1/accounts/{account}/bank_accounts/{id}删除银行账户GET/v1/accounts/{account}/bank_accounts/{id}获取银行账户详情Capabilities指定账户下方法端点说明GET/v1/accounts/{account}/capabilities获取账户能力列表GET/v1/accounts/{account}/capabilities/{capability}获取指定能力详情POST/v1/accounts/{account}/capabilities/{capability}更新指定能力External Accounts指定账户下方法端点说明GET/v1/accounts/{account}/external_accounts获取外部账户列表POST/v1/accounts/{account}/external_accounts添加外部账户DELETE/v1/accounts/{account}/external_accounts/{id}删除外部账户GET/v1/accounts/{account}/external_accounts/{id}获取外部账户详情People指定账户下方法端点说明GET/v1/accounts/{account}/people获取关联人员列表POST/v1/accounts/{account}/people添加人员DELETE/v1/accounts/{account}/people/{person}删除人员GET/v1/accounts/{account}/people/{person}获取人员详情POST/v1/accounts/{account}/people/{person}更新人员详情Persons指定账户下方法端点说明POST/v1/accounts/{account}/persons添加人员DELETE/v1/accounts/{account}/persons/{person}删除人员GET/v1/accounts/{account}/persons/{person}获取人员详情POST/v1/accounts/{account}/persons/{person}更新人员详情其他 Account 指定操作方法端点说明POST/v1/accounts/{account}/login_links创建账户登录链接POST/v1/accounts/{account}/reject拒绝账户Apple Pay 操作方法端点说明GET/v1/apple_pay/domains获取 Apple Pay 域名列表POST/v1/apple_pay/domains添加 Apple Pay 域名DELETE/v1/apple_pay/domains/{domain}从 Apple Pay 删除域名GET/v1/apple_pay/domains/{domain}获取指定 Apple Pay 域名Application Fees 操作方法端点说明GET/v1/application_fees获取应用费用列表GET/v1/application_fees/{id}获取指定应用费用POST/v1/application_fees/{id}/refund退款应用费用GET/v1/application_fees/{id}/refunds获取退款列表POST/v1/application_fees/{id}/refunds为应用费用创建退款Application Fee Refunds指定方法端点说明GET/v1/application_fees/{fee}/refunds/{id}获取指定退款详情说明上述清单覆盖了文档中列出的全部端点。由于 ToolJet 的操作列表直接对接 Stripe OpenAPI 规范见 operations.json其余未在此逐一罗列的资源如 Charges、Customers、PaymentIntents、Refunds、Subscriptions 等同样可以直接从下拉框中选择并执行。更详细的每个操作的行为与参数语义可参考 Stripe 官方 API 文档。五、底层实现插件源码如何执行 Stripe 查询理解了操作清单之后再来看插件运行时是如何把这些操作真正发送到 Stripe 的。核心实现位于 plugins/packages/stripe/lib/index.ts 的StripeQueryService类。5.1 认证方式Bearer TokenauthHeader方法把数据源配置中的api_key组装为标准的 HTTP 认证头authHeader(token: string): Headers { return { Authorization: Bearer ${token} }; }Stripe API 采用Authorization: Bearer secret_key的认证方式与 manifest.json 中定义的SourceOptions{ api_key: string }见 types.ts一一对应。也就是说查询时插件会从数据源配置中取出加密存储的 API Key解密后放入请求头。5.2 请求地址与路径参数替换插件将固定的 API 基地址与查询面板中选择的端点拼接并处理路径参数const baseUrl https://api.stripe.com; const path queryOptions[path]; let url ${baseUrl}${path}; const pathParams queryOptions[params][path]; // Replace path params of url for (const param of Object.keys(pathParams)) { url url.replace({${param}}, pathParams[param]); }这解释了上一节端点表格中的{id}、{account}、{person}、{capability}、{domain}、{fee}等占位符的用途在查询面板填写这些路径参数后插件会逐一把{param}替换为实际值例如把/v1/accounts/{account}变为/v1/accounts/acct_123。5.3 GET 与 POST 请求的差异处理插件根据操作类型区分请求方式if (operation get) { response await got(url, { method: operation, headers: this.authHeader(apiKey), searchParams: queryParams, }); } else { const resolvedBodyParams this.resolveBodyparams(bodyParams); response await got(url, { method: operation, headers: this.authHeader(apiKey), form: resolvedBodyParams, searchParams: queryParams, }); }GET 请求查询参数通过searchParams追加到 URL 查询字符串其他请求POST / DELETE / PUT 等请求体以form形式提交即application/x-www-form-urlencoded这符合 Stripe API 对表单编码请求体的要求。5.4 嵌套参数的扁平化编码Stripe 的很多参数是嵌套结构例如metadata[order_id]...。resolveBodyparams方法负责把面板中的嵌套对象扁平化为 Stripe 期望的键名格式private resolveBodyparams(bodyParams: object): object { if (typeof bodyParams string) { return bodyParams; } const expectedResult {}; for (const key of Object.keys(bodyParams)) { if (typeof bodyParams[key] object) { for (const subKey of Object.keys(bodyParams[key])) { expectedResult[${key}[${subKey}]] bodyParams[key][subKey]; } } else { expectedResult[key] bodyParams[key]; } } return expectedResult; }例如配置{ metadata: { order_id: 1001 } }会被转换为metadata[order_id]1001后随表单提交与 Stripe API 的参数规范保持一致。5.5 响应与错误处理请求成功后插件解析返回的 JSON 并包装为统一的查询结果结构result JSON.parse(response.body); return { status: ok, data: result, };失败时则抛出QueryError携带 Stripe 返回的错误响应体便于在 ToolJet 的查询结果面板中直接查看错误原因。此外manifest 中开启了customTesting: true意味着数据源连接建立后ToolJet 会以自定义方式验证 API Key 的有效性确保在编写查询前连接就绪。六、常见应用场景基于以上能力可以快速构建以下典型场景退款工具在管理后台通过POST /v1/charges/{id}/refunds等操作发起退款并配合查询面板查看退款状态官方文档还提供了 Stripe Refund App 教程 作为参考案例客户数据看板通过GET /v1/customers、GET /v1/payment_intents等操作拉取客户与支付数据结合 ToolJet 表格、图表组件生成业务仪表盘账户自助管理在内部工具中为运营团队提供查询账户详情GET /v1/account、管理外部账户/v1/account/external_accounts的能力订阅与发票管理通过下拉框选择 Subscriptions、Invoices 相关端点实现订阅状态查询、发票检索等运营操作。七、小结本文围绕 ToolJet 的 Stripe 数据源完成了从接入到原理的闭环讲解先获取 Stripe Secret key再在 ToolJet 中通过 Add new Data source或 Data Sources 页面建立连接随后在查询面板中基于 Stripe OpenAPI 规范生成的操作列表执行查询最后深入 插件源码 剖析了 Bearer 认证、路径参数替换、表单编码与嵌套参数扁平化等底层机制。结合这些内容你可以在 ToolJet 中以低代码方式完成客户、支付、退款、账户等 Stripe 数据的读写并在此基础上构建退款工具、支付看板等业务应用。相关文档与源码入口如下官方数据源文档docs/versioned_docs/version-3.0.0-LTS/data-sources/stripe.md插件运行时实现plugins/packages/stripe/lib/index.ts插件清单配置项定义plugins/packages/stripe/lib/manifest.json操作定义plugins/packages/stripe/lib/operations.json类型定义plugins/packages/stripe/lib/types.ts【免费下载链接】ToolJetOpen-source foundation of ToolJet AI - the enterprise app generation platform for internal tools, dashboards, business applications, workflows and AI agents. Build visually, from a prompt, or from Claude Code, Codex and Cursor over MCP 项目地址: https://gitcode.com/GitHub_Trending/to/ToolJet创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考