開發者 API

REST API v1

用 API 從自己的系統建立短網址、查詢點擊數。所有請求都送到 https://api.302uu.cc/v1,回應一律是 JSON。

認證

每個請求都在標頭帶上金鑰:Authorization: Bearer sk_302uu_…

curl https://api.302uu.cc/v1/links \
  -H "Authorization: Bearer sk_302uu_你的金鑰"

速率限制與額度

錯誤

失敗時回對應的 HTTP 狀態碼,內容一律是:

{
  "error": {
    "code": "alias_taken",
    "message": "這個短碼已被使用"
  }
}
code狀態碼說明
unauthorized401沒有帶 Authorization 標頭,或格式不是 Bearer <金鑰>
invalid_api_key401金鑰不存在、已撤銷,或建立它的擁有者已不在工作區
insufficient_scope403唯讀金鑰呼叫了 GET 以外的端點
workspace_suspended403工作區已被停權
module_disabled403工作區沒有開啟「API 存取」模組(或設定分享預覽時沒開「社群預覽」)
plan_required403方案不含 API、查詢的期間超過方案的數據期限,或品牌網域數超過方案上限(例如降級後);error 裡有 requiredPlan
not_found404找不到這條連結(包括不屬於這個工作區的連結)
invalid_request400請求內容不正確;error.path 是第一個有問題的欄位
invalid_cursor400cursor 不是上一頁回傳的 nextCursor
domain_not_found400domain 不是這個工作區能用的網域
target_blocked/target_unsafe400目標網址被封鎖或判定為不安全
not_allowed_with_301400301 不能同時設定分流規則或內建瀏覽器引導
not_allowed_with_password400密碼保護的連結不能自訂分享預覽
alias_format/alias_reserved422短碼格式不對或是系統保留字
alias_taken409短碼已被使用
tag_limit409工作區的標籤已達上限,不能再用新名稱
link_blocked409這條連結已被平台封鎖,不能改回啟用
no_default_domain409沒指定 domain,工作區也沒有可用的預設網域
quota_exceeded429已達方案的每日連結額度;error 裡有 limit
rate_limited429超過每分鐘的請求數;依 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 與連結物件。欄位:

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 }
  ]
}