端點詳細
概述
端點詳細是處理單個端點所有設定的頁面。在這一個頁面上您可以：
- 查看和編輯端點資訊（名稱、描述、URL、版本）
- 切換啟用 / 停用
- 部署和重新部署到正式環境
- 管理預設 API 金鑰
- 新增和刪除必填欄位
- 設定 Webhook
- 刪除端點
協作金鑰管理（簽發金鑰、邀請、權限）在單獨的頁面處理。詳情請參閱協作金鑰。
如果您以協作者身分參與，只會顯示您有權限存取的部分（所有者專屬部分自動隱藏）。
如何進入
- 頂部選單 APIs → 點擊列表中的端點名稱
- 儀表板最近活動 → 點擊端點
- 完成新手引導步驟 1 後自動跳轉
免費方案警告橫幅
使用免費方案時顯示在頂部。免費方案下可以隨意建立和試用端點。端點會在建立 7 天後自動清理，但您隨時可以建立新的——放心嘗試。
啟用/停用和部署按鈕
僅所有者可見。
- 啟用/停用按鈕（電源圖示）：當您想要暫時暫停所有環境的 API 呼叫時使用。停用期間呼叫被拒絕，但資料保留。
部署到正式環境按鈕（僅沙箱環境分頁）：- 將目前沙箱環境設定複製到正式環境
- 條件：必須在沙箱環境中完成至少 1 次測試呼叫後才可啟用
如果協作者存取此頁面，會顯示 請求部署 按鈕，向所有者傳送部署請求訊息。
環境分頁
頁首列下方有 沙箱環境 | 正式環境 分頁。兩個環境完全獨立。
推薦的工作流程是：在沙箱環境中測試並與協作者討論 → 部署到正式環境 → 營運。需要變更時，先在沙箱環境修改再重新部署。
沙箱環境
- 使用沙箱環境 API 金鑰（
tm_test_）呼叫的環境 - 僅用於測試。上線前可以自由實驗
- 沙箱環境資料30 天後自動刪除（所有方案）
正式環境
- 使用正式環境 API 金鑰（
tm_live_）呼叫的環境 - 用於正式營運。記錄至少保留 30 天，之後按月整批刪除。需要長期保存的資料請透過 Webhook 或清單 API 在記錄抵達時匯出
- 正式環境部署前，正式環境金鑰呼叫將被拒絕且不記錄日誌
概覽卡片
包含端點基本資訊的區域。
| 項目 | 說明 |
|---|---|
| 描述 | 端點描述。所有者可在沙箱環境分頁內聯編輯 |
| 端點 URL | 實際 API 呼叫地址。**向此 URL 傳送 POST/GET/PUT/DELETE 請求。**提供複製按鈕 |
| 版本 | 設定版本。每次部署遞增 |
| 建立時間 | 端點建立時間 |
| 更新時間 | 最後一次設定變更時間（沙箱環境） |
| 發佈時間 | 正式環境部署時間（僅正式環境分頁） |
預設 API 金鑰
僅所有者可見。
- 端點建立時簽發的預設 API 金鑰
- 用於測試與整合指南頁面的認證，可透過右側的立即測試按鈕存取
- 顯示 / 隱藏 切換，在螢幕上隱藏或顯示金鑰
- 重新生成 按鈕：舊金鑰立即失效。僅在懷疑洩漏時使用
協作者存取時，此區域替換為其分配的協作金鑰卡片。
協作金鑰
此處僅提供摘要卡片——金鑰建立、邀請和權限管理在單獨的管理頁面進行。
- 所有者檢視：
檢視全部按鈕和每個協作者的摘要（名稱、邀請數） - 協作者檢視：分配給您的金鑰的權限標籤
詳細說明請參閱協作金鑰。
必填欄位
定義 API 呼叫中必須包含的 JSON 欄位。詳細說明請參閱建立新端點。
- 要新增或編輯欄位，點擊
編輯按鈕 - 編輯時可以新增、刪除和更改欄位類型。完成後點擊
儲存或取消 - 儲存後更新沙箱環境設定——要套用到正式環境，需要重新部署
- 即使部署後，修改必填欄位不影響已儲存的資料。更新的欄位規則僅適用於新的傳入呼叫
Webhook
僅所有者可見。
API 呼叫成功處理後，可以向指定的 Webhook URL 傳送二次請求。無論 Webhook 是否成功，資料儲存始終完成。
輸入欄位
- Webhook URL：接收 Webhook 的地址（建議 HTTPS）
- Auth Header（可選）：認證標頭鍵。預設
Authorization - Auth Value（可選）：認證標頭值。範例：
Bearer abc123
對於不需要認證的 Webhook（簡單接收器、URL 中嵌入 Token 等），留空認證欄位即可。
Webhook 策略摘要
- 逾時：必須在 15 秒內回應。逾時視為失敗
- 回應狀態碼：2xx 表示「我收到了」，而不是「處理成功了」。即使你這邊的處理失敗也要回傳 2xx，並把該失敗記錄在你自己的系統裡。5xx 表示投遞根本沒有送達，我們會按下方的重試排程反覆重送同一筆記錄，你的接收端每次都會把同一份工作再執行一遍
- 重試：正式環境共 6 次嘗試——首次投遞 1 次 + 重試 5 次（30 秒·2 分·10 分·1 小時·4 小時，約 5 小時）。沙箱環境共 4 次嘗試——首次投遞 1 次 + 重試 3 次（30 秒·2 分·10 分，約 12 分鐘）
- 會重試：5xx、429、逾時、連線錯誤。若 429 附帶
Retry-After，我們會相應地多等一段時間（不會短於預設間隔） - 不重試：除 429 外的所有 4xx，包括 409。修正設定後，下次呼叫即可正常送達
- 查看失敗：投遞失敗或仍在重試的紀錄會出現在日誌頁面的 Webhook 投遞中。成功送達的 Webhook 不會被記錄
- 電子郵件通知：一旦放棄投遞（重試用盡，或永久性回應），我們會寄信通知您，不分方案（免費方案同樣適用），但僅限正式環境 Webhook，每個端點每天最多一封，且沒有復原通知。協作者 Webhook 的失敗不會寄送郵件——因為您無法變更該 URL
- 冪等性：每次嘗試都攜帶相同的
X-3minapi-Record-Id。請用它判斷重複 - 簽章：每個請求都帶有 HMAC-SHA256 簽章（
webhook-signature）。詳情請參見下方的 Webhook 簽章密鑰
Webhook 簽章密鑰
位於 Webhook 設定卡片正下方。它不是擁有者專屬區域，協作者同樣可以檢視 — 因為協作者透過 X-Webhook-Callback 自行接收的 Webhook 也使用同一個密鑰簽章。
- 依環境區分 — 沙箱分頁和正式分頁的密鑰各自獨立。請使用你所接收環境的那一個
- 擁有者和協作者都可以檢視
- 只有擁有者可以重新簽發（輪換）。 協作者的畫面上不會出現重新簽發按鈕
- 這不是需要定期輪換的值。 重新簽發是密鑰外洩時的因應手段
- 重新簽發後，24 小時內會同時傳送新舊兩個簽章。在這段時間內的任意時刻更換接收伺服器上的值，都不會遺失投遞。寬限期內卡片上會顯示到期時間橫幅
拿到這個值之後該怎麼用，請參見驗證 Webhook 簽章。
Webhook Payload
API 呼叫處理後，以下 JSON Payload 將傳送到 Webhook URL。您可以展開截圖中的 Webhook Payload 示例 區域查看實際格式。
| 欄位 | 說明 |
|---|---|
| id | 儲存記錄的唯一 ID |
| operation | 執行的操作（create、update、delete） |
| status | 處理結果（success、failed） |
| endpoint_slug | 端點識別碼 |
| payload | 呼叫者傳送的原始 JSON 資料，原樣包含（delete 時為 null） |
| target_record_id | 目標記錄 ID（update/delete 時包含） |
| processed_at | 處理完成時間 |
協作者 Webhook
如果協作者需要 Webhook，可以在 API 請求中包含 X-Webhook-Callback 等標頭來設定自己的 Webhook。協作者 Webhook 與所有者 Webhook 獨立運作，Payload 格式相同。詳細設定說明請參閱測試與整合指南。
協作者 Webhook 與擁有者 Webhook 適用相同的重試策略和相同的簽章。用於驗證簽章的密鑰可在上方的 Webhook 簽章密鑰卡片中檢視。
危險區域
僅所有者可見。
刪除端點按鈕- 刪除後立即且永久移除：
- 端點設定本身
- 沙箱環境和正式環境的所有 API 記錄
- 相關統計 / 部署請求 / Webhook / 協作金鑰
- 協作者也將失去存取權限
- 無法復原 — 確認對話框中必須輸入端點名稱才能繼續
右側邊欄
詳細頁面右側根據環境顯示不同的快捷卡片。
API 呼叫記錄
跳轉到可以查看該端點 API 呼叫結果的頁面。您可以詳細查看請求成功/失敗、Payload、Webhook 狀態等。
沙箱環境測試
在沙箱環境分頁顯示。
跳轉到可以直接在瀏覽器中測試 API 呼叫和查看整合方法的頁面。詳情請參閱測試與整合指南。
正式控制台
在正式環境分頁顯示，部署後僅所有者可見。
直接從儀表板管理正式環境資料的控制台。適用於預先填充產品列表或公告，供協作者透過 GET 取得。支援 POST（建立）、GET（讀取）、PUT（更新）和 DELETE（刪除）。控制台使用所有者的 API 金鑰執行，不會觸發協作者 Webhook。如果設定了所有者 Webhook，則正常觸發。詳情請參閱正式控制台。
部署請求通知
在沙箱環境分頁顯示。
協作者請求了正式環境部署時顯示。該通知也會透過電子郵件傳送，不會錯過。點擊 檢視全部 按鈕查看完整的部署請求歷史。
常見問題
- 部署按鈕被停用：可能是沙箱環境中沒有進行過測試呼叫，或者最新的沙箱環境版本已經部署到了正式環境。請先在沙箱環境中執行測試
- 正式環境分頁沒有記錄：部署前正式環境呼叫會被拒絕，因此不記錄日誌。請檢查部署是否成功，以及是否使用了
tm_live_金鑰 - 必填欄位已更改但未反映在正式環境：沙箱環境的更改不會自動套用到正式環境。請再次點擊
部署到正式環境 - Webhook 未到達：Webhook 伺服器必須在 15 秒內回應。請檢查伺服器是否可公開存取且使用 HTTPS。Discord 和 Slack 等平台有自己的速率限制——如果短時間內觸發了過多 Webhook，部分可能會被攔截。請同時檢查接收平台的速率限制政策