測試與整合指南
概述
這是在端點詳細頁面點擊立即測試後開啟的頁面。您可以直接在瀏覽器中測試 API 呼叫，無需任何額外工具，還可以與協作者分享，讓他們在一個地方找到整合所需的所有資訊。
此頁面的測試僅在沙箱環境中進行。不會影響正式環境資料，請放心實驗。
頁面有兩個分頁：
- 快速開始 — 使用 API 金鑰認證並立即測試呼叫
- 指南 — 面向所有者和協作者的整合參考（分步指南、API 端點、標頭、欄位定義、程式碼範例等）
如何進入
- 端點詳細右側邊欄 > 立即測試 按鈕（沙箱環境分頁）
- 協作者接受邀請後也可以從自己的儀表板存取
端點資訊
- 顯示端點名稱和描述
- 旁邊顯示環境標籤（沙箱環境）和版本資訊
- 在 快速開始 / 指南 分頁之間切換
快速開始分頁
認證
要開始測試，需要先使用 API 金鑰進行認證。
認證後，輸入框消失，顯示 退出 按鈕。要使用其他金鑰測試，先退出再重新認證。
試一試
認證後，CRUD 呼叫執行區域被啟用。選擇方法，輸入請求主體（JSON），點擊 Execute 即可立即看到結果。
如果想一次性測試完整流程，請按以下順序進行：
完整 CRUD 測試指南
CREATE (POST) — 在請求主體中輸入測試 JSON 並執行。從回應中複製
id——後續步驟需要用到。READ (GET) — 將
id貼到 Record ID 欄位並執行。驗證剛建立的資料是否正確回傳。UPDATE (PUT) — 輸入相同的
id，並在請求主體中提供修改後的 JSON。這是完全替換，所以要保留的欄位和要更改的欄位都需要包含。DELETE — 輸入相同的
id並執行。之後再試一次 READ，確認記錄已被刪除。
權限檢查：使用協作金鑰測試時，只能執行該金鑰權限允許的方法。呼叫未授權的方法回傳 403 錯誤。請在協作金鑰 > 權限中查看權限。
協作者 Webhook
試一試區域底部有一個可摺疊的 Webhook 設定區域。這與所有者在儀表板設定的 Webhook 不同——它是讓 API 呼叫者在請求標頭中包含 Webhook 資訊，以便在指定的 URL 接收處理結果。您可以在此測試這些標頭。
- 與所有者 Webhook 獨立運作
- 在實際整合中，Webhook 標頭直接包含在 API 呼叫程式碼中
- 詳細的標頭名稱和實作方法請參閱指南分頁的 Webhook 設定部分
指南分頁
指南分頁的結構讓所有者和協作者都可以在一個地方查看完整的整合流程和技術細節。頂部是角色專屬的分步指南，下方是技術參考。
入門 — 所有者
選擇 我建立了端點 分頁，從所有者的視角查看步驟。
- 建立端點 — 只需設定 API 名稱，CRUD 自動建立。描述和必填欄位可以稍後新增
- 沙箱環境測試和日誌檢查 — 在快速開始分頁使用預設 API 金鑰發起呼叫，然後在儀表板日誌中驗證資料接收
- 建立協作金鑰並邀請 — 在詳細頁面建立金鑰並傳送電子郵件邀請
- 整合測試 — 透過日誌共同驗證協作者在沙箱環境中的呼叫是否正確
- 正式環境部署 — 批准協作者的部署請求，或直接部署。部署後協作者會收到通知
入門 — 協作者
選擇 我被邀請了 分頁，從協作者的視角查看步驟。
- 接受邀請 — 查看邀請郵件，登入後在儀表板上接受
- 查看 API 金鑰 — 在端點詳細頁面找到您的沙箱環境 API 金鑰（
tm_test_） - 整合和測試 — 在快速開始分頁測試呼叫，參考指南分頁的技術資訊進行開發。如果收到 202 回應，說明系統保證處理
- 請求部署 — 測試完成後，在端點詳細頁面提交部署請求
- 切換到正式環境 — 所有者完成部署後您會收到通知。從正式環境分頁查看並套用正式環境 API 金鑰（
tm_live_）
API 端點
顯示該端點可用的 API 路徑和方法。建立端點時自動準備四種方法。
| 方法 | 路徑 | 說明 |
|---|---|---|
| POST | /api/v1/data/{slug} |
建立新記錄 |
| GET | /api/v1/data/{slug}/{record_id} |
取得記錄 |
| PUT | /api/v1/data/{slug}/{record_id} |
替換記錄 |
| DELETE | /api/v1/data/{slug}/{record_id} |
刪除記錄 |
{slug} 是端點建立時自動分配的唯一識別碼。您可以在此頁面查看實際值。
API 金鑰
API 呼叫認證所需的金鑰資訊。
| 環境 | 金鑰前綴 | 用途 |
|---|---|---|
| 沙箱環境 | tm_test_ |
開發和測試 |
| 正式環境 | tm_live_ |
正式服務 |
正式環境 API 金鑰可在部署完成後在端點詳細頁面找到。部署前，使用正式環境金鑰的呼叫將被拒絕。
請求標頭
API 呼叫中需要包含的 HTTP 標頭。Content-Type 和 Authorization 為必要；Webhook 標頭僅在需要時新增。
| 標頭 | 是否必要 | 說明 |
|---|---|---|
Content-Type |
必要 | application/json（用於 POST/PUT） |
Authorization |
必要 | Bearer {API_KEY} 格式 |
X-Webhook-Callback |
可選 | 接收呼叫者 Webhook 的 URL |
X-Webhook-Auth |
可選 | Webhook 認證值（例如 Bearer token） |
X-Webhook-Auth-Header |
可選 | Webhook 認證標頭鍵（預設：Authorization） |
請求主體
關於 POST/PUT 請求傳送的 JSON 請求主體的資訊。
- 格式：JSON（
application/json）· 最大 100KB · UTF-8 - 如果所有者定義了必填欄位，這些欄位必須包含。必填欄位以外的額外欄位可以自由傳送
- 如果未定義必填欄位，任何 JSON 都可接受
- 請求非同步處理。您會立即收到 202 回應，實際儲存和 Webhook 傳送在背景進行
回應格式
顯示各方法的成功回應和錯誤代碼。
成功回應：
- POST/PUT/DELETE →
202 Accepted（請求已接受並加入佇列） - GET →
200 OK（資料立即回傳）
錯誤代碼：
| 代碼 | 狀態 | 含義 |
|---|---|---|
| 400 | Bad Request | 無效 JSON、缺少必填欄位、無效記錄 ID |
| 401 | Unauthorized | API 金鑰缺失或無效 |
| 403 | Forbidden | 端點未啟用、無訂閱或權限不足 |
| 415 | Unsupported Media Type | Content-Type 不是 application/json |
| 429 | Too Many Requests | 月度使用量超出限額 |
| 5xx | Server Error | 暫時伺服器錯誤——請實作重試邏輯 |
如果收到 5xx 錯誤，請求未到達伺服器。請在程式碼中實作重試邏輯（例如 1 秒 → 2 秒 → 4 秒退避）。如果收到 202 回應，系統保證處理。
Webhook 設定
設定呼叫者 Webhook 以自動接收處理結果的說明。與所有者在儀表板設定的 Webhook 獨立運作。
設定方法：在 API 呼叫中包含以下標頭。
| 標頭 | 是否必要 | 說明 |
|---|---|---|
X-Webhook-Callback |
必要 | 接收 Webhook 的 URL |
X-Webhook-Auth |
可選 | 認證值（例如 Bearer token） |
X-Webhook-Auth-Header |
可選 | 認證標頭鍵（預設：Authorization） |
重試策略：
- 失敗後最多重試 3 次（1-2 秒退避）
- 成功標準：2xx 狀態碼
- 即使 3 次嘗試全部失敗，資料仍安全儲存。在日誌中查看 Webhook 狀態
程式碼範例
提供包括 curl、JavaScript 和 Python 在內的主要語言的 API 呼叫程式碼範例。切換分頁查看各語言的範例。實際端點 URL 和必要標頭已預先填入，可以直接複製使用。
常見問題
- 點擊授權後沒有反應：請檢查 API 金鑰是否以
tm_test_（沙箱環境金鑰）開頭。正式環境金鑰（tm_live_）不能在此頁面使用 - CREATE 後遺失了 ID：再次呼叫 CREATE 產生新記錄繼續測試。如果需要之前記錄的 ID，請在儀表板日誌頁面查看呼叫歷史
- 收到 403 錯誤：您使用的協作金鑰可能沒有該方法的權限。請在協作金鑰 > 權限中查看
- Webhook 未到達：Webhook 伺服器必須在 7 秒內回應。請檢查是否可公開存取且使用 HTTPS。Discord 和 Slack 等平台有速率限制——如果短時間內觸發了過多 Webhook，部分可能會被攔截