開發者 API、MCP、GitHub 及觸發器模擬
您可以檢視觸發器、啟用或停用它們、查閱事件歷史紀錄，並透過您自己的程式碼或 AI 助理來模擬觸發器。Workflow Trigger Extensions 提供 REST API 和 MCP 伺服器，並能連線至 GitHub 儲存庫，讓您的自訂觸發器程式碼置於版本控制之下。這三項功能皆可在「開發者」頁面進行管理。
模擬觸發器
測試 Flow 工作流程通常意味著在您的商店中實際執行相關操作 - - 編輯商品、下單、等待投票結果。模擬功能則能省去這段等待時間：選擇一個觸發器，將其指向某個資源，系統便會觸發該流程，彷彿真實事件剛剛發生一般。
有兩種方法可以執行它：
- **在應用程式中，**開啟「事件歷史紀錄」中的任何事件，然後再次選擇「模擬」。這會重新觸發該特定事件。
- 透過 API 或 MCP，並使用資源 ID 或過去的事件。
模擬功能刻意追求精準。它不會建立任何捷徑式有效載荷 - - 而是會經過與真實的 Shopify Webhook 完全相同的處理流程，因此您的工作流程所接收的內容，與實際在生產環境中所接收的內容完全一致。
curl -X POST https://shopify.workflow-trigger-extensions.app/api/v1/triggers/product-update-trigger/simulate \
-H "Authorization: Bearer ftk_your_key_here" \
-H "Content-Type: application/json" \
-d '{"resourceId":"gid://shopify/Product/123456789","dryRun":true}'模擬執行會驗證觸發條件、解析主題，並顯示有效載荷 - - 但不會觸發任何動作。移除 dryRun 即可實際觸發該事件。您也可以傳入 {"fromHistoryId":"456"}，以重新觸發過去的事件，而非建立新的事件。
由輪詢（polling）而非 Webhook 觸發的觸發器無法進行模擬；在觸發器清單中，這些觸發器會顯示「simulatable: false」。
API 金鑰
在「開發者」頁面建立一個金鑰，並選擇其存取層級：
- 唯讀 - 列出觸發器及其狀態、讀取事件歷史紀錄、統計資料及權限。
- 讀取與寫入 - - 亦可開啟或關閉觸發器。
- 讀取、寫入與執行 - - 亦可模擬觸發器並測試自訂觸發器程式碼。
完整金鑰僅在建立時顯示一次。金鑰以雜湊形式儲存，並可隨時撤銷。請以 Bearer 標記的形式傳送：
Authorization: Bearer ftk_your_key_here基於上述原因，模擬功能位於其專屬層級之下：它會實際執行您的自動化流程，因此用於日常讀取的金鑰無法觸發這些流程。
REST API
| 方法 | 路徑 | 等級 | 目的 |
|---|---|---|---|
| GET | /api/v1 |
無 | API 指標 - 確認 API 正常運作 |
| GET | /api/v1/me |
閱讀 | 檢查授權並查看您的金鑰等級 |
| GET | /api/v1/triggers |
閱讀 | 每個觸發器及其對您商店的狀態 |
| GET | /api/v1/triggers/:handle |
閱讀 | 詳細說明一個觸發器 |
| PUT | /api/v1/triggers/:handle |
寫 | 開啟或關閉一個觸發器 |
| PUT | /api/v1/triggers |
寫 | 透過單次呼叫同時開啟或關閉多個裝置 |
| POST | /api/v1/triggers/:handle/simulate |
執行 | 模擬觸發器 |
| GET | /api/v1/triggers/custom |
閱讀 | 您自訂的觸發器及其程式碼 |
| GET | /api/v1/triggers/custom/:handle/test |
閱讀 | 自訂觸發器的擷取樣本事件 |
| POST | /api/v1/triggers/custom/:handle/test |
執行 | 在不儲存或觸發的情況下執行自訂觸發程式碼 |
| GET | /api/v1/history |
閱讀 | 列出觸發事件 |
| GET | /api/v1/history/:id |
閱讀 | 取得一個事件及其載荷 |
| GET | /api/v1/stats |
閱讀 | 總計、成功率、狀態分類 |
| GET | /api/v1/permissions |
閱讀 | 您授予了哪些資料權限，以及每項權限能解鎖哪些功能 |
GET /api/v1/triggers 這是設定時非常實用的功能：針對每個觸發器，它會告訴您該觸發器所需的權限、該權限是否已授予、觸發器是否已啟用，以及應在應用程式的哪個位置進行管理。
開啟與關閉觸發器
PUT 之所以使用此方法而非 PATCH，是因為該呼叫具有幺勁性 - - 在超時後重新執行時，不會導致任何操作被重複應用，這一點在由輔助函式驅動 API 時至關重要。
curl -X PUT https://shopify.workflow-trigger-extensions.app/api/v1/triggers/order-tags-added-trigger \
-H "Authorization: Bearer ftk_your_key_here" \
-H "Content-Type: application/json" \
-d '{"enabled":true}'Enabling 從不授予任何權限。如果觸發器需要某項您尚未授予的權限，呼叫仍會成功，並明確告知您缺少哪些權限以及應在哪裡授予：
{
"enabled": true,
"scopeGranted": false,
"missingScopeLabels": ["Order Data Access"],
"permissionsUrl": "https://admin.shopify.com/store/.../app/permissions?permission=read_orders",
"warning": "Enabled, but this trigger cannot fire until Order Data Access is granted."
}點擊該連結會開啟「權限」頁面，並直接捲動至您所需的卡片。
加入 "sync": true 以同時啟動資料同步，如此一來，觸發器便會對現有的記錄生效，而非僅針對今後建立的記錄。
若要一次切換多個選項，PUT /api/v1/triggers 接受明確的清單或整個類別：
{ "enabled": true, "handles": ["order-tags-added-trigger", "order-note-changed-trigger"] }
{ "enabled": true, "category": "orders" }連結 GitHub
在「開發者」頁面上，「連線」分頁可讓您將 GitHub 儲存庫與您的 自訂觸發器 程式碼進行連結。變更內容會以拉取請求的形式供審查，您可以查看誰做了哪些變更，並能將不再運作的轉換還原。
點選「連線」將在您選擇的帳戶上安裝我們的 GitHub App。您可以選擇該 App 可存取的儲存庫，並可隨時在 GitHub 上撤銷該存取權限。選取儲存庫後，系統會立即將您現有的所有自訂觸發器寫入該儲存庫，因此該儲存庫一開始就能與該 App 對應，而非需隨時間推移逐步填入資料。
| 您的職責 | 會發生什麼事 |
|---|---|
| 在應用程式中建立、編輯或複製觸發器 | 該檔案已提交至您的儲存庫 |
| 在應用程式中刪除觸發器 | 該檔案已從您的儲存庫中移除 |
| 將變更推送到已連線的分支 | 應用程式中已更新觸發器的程式碼 |
每個觸發器都是一個以該觸發器識別碼命名的檔案，其中包含的正是您在編輯器中看到的模組 - - 沒有任何額外的封裝。因此，您可以像處理其他 JavaScript 檔案一樣，在自己的編輯器中開啟該檔案、執行它並進行程式碼檢查，然後在提交之前，使用上方的 /test 端點，將其套用至實際擷取的事件上進行測試。
還原至較早的版本
您無需了解 Git 即可撤銷變更。一旦儲存庫建立連線，觸發編輯器便會顯示一個「版本」下拉選單，列出該檔案的所有先前版本，並附上日期與作者。選擇其中一個版本，系統便會將其載入編輯器中，作為未儲存的變更，讓您能先閱讀內容 - - 只有儲存後，系統才會將其還原為新的提交。
變更或斷開連接
**「變更儲存庫」會將您帶回選取器，且不會影響該安裝項目。「斷開連結」會撤銷 GitHub 上的安裝，並在此處移除該安裝項目，因此其名稱即為其功能。「管理權限」**會開啟 GitHub 上的安裝設定，您可以在該處新增或移除儲存庫。
測試自訂觸發程式碼
如果您將自訂觸發器程式碼存放在儲存庫中，並使用自己的編輯器進行編輯，則無需先將程式碼儲存至應用程式，即可針對擷取的樣本事件執行該程式碼。
curl -X POST https://shopify.workflow-trigger-extensions.app/api/v1/triggers/custom/my-trigger/test \
-H "Authorization: Bearer ftk_your_key_here" \
-H "Content-Type: application/json" \
-d "$(jq -Rn --rawfile c flow-triggers/my-trigger.js '{code:$c}')"您將獲得該應用程式「測試」按鈕所顯示的內容：是否會觸發、輸出物件、您的 ctx.log 指令，以及執行時間。
不會觸發任何操作，也不會進行任何儲存 - - 不會執行任何工作流程、不會記錄任何事件、不會消耗任何配額，且儲存的程式碼亦不會被修改。此流程可在檔案監控器每次儲存時安全地執行。完整的工作流程請參閱 自訂觸發器。
MCP 伺服器
「開發者」頁面的「MCP」分頁會顯示伺服器 URL，以及適用於 Claude、Cursor、VS Code、Gemini CLI 等工具的、可直接複製的連線指令。這些工具對應於 REST 端點，且工具集會根據您的金鑰層級而有所不同 - - 若為唯讀金鑰，則完全無法使用寫入或執行類型的工具。
| 工具 | 等級 | 功能說明 |
|---|---|---|
list_triggers |
閱讀 | 每個觸發器及其狀態 |
list_custom_triggers |
閱讀 | 您自訂的觸發器及其程式碼 |
get_custom_trigger_sample |
閱讀 | 自訂觸發器用來進行測試的擷取事件 |
list_history |
閱讀 | 近期觸發事件 |
get_event |
閱讀 | 一項事件及其所包含的有效載荷 |
get_stats |
閱讀 | 彙總統計資料 |
get_permissions |
閱讀 | 已授予的權限及其所解鎖的功能 |
get_trigger |
寫 | 詳細說明一個觸發器 |
set_trigger |
寫 | 開啟或關閉一個觸發器 |
set_triggers_bulk |
寫 | 一次開啟或關閉多個開關 |
simulate_trigger |
執行 | 按需觸發 |
test_custom_trigger |
執行 | 在不儲存或觸發的情況下執行自訂觸發程式碼 |
這正是讓助理真正實用的關鍵：它能夠列出現有項目、說明觸發器所需的條件、啟用觸發器、觸發測試事件、讀取結果 - - 對於自訂觸發器，還能重寫程式碼並進行測試 - - 而您無需離開當前的對話。
您的資料如何受到保護
事件有效載荷在回傳時會將個人資料進行遮蔽處理：電子郵件地址、電話號碼、卡號以及包含個人姓名的欄位均會轉為 ***。Shopify 資源識別碼及商業相關欄位則保持不變，以確保有效載荷仍具實用價值。
遮罩功能適用於欄位名稱和值模式，因此雖已謹慎處理，但無法完全保證 - - 自由文字欄位中的個人資料仍可能外洩。此外，錯誤訊息在離開伺服器之前，其內部診斷細節也會被移除。
GitHub 連線不會儲存任何可能外洩的憑證：僅保留安裝識別碼，而存取儲存庫則使用按需生成的憑證，該憑證將於一小時內過期。
下一步
- 自訂觸發器 - 只需幾行程式碼，就能用 JavaScript 建立專屬的觸發器。
- 方案與使用方式 - 什麼算作「事件」，以及這項津貼是如何運作的。
- 《Workflow Trigger Extensions》簡介 - 觸發器如何運作，以及如何啟用它們。
速率限制
REST API 與 MCP 伺服器會針對每個 API 金鑰共用一個配額。
- 每 60 秒內，每個金鑰的請求數上限為 300 次，此為固定時段。
- **執行層級的呼叫會獲得第二項、更嚴格的配額，即每小時 60 次。**這兩項配額都會被消耗，因此一波密集的執行操作也會侵蝕共享配額。對此應用程式而言，這意味著模擬觸發器以及執行自訂觸發程式碼，這兩者都會實際觸發您的工作流程。
- **所有方案皆同。**您的方案計量機制是觸發事件，而非 API 呼叫，因此升級並不會增加這些數字。
- 處理時傳回 HTTP 429 錯誤。請暫停並重新嘗試，最好採用指數退避法。
- 若我們的快取暫時無法使用，限流器會採取「開放式」處理，而非阻斷您的整合流程。
傳入的 Shopify Webhook 不會受到速率限制
我們不會對 Shopify 傳送給我們的 Webhooks 進行流量限制 - - 這些 Webhooks 會在收到時立即被接受並排入佇列。上限為您方案的 30 天事件配額。
若您撰寫自訂觸發器，有件事值得留意：您的程式碼會在監聽的主題發生每個事件時執行，且每次執行都算作一個事件，包括您透過傳回 null 篩除的事件。其成本與針對同一事件的內建觸發器相同。
Shopify
這些是 Shopify 對 Shopify API 所設的限制，而非我們所設的限制。這些限制適用於此應用程式（以及您的工作流程）在 Shopify 端所能執行的操作，因此即使您在我們設定的限制範圍內，若商店規模較大，仍可能觸及這些限制。
- 所有 Shopify API 的輸入陣列均設有 250 項的上限。若請求中的陣列超過此上限，該請求將被拒絕。
- **分頁功能在 25,000 個物件處停止。**計數在 25,000 個以內均為準確；超過此數值時，Shopify 會傳回
25001，意指「超過 25,000」。若需進一步瀏覽，請先進行篩選。 - GraphQL 管理 API 的計費是根據計算出的查詢成本（以每秒點數為單位）來計算的，其上限取決於商店所選用的「Shopify」方案：
| Shopify 計畫 | 每秒得分 |
|---|---|
| 標準 | 100 |
| 進階 | 200 |
| 此外 | 1000 |
| 企業（商務元件） | 2000 |
Storefront API 並無速率限制。
完整詳情：Shopify API 速率限制