把短連結，接進你的工作流。

快速開始

1. 由站主管理帳號以 Google 登入，在 API 管理頁建立 Token。
2. 把 Token 存為後端環境變數 ZUOIN_TOKEN。
3. 呼叫 POST /v4/shorten，使用回應的 link 欄位分享短網址。

curl --fail-with-body --max-time 30 https://zuo.in/v4/shorten \
  -H "Authorization: Bearer $ZUOIN_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"long_url":"https://example.com/"}'

新建立的短連結回傳 201 Created；相同帳號已存在相同最終目的地時，回傳 200 OK 並重用連結。兩者都是成功。

{
  "id": "zuo.in/7Ab",
  "link": "https://zuo.in/7Ab",
  "long_url": "https://example.com/",
  "title": "",
  "created_at": "2026-10-18T00:00:00Z",
  "created_by": "zuola",
  "archived": false,
  "tags": [],
  "custom_bitlinks": [],
  "deeplinks": [],
  "references": {"group": "https://zuo.in/v4/groups/ZuoinGroup"}
}

以上短碼與時間是回應格式示例；請使用實際回應值。

授權與權限

每個 API 請求必須帶 Authorization: Bearer <ZUOIN_TOKEN>。zuo.in Token 以 zui_ 開頭，與 Bitly Token 不通用。

這是佐拉的專屬短網址服務。目前只有站主管理帳號可建立、撤銷 Token 及使用 API；一般 Google 登入訪客不會取得 API 權限。需要品牌專屬部署或整合，請參考定製服務。

每個管理帳號同時只有一個有效 Token。新 Token 只顯示一次，重新產生會立即使舊 Token 失效，撤銷後也立即失效。資料庫只儲存 Token 的 SHA-256 摘要。

請將 Token 放在伺服器環境變數或 Secret 管理工具中，勿放入網址、瀏覽器 JavaScript、公開倉庫或日誌。agent 不應自動建立或輪替 Token；缺少憑證時，應請使用者在部署環境設定。

# 唯讀驗證 Token，不會建立短連結
curl --fail-with-body --max-time 30 https://zuo.in/v4/user \
  -H "Authorization: Bearer $ZUOIN_TOKEN"

給 AI coding agent

可將以下整合要求交給你的 coding agent；完整參數與回應結構請讀取 https://zuo.in/openapi.json。

Integrate the zuo.in URL shortener in the server-side application.
Documentation: https://zuo.in/docs
OpenAPI: https://zuo.in/openapi.json
API base: https://zuo.in/v4

1. Read ZUOIN_TOKEN from server-side secrets. Never expose or log it.
   Only the site owner can provision a token at /dashboard/api.
   If the token is missing, ask the user to configure it.
2. Verify credentials with GET /v4/user (read-only).
3. Create links with POST /v4/shorten and JSON {"long_url": "..."}.
   Accept both 200 (reused) and 201 (created); return response.link.
4. Keep force_new_link false/omitted for normal requests and retries.
   A retry with true can create another short link.
5. Use response.id (zuo.in/code) for lookup, expand and click APIs.
   Do not guess slugs or assume they are always three characters.
6. Use a 30-second client timeout. The service fetches the destination,
   follows redirects, requires a final HTTP 200 and stores the final URL.
7. Handle errors using HTTP status plus message/description/resource.
   Do not blindly retry 400, 401, 404 or 422. For temporary failures,
   use bounded retries with exponential backoff and jitter.
8. Do not use the browser-session-only /api/links for integrations.
   Do not invent PATCH/DELETE, custom slugs, tags, deeplinks or MCP APIs.
9. Use mocks for automated tests; create production links only when
   the user has authorized that operation.

建立短連結

POST /v4/shorten，也可用相同契約的 POST /v4/bitlinks。

JSON Body 上限 64 KiB。目的地檢查的逾時為 15 秒，重新導向限制為 10 次，最終回應必須為 HTTP 200；服務儲存的是重新導向後的最終網址。需登入、封鎖檢查器或回傳其他狀態碼的目的地，可能回傳 422。

相同目的地的重用不是交易級的 Idempotency-Key 保證。一般重試應保留 force_new_link=false；若使用 true 且第一次請求結果未知，重試可能再建立一條連結。

API 自動配置短碼，不支援指定短碼或到期時間。非空的 tags 或 deeplinks 會回傳 422 UNSUPPORTED_OPERATION。

查詢與還原

id 是 zuo.in/7Ab，link 是 https://zuo.in/7Ab。查詢路徑直接使用含網域的 ID，保留中間的斜線；只能查詢目前 Token 所屬帳號的連結。

