開發者 API

用 REST API 程式化建立／管理短連結（server-to-server）。到 儀表板 → 開發者 API 產生金鑰。每月免費 1,000 次呼叫。

驗證

每個請求帶 Authorization: Bearer lk_live_…。回應標頭含 X-RateLimit-Remaining；額度用完回 429。

建立短連結

POST /api/v1/links

curl -X POST https://link.luvai.net/api/v1/links \
  -H "Authorization: Bearer lk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "target_url": "https://example.com.tw/sale",
    "slug": "summer",
    "title": "Summer sale",
    "escape_inapp": true,
    "utm": { "source": "ig", "medium": "bio" }
  }'

# 201 -> { "ok": true, "id": 42, "slug": "summer",
#          "short_url": "https://link.luvai.net/summer" }

欄位：target_url（必填）、slug（可留白＝隨機）、title、mode（simple｜ab｜device｜geo）、variants、redirect_type（301｜302）、og{title,description,image}、pixel_fb／ga／gtm／tiktok／line、escape_inapp、expires_at（ISO 時間）、max_clicks（點擊上限、0＝不限）、utm、password。目的地會自動過釣魚／惡意網址掃描。

列出 / 查詢 / 刪除

curl https://link.luvai.net/api/v1/links?limit=50 \
  -H "Authorization: Bearer lk_live_YOUR_KEY"

curl https://link.luvai.net/api/v1/links/42 \
  -H "Authorization: Bearer lk_live_YOUR_KEY"

curl -X DELETE https://link.luvai.net/api/v1/links/42 \
  -H "Authorization: Bearer lk_live_YOUR_KEY"

錯誤碼

401 金鑰缺失／無效／已撤銷 · 403 超過連結上限 · 404 找不到（或非你的連結）· 409 短碼重複／保留字 · 429 本月額度用完 · 400 參數錯誤（含目的地未過安全掃描）。

Webhooks

在儀表板的 Webhooks 面板新增接收網址、選事件（click／link.created）。事件發生時我們會 POST JSON 到你的端點，並在 X-Lz-Signature 標頭放 HMAC-SHA256 簽章（值＝sha256=<hex>，用建立時給的 whsec_ 密鑰對整個 raw body 簽）。請用密鑰重算並比對來驗證來源。

POST https://your-endpoint/webhook
X-Lz-Event: click
X-Lz-Signature: sha256=<hex>

{
  "event": "click",
  "sent_at": "2026-06-21T08:00:00.000Z",
  "data": {
    "slug": "abc123", "suffix": "ig", "target": "https://...",
    "country": "TW", "device": "mobile", "os": "iOS", "referrer": "https://..."
  }
}

// verify (Node):
const h = crypto.createHmac("sha256", WHSEC).update(rawBody).digest("hex");
if (("sha256=" + h) !== req.headers["x-lz-signature"]) reject();

轉換追蹤（歸因）

把下面這段放到你的「成交／感謝頁」，訪客完成購買時就回報一筆轉換（可帶營收），數據頁就會顯示「點擊 → 轉換 → 營收」與轉換率。同一訪客 10 分鐘內只算一次。轉換報表為付費方案功能。

<!-- 像素版（最簡單，貼成交頁）value／currency／suffix 皆選填 -->
<!-- suffix=管道標籤（與點擊 /suffix 同），帶了就能看「哪個管道帶來成交」 -->
<img src="https://link.luvai.net/api/conv?slug=YOUR_SLUG&value=99&currency=TWD&suffix=ig"
     width="1" height="1" style="display:none" alt="">

<!-- 或 JS 版（動態帶入訂單金額） -->
fetch("https://link.luvai.net/api/conv", {
  method: "POST", headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ slug: "YOUR_SLUG", value: 99, currency: "TWD", suffix: "ig" })
});

← 回 儀表板

開發者 API｜連 link.luvai.net