REST API 參考手冊
所有路徑皆以 https://shopify.workflow-transactional-email.app 為基準。除了 index 之外，每個端點都需要 Authorization: Bearer fak_... - - 請參閱 驗證與 API 金鑰。
回應格式為 JSON。錯誤訊息的結構始終一致：
{ "error": "Invalid or missing API key" }指標與同一性
| 方法 | 路徑 | 等級 | 目的 |
|---|---|---|---|
| GET | /api/v1 |
無 | API 索引。確認 API 是否正常運作，並回報當前版本 |
| GET | /api/v1/me |
閱讀 | 檢查金鑰是否有效，並查看其存取層級 |
由於該索引無需鍵值，因此將監控器指向它是一項安全的狀態檢查。
電子郵件版面配置
| 方法 | 路徑 | 等級 | 目的 |
|---|---|---|---|
| GET | /api/v1/email-templates |
閱讀 | 列出電子郵件版面配置。q 可搜尋名稱、主旨和說明；category=transactional 或 category=marketing 則會列出某一種電子郵件類型 |
| POST | /api/v1/email-templates |
寫 | 建立版面配置 |
| GET | /api/v1/email-templates/:id |
閱讀 | 一個版面配置，包含其設計或附件、頁尾文字及其語言清單 |
| PUT / PATCH | /api/v1/email-templates/:id |
寫 | 變更佈局。僅您傳送的欄位會有所變更 |
| DELETE | /api/v1/email-templates/:id |
寫 | 刪除佈局及其翻譯與版本 |
| GET | /api/v1/layout-schema |
閱讀 | 如何撰寫版面配置：設計格式、各區塊的預設值、可使用的 Liquid 語法、限制事項及範例 |
此清單支援 page（預設值為 1）、limit（預設值為 25，最大值為 100）以及 q，後者會搜尋名稱、主題和描述。API 並未提供按類型篩選的功能；請改為參閱各佈局的說明頁面：category。
一個版面包含以下欄位：
| 領域 | 註釋 |
|---|---|
name, description |
姓名為必填欄位，最多 200 個字元；描述最多 2000 個字元 |
bodyType |
visual (預設) 或 text。一旦建立即固定不變 |
defaultLocale |
佈局自身內容的語言，若未設定則預設為 en |
category |
transactional (預設) 或 marketing。詳見下文 |
subject, previewText |
允許攜帶液體。必修科目 |
bodyDesign |
視覺佈局：{ blocks, global?, header?, footer?, testVariables? }。若要修改設計，請寄送完整的設計檔；HTML body 即由此渲染而成 |
body |
文字排版：HTML 的 body 標籤 |
attachments |
文字版面配置：[{ filename, fileKey, sendAsLink? }]（適用於上傳的檔案，請參閱下方檔案），或 [{ filename, url }]（適用於寄送電子郵件時透過 HTTPS 擷取的檔案） |
marketingTexts |
行銷版面的頁尾文字，或稱null。詳見下文 |
主旨、預覽文字、正文及每個區塊文字中的 Liquid 內容都必須經過解析，且每個 fileKey 都必須屬於您的商店；否則寫入操作將因 400 錯誤而被拒絕，並會標明該欄位名稱。在撰寫視覺設計之前，請先閱讀 GET /api/v1/layout-schema：該設計是由建構器本身生成的，因此不會產生偏差。
透過此 API 進行的每次寫入操作都會保留在佈局的版本歷史紀錄中，這與在應用程式中儲存資料完全相同。
交易型與行銷型版面配置
category 說明了版面的用途。交易型版面會以未經修改的狀態發送給每位收件者。 行銷版面會跳過已取消訂閱的收件者（此步驟中的「收件者」欄位所有收件者皆已取消訂閱，該郵件不會發送，且在歷史紀錄中顯示為 SKIPPED），並針對每位「收件者」以單一郵件發送，每封郵件皆附有獨立的取消訂閱連結（每步驟最多 20 個），最後附上取消訂閱聲明及貴公司詳細資訊。{{ unsubscribe_url }} 以及 {{ unsubscribe_link }} 需由您自行放置連結；在交易型佈局中，這兩處皆為空白。相關的商家端說明請參閱 行銷電子郵件與取消訂閱。
marketingTexts 這是行銷版面配置所使用的頁尾文字，而非「設定」中全站通用的文字：
{
"marketingTexts": {
"unsubscribeText": "You get this because you shop with us. {{ unsubscribe_link }}",
"unsubscribeLinkLabel": "Unsubscribe",
"companyDetails": "Example GmbH, Musterstrasse 1, 10115 Berlin"
}
}每個欄位皆為選填。若設定了特定欄位，該欄位的「設定」文字將被該欄位內容取代；其餘欄位則維持原樣。null（預設值）表示採用電子郵件語言的「設定」文字。字元限制：unsubscribeText 及 companyDetails 為 2000 個字元，unsubscribeLinkLabel 為 100 個字元。 unsubscribeText 必須包含 {{ unsubscribe_link }} 或 {{ unsubscribe_url }}，否則寫入操作將被拒絕。此欄位會儲存於任何版面配置中，但僅在行銷版面配置中發送。
刪除佈局絕不會遭到阻擋。如果 Shopify Flow 中的步驟仍指向該佈局，回應中會包含一個 warning，標示出相關步驟的數量；這些步驟將持續失敗，直到它們改用其他佈局為止。
譯文
| 方法 | 路徑 | 等級 | 目的 |
|---|---|---|---|
| GET | /api/v1/email-templates/:id/translations |
閱讀 | 佈局中的每種語言及其內容 |
| GET | /api/v1/email-templates/:id/translations/:locale |
閱讀 | 一種語言 |
| PUT | /api/v1/email-templates/:id/translations/:locale |
寫 | 建立或取代一種語言 |
| DELETE | /api/v1/email-templates/:id/translations/:locale |
寫 | 移除一種語言。若該語言無法顯示，則改用預設版面配置 |
| POST | /api/v1/email-templates/:id/translations/:locale/promote |
寫 | 將該語言設為版面配置的主要語言 |
:locale 是一種語言代碼，例如 de、fr 或 pt-br；大小寫與分隔符號皆不影響。每個版面配置最多可包含 30 種語言。在「Shopify Flow」步驟中，「語言」欄位會在發送時依序選擇：精確的地區設定、基礎語言、區域變體，若均不符則採用版面配置本身。
PUT 會取用完整的翻譯內容：subject（必填）、previewText，以及 bodyDesign（圖像）或 body（文字）。請勿變更 Liquid 標籤和 URL。其中有兩個欄位是翻譯專用的：
| 領域 | 文字排版 | 意思 |
|---|---|---|
attachments |
是 | 清單（與版面配置相同）= 此語言本身的附件，[] = 此語言無附件。null = 傳送版面配置的附件。省略 = 保留當前選項；新語言則採用版面配置的設定。視覺版面配置會將其附件作為各語言的 bodyDesign 中的區塊，並拒絕此欄位 |
marketingTexts |
任何 | 此語言的頁尾文字會逐欄疊加在佈局上的文字之上。null = 採用佈局的文字。Omitted = 維持當前選項 |
回傳的翻譯包含相同的兩個欄位：attachments 的值為 null（同時採用該版面的設定），而 marketingTexts 的值為 null（同時採用該版面的設定）。
promote 將版面配置與翻譯互換：版面配置採用翻譯的內容與地區設定，而它原本的內容則成為其原先所屬語言的翻譯。 附件和頁尾文字也會互換位置，因此每種語言仍會持續傳送先前傳送的內容。回應中會回報 promoted、previousMainLanguage 以及版面配置。由於這只是一個版本，因此可以撤銷此操作。
版本
| 方法 | 路徑 | 等級 | 目的 |
|---|---|---|---|
| GET | /api/v1/email-templates/:id/versions |
閱讀 | 已儲存的版本，最新者排在最前。此應用程式會保留最新的 25 個版本 |
| GET | /api/v1/email-templates/:id/versions/:version |
閱讀 | 某個版本的完整快照：包含版面配置及所有翻譯內容 |
| POST | /api/v1/email-templates/:id/versions/:version/restore |
寫 | 把那個版本放回去。已作為新版本錄製 |
| GET | /api/v1/email-templates/:id/versions/github?page= |
閱讀 | 連線的 GitHub 儲存庫中保存的每個版本，每頁顯示 20 個 |
| GET | /api/v1/email-templates/:id/versions/github/:sha |
閱讀 | 某個提交時的佈局 |
| POST | /api/v1/email-templates/:id/versions/github/:sha/restore |
寫 | 還原 GitHub 版本，就像儲存一樣 |
當「開發者」頁面未連接任何儲存庫時，GitHub 端點會傳回 409 錯誤。請參閱 版面配置版本歷史紀錄 及 在 GitHub 上保留無限量的版面配置歷史紀錄。
電子郵件發件人
| 方法 | 路徑 | 等級 | 目的 |
|---|---|---|---|
| GET | /api/v1/smtp-configs |
閱讀 | 列出 SMTP 寄件者 |
| GET | /api/v1/senders |
閱讀 | 列出已連線的信箱（Microsoft 365、Google） |
SMTP 發件者會回報 hasUsername 和 hasPassword，而非憑證本身 - - 這兩部分均被隱藏，因為使用者名稱與密碼同為憑證的一部分。發件者仍可透過其名稱、主機及發件地址被識別。已連線的信箱會回報部分遮蔽的地址（例如 so***@example.com），絕不會透露其登入憑證。
唯讀模式。請在應用程式中連線並編輯寄件者。
秘密
| 方法 | 路徑 | 等級 | 目的 |
|---|---|---|---|
| GET | /api/v1/secrets |
閱讀 | 列出秘密名稱及其說明 |
會回傳 hasValue，絕不會回傳該值。沒有任何端點可用於讀取密鑰。請在應用程式中建立和更新密鑰。
已上傳的檔案
| 方法 | 路徑 | 等級 | 目的 |
|---|---|---|---|
| GET | /api/v1/files |
閱讀 | 列出已上傳的標誌、圖片及附件 |
| DELETE | /api/v1/files |
寫 | 刪除其中一個，作者：key，位於正文中 |
此清單支援 page、limit（最多 100 個）以及 q，以便透過檔案名稱進行搜尋。
加入 **?usage=true** 後，每個檔案還會顯示 inUse，以及一個名為 usedBy 的陣列，其中列出所有引用該檔案的佈局與預設值。這就是您如何透過單一請求，找出所有可安全刪除的項目。由於此功能會掃描您的佈局與預設值，因此需手動啟用，而非預設啟用。
此處未提供上傳功能 - - 請透過應用程式中的媒體選擇器新增檔案。
HTTP 請求
| 方法 | 路徑 | 等級 | 目的 |
|---|---|---|---|
| GET | /api/v1/http-requests |
閱讀 | 列出 HTTP 請求 |
| POST | /api/v1/http-requests |
寫 | 建立一個 |
| GET | /api/v1/http-requests/:id |
閱讀 | 買一個 |
| PUT / PATCH | /api/v1/http-requests/:id |
寫 | 更新一 |
| DELETE | /api/v1/http-requests/:id |
寫 | 刪除一個 |
| POST | /api/v1/http-requests/:id/test |
執行 | 將其對實際目標進行測試 |
List 接受與電子郵件版面配置相同的 page、limit 及 q 參數。
目標網址 url 必須為 http:// 或 https://。若為其他網域，儲存時將被拒絕。
寫入標頭或正文中的原始憑證，會在每個回應中被遮蔽。以 {{ secrets.KEY }} 形式引用的值則會原樣返回，因為該引用本身並不屬於敏感資訊。
歷史與統計數據
涵蓋電子郵件發送與 HTTP 請求兩者。
| 方法 | 路徑 | 等級 | 目的 |
|---|---|---|---|
| GET | /api/v1/history |
閱讀 | 清單執行 |
| GET | /api/v1/history/:id |
閱讀 | 取得一筆包含請求與回應資料的執行紀錄 |
| GET | /api/v1/stats |
閱讀 | 總數與成功率 |
History 接受 page、limit（最多 100 個）、actionType、status（PENDING、SUCCESS、FAILED、SKIPPED）以及 actionConfigId，用以篩選至單一佈局或請求。
SKIPPED 這是一封行銷電子郵件，其收件者均已取消訂閱：既未發送任何內容，也未佔用配額，且不會計入成功率。
actionType 必須精確為 EMAIL 或 HTTP_REQUEST。系統會忽略未識別的值，而非直接拒絕，因此即使出現打字錯誤，系統也會返回所有結果，而非拋出錯誤。
Stats 接受 days（預設值為 30，最大值為 365）。
狀態碼
| 程式碼 | 意思 |
|---|---|
| 200 | 成功 |
| 201 | 建立於 |
| 400 | 請求格式不正確或驗證失敗。error 會指定該欄位名稱，例如 subject: required |
| 401 | API 金鑰遺失、格式錯誤或已撤銷 |
| 403 | 此金鑰雖有效，但其權限等級對於此端點而言過低 |
| 404 | 未找到，或屬於另一家店鋪 |
| 405 | 此路徑的方法不正確 |
| 409 | 因記錄仍在使用中（檔案刪除）或未連線至 GitHub（GitHub 版本）而遭拒絕 |
| 429 | 速率受限 - - 詳見下文 |
| 502 | 請求已執行，但第三方目標執行失敗 |
屬於另一家商店的記錄會傳回 404 而非 403，因此 API 永遠無法確認該 ID 是否存在於其他地方。
速率限制
兩份獨立的預算，均按鑰匙計算：
- 所有端點每 60 秒共計 300 次請求。
- 此外，每小時還需執行 60 次呼叫，涵蓋
POST /api/v1/http-requests/:id/test。
若任一項超出限制，系統將回傳 429 狀態碼，並附上說明訊息「error」。執行預算刻意設定得相當緊湊：相較於腳本執行緩慢，一個失控的迴圈不斷向支付服務商發送即時請求，將造成更嚴重的故障。
預算是以「金鑰」為單位，而非以「商店」為單位，因此某個整合操作不會耗盡另一個的配額。