# 取得完整連結資訊，回應格式與建立連結相同
curl --fail-with-body --max-time 30 https://zuo.in/v4/bitlinks/zuo.in/7Ab \
  -H "Authorization: Bearer $ZUOIN_TOKEN"

# 還原目的地；bitlink_id 可使用 ID 或完整 HTTP(S) 短網址
curl --fail-with-body --max-time 30 https://zuo.in/v4/expand \
  -H "Authorization: Bearer $ZUOIN_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"bitlink_id":"zuo.in/7Ab"}'

{
  "id": "zuo.in/7Ab",
  "link": "https://zuo.in/7Ab",
  "long_url": "https://example.com/",
  "created_at": "2026-10-18T00:00:00Z"
}

傳入的短網址不可包含 query、fragment 或使用者資訊。取得連結資料不會增加點擊數；開啟實際短網址會記錄一次重新導向。

點擊統計

# 最近七個日曆日的點擊總數（包含當日）
curl --fail-with-body --max-time 30 \
  'https://zuo.in/v4/bitlinks/zuo.in/7Ab/clicks/summary?unit=day&units=7' \
  -H "Authorization: Bearer $ZUOIN_TOKEN"

# 按日分桶，最新在前，包含零點擊的日期
curl --fail-with-body --max-time 30 \
  'https://zuo.in/v4/bitlinks/zuo.in/7Ab/clicks?unit=day&units=7' \
  -H "Authorization: Bearer $ZUOIN_TOKEN"

# 累計點擊總數；units=-1 僅支援 summary
curl --fail-with-body --max-time 30 \
  'https://zuo.in/v4/bitlinks/zuo.in/7Ab/clicks/summary?units=-1' \
  -H "Authorization: Bearer $ZUOIN_TOKEN"

{
  "unit": "day",
  "units": 7,
  "unit_reference": "2026-10-18T08:00:00Z",
  "total_clicks": 42
}

分桶端點將 total_clicks 改為 link_clicks 陣列，每筆包含 date 與 clicks。

• unit：minute、hour、day（預設）、week、month。
• units：1–366，預設 7；只有 summary 可使用 -1。
• unit_reference：選填 RFC3339，預設目前時間；以其所在日曆桶向前計算，週從星期日開始。
• timezone：省略或 0，只支援 UTC。網站報表採臺北時間，日期邊界可能不同。

統計由背景工作非同步寫入，可能稍有延遲。點擊數包含爬蟲與預覽請求，不等同真人或不重複訪客數。

端點總覽

下列路徑均以 https://zuo.in 為基底，全部需要 Bearer Token。

程式範例

JavaScript / Node.js（後端）

async function shorten(longUrl) {
  const token = process.env.ZUOIN_TOKEN;
  if (!token) throw new Error("Missing ZUOIN_TOKEN");

  const response = await fetch("https://zuo.in/v4/shorten", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({ long_url: longUrl }),
    signal: AbortSignal.timeout(30_000)
  });
  if (!response.ok) {
    throw new Error(`zuo.in API returned HTTP ${response.status}`);
  }
  const data = await response.json();
  return data.link;
}

Python（需安裝 requests）

import os
import requests

def shorten(long_url):
    response = requests.post(
        "https://zuo.in/v4/shorten",
        headers={"Authorization": f"Bearer {os.environ['ZUOIN_TOKEN']}"},
        json={"long_url": long_url},
        timeout=30,
    )
    if not response.ok:
        # Do not log the request headers or the token.
        raise RuntimeError(f"zuo.in API returned HTTP {response.status_code}")
    return response.json()["link"]

錯誤與限制

{
  "message": "UNAUTHORIZED",
  "description": "A zuo.in Bearer token is required.",
  "resource": "/v4/shorten"
}

這是 Bitly v4 的部分相容實作，不提供 Bitly OAuth、PATCH／DELETE、自訂短碼、任意網域、campaigns、webhooks 或 MCP。未支援的路徑可能回傳 404／405，且不保證 JSON；反向代理錯誤也可能是非 JSON 回應。

不要將舊的 /api/links 當作整合端點，它需要站主瀏覽器登入 Session。公開短網址、/{code}+ 報表與 /qr/{code} 不需要 Token，但不屬於這份 /v4 JSON API 契約。

WordPress 整合

使用官方 WP Bitly 2.8.1 時，另外安裝 zuo.in Bitly 轉接外掛，並在伺服器的 wp-config.php 設定 ZUOIN_API_TOKEN。此名稱是 WordPress 外掛的常數，對應前述範例的 ZUOIN_TOKEN。

define('ZUOIN_API_TOKEN', 'YOUR_ZUO_IN_TOKEN');

外掛會將短連結與統計請求轉送至 zuo.in。只替換 Token 而未安裝轉接外掛，無法更改官方外掛的 Bitly API 目的地。