核心概念

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

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. 任務

任務讓 ChatGPT、Claude 等 AI 把工作交給您自己的 HTTP 伺服器（Worker），並把結果帶回對話。3Min API 只負責投遞任務與記錄狀態，實際工作由 Worker 完成。

任務的執行流程：

AI 以 Worker 名稱與 input 呼叫 task_create，任務以 working 狀態開始
3Min API 向 Worker URL 傳送帶簽章的 POST，內容包含 callback_url
Worker 立即回傳 2xx 後再開始工作。2xx 表示「已收到」，不是結果
完成後，Worker 向 callback_url 回報 completed 或 failed。之前的進度訊息為選用
AI 透過 task_get 讀取結果並顯示在對話中

Webhook 與任務：

項目	Webhook	任務
作用	通知紀錄已到達	把工作交給您的伺服器
何時結束	投遞收到 2xx 時	Worker 回報 completed 或 failed，或超過期限時
需要	15 秒內回應的公開 URL	擁有公開 URL 的已註冊 Worker，以及向 callback_url 的回報

注意事項：

公開 Worker 需要公開 URL。自己電腦上的程式碼可以透過 3Min API CLI 以本機 Worker 執行，不需要公開 URL
24 小時內未完成的任務會變為 failed
投遞為 at-least-once，同一任務可能到達兩次，請依任務 ID 去除重複
註冊 Worker 以及查看、輪換金鑰只能在網頁儀表板中進行。AI 看不到 URL 與金鑰

Worker 實作約定、簽章驗證與範例程式碼：任務指南

10. 資料保留

記錄只保留有限的時間。請把 Webhook 或輪詢端點——而不是儀表板——當作資料離開 3Min API 的通道。

各環境政策：

環境	政策	備註
正式（付費方案）	至少保留 60 天	超過保留期後按月整批刪除
沙箱（付費方案）	30 天後自動刪除	用於測試，不是儲存空間
免費方案	端點建立 7 天後全部刪除	按端點刪除

如何匯出資料：

Webhook：記錄一抵達就推送到您指定的 URL
輪詢：自行取回上次呼叫之後抵達的記錄——參見上方第 8 節
日誌：在保留期內可在儀表板查看或搜尋單筆記錄
使用統計單獨保存，不隨記錄刪除，儀表板圖表保持完整