核心概念
深入了解快速入門中介紹的術語。
1. API
用於程式之間交換資料的通信協議。
在 3Min API 中：
- 無需後端程式碼即可建立 API
- 接收標準 JSON 資料
- 資料自動存儲，可透過 Webhook 轉發
2. 端點
接收資料的 API 地址。一個 API = 一個端點。
每個端點包含：
- 唯一 URL 路徑（自動生成）
- 必填欄位（可選）
- 沙箱/正式環境隔離
- 各環境獨立的 API 金鑰 (
tm_test_xxx...,tm_live_xxx...)
3. JSON
3Min API 接受標準 JSON 資料。
支援的欄位類型：
| String | 文本 | Example |
|---|---|---|
| string | 文本 | "hello" |
| number | 數字 | 123, 45.67 |
| boolean | 真/假 | true, false |
| array | 列表 | [1, 2, 3] |
| object | 巢狀資料 | {"key": "value"} |
示例（訂單資訊）：
{
"order_id": "ORD-2024-001",
"amount": 45000,
"items": ["Item A", "Item B"],
"paid": true,
"customer": {
"name": "John Doe",
"phone": "010-1234-5678"
}
}4. 必填欄位（可選）
即使不定義必填欄位，也可接受標準 JSON。
您可以指定 JSON 資料中必須包含的欄位。
設定必填欄位後：
- 缺少必填欄位的請求將被拒絕（400 錯誤）
- 確保資料質量
5. 沙箱 vs 正式環境
| 環境 | API 金鑰 | 用途 |
|---|---|---|
| 沙箱 | tm_test_xxx... | 開發和測試 |
| 正式 | tm_live_xxx... | 正式服務 |
- 環境由 API 金鑰前綴決定
- 每個環境可單獨設定 Webhook
- 部署到正式環境前請在沙箱中充分測試
6. API 金鑰
調用端點時用於身份認證。所有者的預設 API 金鑰在建立端點時自動生成，不可刪除。如金鑰泄露，可重新生成。
| API 金鑰 | 環境 | 用途 |
|---|---|---|
tm_test_xxx... | 沙箱 | 用於測試，不影響正式環境 |
tm_live_xxx... | 正式 | 用於正式服務，處理真實資料 |
API 金鑰泄露時請立即重新生成。
協作金鑰
建立協作金鑰並邀請協作者，按協作金鑰分別管理日誌和統計資料。
按協作金鑰篩選日誌，跟蹤每個協作金鑰的使用情況。
為每個協作金鑰設定允許的操作（POST/GET/PUT/DELETE），每個環境獨立設定。讀取（GET）權限同時適用於單筆、清單、搜尋查詢。
7. Webhook
資料到達時自動傳送通知到指定 URL。
兩種類型的 Webhook：
| Webhook | 設定位置 | 描述 |
|---|---|---|
| 所有者 Webhook | 儀表板 → API → 端點詳情 | 接收所有 API 調用通知 |
| 協作者 Webhook | 調用 API 時的請求頭 | 協作者直接接收處理結果 |
重試政策：請在 15 秒內回傳 2xx。失敗後從佇列以小時級間隔重試
注意：即使所有 Webhook 重試均失敗，您的資料仍會安全存儲。請在日誌中檢視 Webhook 狀態。
8. 輪詢
接收資料的另一種方式。不是由我們呼叫您的 URL，而是您的用戶端循環呼叫輪詢端點，只取回上次呼叫之後抵達的記錄。
Webhook 與輪詢比較：
| 比較項目 | Webhook（推送） | 輪詢（拉取） |
|---|---|---|
| 由誰發起 | 3Min API 呼叫您 | 您的用戶端呼叫我們 |
| 前提條件 | 一個能在 15 秒內回應的公開 URL | 不需要任何連入連線，只要能送出 HTTPS 請求 |
| 延遲 | 記錄儲存後數秒 | 一個輪詢週期，再加約 60 秒的沉澱延遲 |
| 費用 | 免費——投遞不計入 API 呼叫 | 每次輪詢請求計一次 API 呼叫，空回應也計 |
如果接收方有公開 URL，並且需要在資料抵達時立即回應，請選 Webhook。這是預設選擇。
如果沒有公開 URL——本機開發、內網、防火牆之後、沒有常駐伺服器——或者接收方需要自己控制節奏，請選輪詢。
兩者並不互斥。同一個端點可以同時開啟：用 Webhook 做即時回應，再用每晚一次的輪詢補齊接收方漏掉的記錄。
請求範例：
# First call - since a point in time
GET /api/v1/data/my-endpoint/poll?since=2026-09-01
Authorization: Bearer tm_test_xxx
# Response - oldest first
{
"success": true,
"data": [ ... ],
"pagination": {
"limit": 100,
"poll_cursor": "eyJ0IjoiMjAyNi0wOS0wMVQwMDowMDowMFoifQ"
}
}
# Next call - send the cursor back
GET /api/v1/data/my-endpoint/poll?cursor=eyJ0IjoiMjAyNi0wOS0wMVQwMDowMDowMFoifQ游標的運作方式：
- 首次呼叫可以帶 since（RFC 3339 或 YYYY-MM-DD，一律以 UTC 解讀），也可以什麼都不帶，那就表示從此刻開始訂閱。since 與 cursor 不能同時送出。
- next_cursor 表示還有積壓——請立即再次呼叫
- poll_cursor 表示已經追平——請保存它，等到下一個週期
- 記錄按從舊到新回傳，每頁最多 100 筆（limit，1-100）。每次回應只會包含兩個游標中的一個
最近 60 秒左右的記錄會在佇列追平之前暫時保留，因此只是延後到之後的輪詢，而不是被略過。重試與重新啟動可能重複投遞同一筆記錄，請依記錄 id 做冪等處理。
9. 資料保留
記錄只保留有限的時間。請把 Webhook 或輪詢端點——而不是儀表板——當作資料離開 3Min API 的通道。
各環境政策：
| 環境 | 政策 | 備註 |
|---|---|---|
| 正式（付費方案） | 至少保留 60 天 | 超過保留期後按月整批刪除 |
| 沙箱（付費方案） | 30 天後自動刪除 | 用於測試，不是儲存空間 |
| 免費方案 | 端點建立 7 天後全部刪除 | 按端點刪除 |
如何匯出資料：
- Webhook：記錄一抵達就推送到您指定的 URL
- 輪詢：自行取回上次呼叫之後抵達的記錄——參見上方第 8 節
- 日誌：在保留期內可在儀表板查看或搜尋單筆記錄
- 使用統計單獨保存，不隨記錄刪除，儀表板圖表保持完整