ToolJet 集成 Stripe 數(shù)據(jù)源完全指南連接配置、查詢操作與 API 底層實現(xiàn)解析【免費下載鏈接】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 賬戶實現(xiàn)對客戶、支付、退款、賬戶等核心數(shù)據(jù)的讀寫操作。本文基于 ToolJet 倉庫中的 Stripe 數(shù)據(jù)源插件與官方文檔完整講解從獲取 API Key、建立數(shù)據(jù)源連接到在查詢面板中執(zhí)行各類操作的完整流程并深入解析插件源碼中的認證、路徑參數(shù)替換與表單編碼原理幫助你快速在內(nèi)部工具、儀表盤或業(yè)務應用中落地 Stripe 集成。概述為什么在 ToolJet 中使用 Stripe 數(shù)據(jù)源Stripe 是廣泛使用的在線支付與業(yè)務管理平臺其 REST API 覆蓋賬戶、客戶、支付、退款、訂閱、發(fā)票等大量資源。ToolJet 將 Stripe 封裝為開箱即用的 API 類型數(shù)據(jù)源使得非后端開發(fā)人員也能在可視化編輯器里直接調(diào)用 Stripe 接口——無需編寫任何服務端代碼即可讀取和寫入客戶、支付等數(shù)據(jù)。在 ToolJet 中Stripe 數(shù)據(jù)源是一個典型的「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開發(fā)者入口在左側(cè)邊欄進入API KeysAPI 密鑰頁面在Secret key密鑰區(qū)域點擊Reveal test key顯示密鑰復制后粘貼到 ToolJet 中。需要注意的關鍵點密鑰類型Stripe 提供 Publishable key可發(fā)布密鑰與 Secret key密鑰兩類ToolJet 需要的是Secret key測試模式與生產(chǎn)模式Stripe 控制臺區(qū)分 Test mode測試模式和 Live mode生產(chǎn)模式二者對應不同的密鑰開發(fā)階段建議先使用測試密鑰驗證無誤后再切換生產(chǎn)密鑰密鑰保密Secret key 等同于賬戶的訪問憑證切勿提交到代碼倉庫或暴露在客戶端。在 ToolJet 中該密鑰會以加密形式存儲manifest 中api_key被標記為encrypted: true但使用時仍應遵循最小權限原則。二、在 ToolJet 中建立 Stripe 數(shù)據(jù)源連接連接 Stripe 數(shù)據(jù)源有兩種入口任選其一即可在查詢面板query panel點擊 Add new Data source按鈕或從 ToolJet 儀表盤導航到Data Sources頁面在數(shù)據(jù)源列表中選擇Stripe。選擇 Stripe 后只需填寫一項配置配置項說明是否必填API key上一步從 Stripe 開發(fā)者控制臺獲取的 Secret key是從插件清單 plugins/packages/stripe/lib/manifest.json 可以印證這一設計properties.api_key被定義為type: password類型的輸入框輸入內(nèi)容以密碼形式掩碼顯示并且位于required列表中即未填寫 API Key 將無法保存數(shù)據(jù)源。保存后密鑰以加密形式持久化界面上會顯示 Encrypted 標簽。配置完成后點擊Save保存數(shù)據(jù)源即可在查詢面板中開始使用。三、查詢 Stripe基本操作流程在查詢管理器中執(zhí)行 Stripe 查詢的操作步驟如下點擊編輯器底部查詢管理器的 Add按鈕新建查詢在數(shù)據(jù)源下拉列表中選擇上一步創(chuàng)建的Stripe數(shù)據(jù)源從操作下拉框中選擇所需操作并填寫對應參數(shù)點擊Preview按鈕預覽輸出結(jié)果或點擊Run按鈕實際觸發(fā)查詢。查詢面板中的操作選擇器由 plugins/packages/stripe/lib/operations.json 定義operation字段使用react-component-api-endpoint-old類型渲染一個下拉選擇組件其選項數(shù)據(jù)直接來源于 Stripe 官方 OpenAPI 規(guī)范spec_url指向 Stripe 的openapi/spec3.json。這意味著操作列表與 Stripe API 規(guī)范保持同步凡是 Stripe API 支持的端點都可以在 ToolJet 中選擇執(zhí)行。提示查詢返回的結(jié)果可以通過 ToolJet 的 Transformations數(shù)據(jù)轉(zhuǎn)換功能進一步處理例如過濾、聚合或映射字段詳見 Transformations 文檔。四、支持的操作一覽完整端點清單ToolJet 對 Stripe 數(shù)據(jù)源的支持覆蓋 Stripe API 的全部操作文檔按資源類別列出了完整的端點矩陣。以下為各操作類別及其端點、HTTP 方法與說明的完整清單。Account 操作針對當前賬戶方法端點說明DELETE/v1/account刪除賬戶GET/v1/account獲取賬戶詳情POST/v1/account創(chuàng)建或更新賬戶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獲取關聯(lián)人員列表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為賬戶創(chuàng)建登錄鏈接POST/v1/account_links創(chuàng)建賬戶鏈接Accounts指定賬戶操作方法端點說明GET/v1/accounts獲取賬戶列表POST/v1/accounts創(chuàng)建新賬戶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獲取關聯(lián)人員列表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創(chuàng)建賬戶登錄鏈接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為應用費用創(chuàng)建退款Application Fee Refunds指定方法端點說明GET/v1/application_fees/{fee}/refunds/{id}獲取指定退款詳情說明上述清單覆蓋了文檔中列出的全部端點。由于 ToolJet 的操作列表直接對接 Stripe OpenAPI 規(guī)范見 operations.json其余未在此逐一羅列的資源如 Charges、Customers、PaymentIntents、Refunds、Subscriptions 等同樣可以直接從下拉框中選擇并執(zhí)行。更詳細的每個操作的行為與參數(shù)語義可參考 Stripe 官方 API 文檔。五、底層實現(xiàn)插件源碼如何執(zhí)行 Stripe 查詢理解了操作清單之后再來看插件運行時是如何把這些操作真正發(fā)送到 Stripe 的。核心實現(xiàn)位于 plugins/packages/stripe/lib/index.ts 的StripeQueryService類。5.1 認證方式Bearer TokenauthHeader方法把數(shù)據(jù)源配置中的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一一對應。也就是說查詢時插件會從數(shù)據(jù)源配置中取出加密存儲的 API Key解密后放入請求頭。5.2 請求地址與路徑參數(shù)替換插件將固定的 API 基地址與查詢面板中選擇的端點拼接并處理路徑參數(shù)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]); }這解釋了上一節(jié)端點表格中的{id}、{account}、{person}、{capability}、{domain}、{fee}等占位符的用途在查詢面板填寫這些路徑參數(shù)后插件會逐一把{param}替換為實際值例如把/v1/accounts/{account}變?yōu)?v1/accounts/acct_123。5.3 GET 與 POST 請求的差異處理插件根據(jù)操作類型區(qū)分請求方式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 請求查詢參數(shù)通過searchParams追加到 URL 查詢字符串其他請求POST / DELETE / PUT 等請求體以form形式提交即application/x-www-form-urlencoded這符合 Stripe API 對表單編碼請求體的要求。5.4 嵌套參數(shù)的扁平化編碼Stripe 的很多參數(shù)是嵌套結(jié)構例如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 } }會被轉(zhuǎn)換為metadata[order_id]1001后隨表單提交與 Stripe API 的參數(shù)規(guī)范保持一致。5.5 響應與錯誤處理請求成功后插件解析返回的 JSON 并包裝為統(tǒng)一的查詢結(jié)果結(jié)構result JSON.parse(response.body); return { status: ok, data: result, };失敗時則拋出QueryError攜帶 Stripe 返回的錯誤響應體便于在 ToolJet 的查詢結(jié)果面板中直接查看錯誤原因。此外manifest 中開啟了customTesting: true意味著數(shù)據(jù)源連接建立后ToolJet 會以自定義方式驗證 API Key 的有效性確保在編寫查詢前連接就緒。六、常見應用場景基于以上能力可以快速構建以下典型場景退款工具在管理后臺通過POST /v1/charges/{id}/refunds等操作發(fā)起退款并配合查詢面板查看退款狀態(tài)官方文檔還提供了 Stripe Refund App 教程 作為參考案例客戶數(shù)據(jù)看板通過GET /v1/customers、GET /v1/payment_intents等操作拉取客戶與支付數(shù)據(jù)結(jié)合 ToolJet 表格、圖表組件生成業(yè)務儀表盤賬戶自助管理在內(nèi)部工具中為運營團隊提供查詢賬戶詳情GET /v1/account、管理外部賬戶/v1/account/external_accounts的能力訂閱與發(fā)票管理通過下拉框選擇 Subscriptions、Invoices 相關端點實現(xiàn)訂閱狀態(tài)查詢、發(fā)票檢索等運營操作。七、小結(jié)本文圍繞 ToolJet 的 Stripe 數(shù)據(jù)源完成了從接入到原理的閉環(huán)講解先獲取 Stripe Secret key再在 ToolJet 中通過 Add new Data source或 Data Sources 頁面建立連接隨后在查詢面板中基于 Stripe OpenAPI 規(guī)范生成的操作列表執(zhí)行查詢最后深入 插件源碼 剖析了 Bearer 認證、路徑參數(shù)替換、表單編碼與嵌套參數(shù)扁平化等底層機制。結(jié)合這些內(nèi)容你可以在 ToolJet 中以低代碼方式完成客戶、支付、退款、賬戶等 Stripe 數(shù)據(jù)的讀寫并在此基礎上構建退款工具、支付看板等業(yè)務應用。相關文檔與源碼入口如下官方數(shù)據(jù)源文檔docs/versioned_docs/version-3.0.0-LTS/data-sources/stripe.md插件運行時實現(xiàn)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創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考