開發者 API
REST API v1
用 API 從自己的系統建立短網址、查詢點擊數。所有請求都送到 https://api.302uu.cc/v1,回應一律是 JSON。
- API 存取需要團隊方案,並由工作區擁有者在後台「模組」頁開啟「API 存取」。
- 擁有者在後台「設定 → API 金鑰」建立金鑰:每個工作區最多 10 把,分成唯讀與讀寫兩種。
- 金鑰只在建立時顯示一次,請存在伺服器的環境變數裡。API 不支援從瀏覽器直接呼叫(沒有 CORS),不要把金鑰放進網頁或 App。
認證
每個請求都在標頭帶上金鑰:Authorization: Bearer sk_302uu_…
curl https://api.302uu.cc/v1/links \
-H "Authorization: Bearer sk_302uu_你的金鑰"- 唯讀金鑰只能呼叫 GET;讀寫金鑰可以呼叫全部端點。
- 撤銷後立即失效。建立金鑰的擁有者離開工作區、被停權或不再是擁有者時,他建立的金鑰也會失效。
- 模組關閉或方案不含 API 時,所有金鑰暫時失效;重新開啟就恢復。
速率限制與額度
- 每把金鑰每分鐘 120 次請求。超過時回
429 rate_limited,並附Retry-After: 60標頭。 - 建立連結與後台共用同一份每日額度與總數上限,也經過同樣的網址安全檢查。
錯誤
失敗時回對應的 HTTP 狀態碼,內容一律是:
{
"error": {
"code": "alias_taken",
"message": "這個短碼已被使用"
}
}| code | 狀態碼 | 說明 |
|---|---|---|
unauthorized | 401 | 沒有帶 Authorization 標頭,或格式不是 Bearer <金鑰> |
invalid_api_key | 401 | 金鑰不存在、已撤銷,或建立它的擁有者已不在工作區 |
insufficient_scope | 403 | 唯讀金鑰呼叫了 GET 以外的端點 |
workspace_suspended | 403 | 工作區已被停權 |
module_disabled | 403 | 工作區沒有開啟「API 存取」模組(或設定分享預覽時沒開「社群預覽」) |
plan_required | 403 | 方案不含 API、查詢的期間超過方案的數據期限,或品牌網域數超過方案上限(例如降級後);error 裡有 requiredPlan |
not_found | 404 | 找不到這條連結(包括不屬於這個工作區的連結) |
invalid_request | 400 | 請求內容不正確;error.path 是第一個有問題的欄位 |
invalid_cursor | 400 | cursor 不是上一頁回傳的 nextCursor |
domain_not_found | 400 | domain 不是這個工作區能用的網域 |
target_blocked/target_unsafe | 400 | 目標網址被封鎖或判定為不安全 |
not_allowed_with_301 | 400 | 301 不能同時設定分流規則或內建瀏覽器引導 |
not_allowed_with_password | 400 | 密碼保護的連結不能自訂分享預覽 |
alias_format/alias_reserved | 422 | 短碼格式不對或是系統保留字 |
alias_taken | 409 | 短碼已被使用 |
tag_limit | 409 | 工作區的標籤已達上限,不能再用新名稱 |
link_blocked | 409 | 這條連結已被平台封鎖,不能改回啟用 |
no_default_domain | 409 | 沒指定 domain,工作區也沒有可用的預設網域 |
quota_exceeded | 429 | 已達方案的每日連結額度;error 裡有 limit |
rate_limited | 429 | 超過每分鐘的請求數;依 Retry-After 等待後再試 |
連結物件
時間是 epoch 毫秒;tags 是標籤名稱;有設定分流規則或分享預覽時,另外有 rules 與 og(標題與描述)。
{
"id": "5f1c2a9e-8b1d-4c1e-9a53-0d7f0e2c4b11",
"shortUrl": "https://302uu.cc/fall",
"slug": "fall",
"domain": "302uu.cc",
"targetUrl": "https://shop.example.com/fall?utm_source=crm",
"title": "秋季特賣",
"status": "active",
"statusCode": 302,
"blocked": false,
"tags": ["活動"],
"expiresAt": null,
"maxClicks": null,
"hasPassword": false,
"createdAt": 1790467200000,
"updatedAt": 1790467200000
}端點
POST /v1/links
建立連結(讀寫金鑰),成功回 201 與連結物件。欄位:
targetUrl(必填):http 或 https 網址。UTM 請直接寫在網址裡。alias:自訂短碼,英數字、-與_,以英數字開頭,最長 64 字;省略就自動產生。title、statusCode(302 預設、307、301)、expiresAt、expiredUrl、maxClicks、password、rules、guideEnabled、passthroughQuery、trackingEnabled。tags:標籤名稱的陣列,最多 10 個;沒有的名稱會自動建立。domain:網域名稱(例如go.yourbrand.com),必須是工作區已啟用的網域;省略=預設網域。ogTitle、ogDescription:分享預覽(需要「社群預覽」模組)。
curl -X POST https://api.302uu.cc/v1/links \
-H "Authorization: Bearer sk_302uu_你的金鑰" \
-H "Content-Type: application/json" \
-d '{"targetUrl":"https://shop.example.com/fall","alias":"fall","title":"秋季特賣","tags":["活動"]}'GET /v1/links
列出連結,新到舊。參數:limit(1–100,預設 50)、cursor(上一頁的 nextCursor)、tag(標籤名稱)、slug(短碼,完全比對)、q(標題或目標網址的關鍵字)。
curl "https://api.302uu.cc/v1/links?limit=50&tag=活動" \
-H "Authorization: Bearer sk_302uu_你的金鑰"{
"data": [ { "id": "…", "slug": "fall", "…": "…" } ],
"nextCursor": "MTc5MDQ2NzIwMDAwMDo1ZjFjMmE5ZQ"
}nextCursor 是 null 表示已經是最後一頁。
GET /v1/links/{id}
取得一條連結。
PATCH /v1/links/{id}
修改連結(讀寫金鑰)。只送要改的欄位;null 代表清除;tags 給了就整組取代(空陣列=全部拿掉)。status 可以是 active、paused、disabled。網域建立後不能改。
curl -X PATCH https://api.302uu.cc/v1/links/5f1c2a9e-8b1d-4c1e-9a53-0d7f0e2c4b11 \
-H "Authorization: Bearer sk_302uu_你的金鑰" \
-H "Content-Type: application/json" \
-d '{"title":"秋季特賣(延長)","status":"paused"}'DELETE /v1/links/{id}
刪除連結(讀寫金鑰),成功回 204。刪除後這個短碼不能再用。
curl -X DELETE https://api.302uu.cc/v1/links/5f1c2a9e-8b1d-4c1e-9a53-0d7f0e2c4b11 \
-H "Authorization: Bearer sk_302uu_你的金鑰"GET /v1/links/{id}/stats
每日點擊數(不含機器人)。參數 from、to 是工作區時區的日期(YYYY-MM-DD),預設最近 30 天、最長 366 天;查詢期間超過方案的數據期限時回 403 plan_required。
curl "https://api.302uu.cc/v1/links/5f1c2a9e-8b1d-4c1e-9a53-0d7f0e2c4b11/stats?from=2026-09-01&to=2026-09-07" \
-H "Authorization: Bearer sk_302uu_你的金鑰"{
"total": 42,
"daily": [
{ "date": "2026-09-01", "clicks": 10 },
{ "date": "2026-09-02", "clicks": 0 }
]
}