核心概念

深入了解快速入門中介紹的術語。

1. API

用於程式之間交換資料的通信協議。

在 3Min API 中：

• 無需後端程式碼即可建立 API
• 接收標準 JSON 資料
• 資料自動存儲，可透過 Webhook 轉發

2. 端點

接收資料的 API 地址。一個 API = 一個端點。

每個端點包含：

• 唯一 URL 路徑（自動生成）
• 必填欄位（可選）
• 沙箱/正式環境隔離
• 各環境獨立的 API 金鑰 (tm_test_xxx..., tm_live_xxx...)

3. JSON

3Min API 接受標準 JSON 資料。

支援的欄位類型：

示例（訂單資訊）：

{
  "order_id": "ORD-2024-001",
  "amount": 45000,
  "items": ["Item A", "Item B"],
  "paid": true,
  "customer": {
    "name": "John Doe",
    "phone": "010-1234-5678"
  }
}

4. 必填欄位（可選）

您可以指定 JSON 資料中必須包含的欄位。

設定必填欄位後：

• 缺少必填欄位的請求將被拒絕（400 錯誤）
• 確保資料質量
• 字串欄位可設為可搜尋，用於日誌檢索

5. 沙箱 vs 正式環境

• 環境由 API 金鑰前綴決定
• 每個環境可單獨設定 Webhook
• 部署到正式環境前請在沙箱中充分測試

6. API 金鑰

調用端點時用於身份認證。所有者的預設 API 金鑰在建立端點時自動生成，不可刪除。如金鑰泄露，可重新生成。

協作金鑰

建立協作金鑰並邀請協作者，按協作金鑰分別管理日誌和統計資料。

按協作金鑰篩選日誌，跟蹤每個協作金鑰的使用情況。

為每個協作金鑰設定允許的操作（POST/GET/PUT/DELETE），每個環境獨立設定。

7. Webhook

資料到達時自動傳送通知到指定 URL。

兩種類型的 Webhook：

重試政策：失敗後最多重試3次（間隔60秒）

注意：即使所有 Webhook 重試均失敗，您的資料仍會安全存儲。請在日誌中檢視 Webhook 狀態。

8. 事件通知（Discord / Slack / Telegram）

透過 Discord、Slack 或 Telegram 即時接收重要事件通知。

設定方式：儀表板 → API → 端點詳情 → 通知設定

支援的事件：

• Webhook 傳送失敗（僅通知受影響方）
• 月度用量達到80%警告（僅限所有者）
• 月度用量超出限制（僅限所有者）
• 新的部署請求（僅限所有者）
• 部署完成（僅限協作者）

注意：通知為盡力傳送。傳送失敗不會重試，通知歷史不會儲存。

9. 資料封存

正式資料在30天後自動封存。封存記錄的元資料（狀態、時間戳、Webhook 結果等）被保留，而 Payload（正文資料）被轉移到獨立存儲。

各環境政策：

封存後：

• 記錄在日誌列表中仍可見（元資料保留）
• Payload 搜尋僅限最近30天
• 可透過"檢視原始資料"檢視單條記錄的 Payload

封存下載：

• 位置：儀表板 > 封存
• JSONL.gz：包含所有系統欄位的完整記錄（原始封存）
• CSV：僅 Payload 欄位，遞歸展開（最大深度5），兼容 Excel（UTF-8 BOM）
• 每個文件包含一天的正式記錄
• 僅限付費方案