API 文档

基础信息

Base URL：/api/v1

响应统一为 { ok: true, data } 或 { ok: false, error: { code, message } }。

接口列表

创建追踪链接

POST /api/v1/links
Content-Type: application/json

{
  "url":    "https://example.com/activity",   // 必填，http/https，≤2048 字符
  "email":  "you@example.com",                // 用于事后查询，建议填写
  "webrtc": false                             // 可选，true 才走过渡页探测真实出口
}

{
  "ok": true,
  "data": {
    "token": "Kx7pQz9LmN2vRt4B",
    "email": "you@example.com",
    "link": "https://你的域名/s/Kx7pQz9LmN2vRt4B",
    "redirect_url": "https://example.com/activity",
    "webrtc": false,
    "created_at": "2026-10-29T09:31:42.000Z",
    "expires_at": "2026-10-29T10:31:42.000Z",
    "expires_in": 3600
  }
}

Token 由服务端随机生成，无需也不建议自定义。

webrtc: true 会让该链接先加载一个过渡页再跳转，用于探测访客的真实出口 IP； 有概率导致链接访问后加载不出来，默认关闭。

按邮箱查询

GET /api/v1/records?email=you@example.com

{
  "ok": true,
  "data": {
    "email": "you@example.com",
    "count": 2,
    "visited": 1,
    "pending": 1,
    "records": [
      {
        "token": "Kx7pQz9LmN2vRt4B",
        "ip": "1.2.3.4",
        "country": "中国",
        "region": "浙江",
        "city": "嘉兴",
        "time": "2026-10-29 17:31:42",
        "redirect_url": "https://example.com/activity",
        "webrtc": true,
        "webrtc_ip": "5.6.7.8",
        "webrtc_local": [],
        "webrtc_probed": true,
        "proxy_leak": true,
        "status": "visited"
      },
      {
        "token": "Ab8xYz2Mn4Pq",
        "ip": "",
        "status": "pending",
        "redirect_url": "https://example.com/other"
      }
    ]
  }
}

记录保留 7 天，查询不会删除数据；未访问的链接 1 小时后自动失效。

webrtc_ip 是访客浏览器通过 STUN 看到的公网出口；与 ip 不一致时 proxy_leak 为 true，说明对方只代理了网页、UDP 漏了真实出口。

在线调试

调用示例

JavaScript

const API = "https://你的域名/api/v1";
const headers = { "Content-Type": "application/json" };

const created = await fetch(`${API}/links`, {
  method: "POST",
  headers,
  body: JSON.stringify({ url: "https://example.com/activity", email: "you@example.com" }),
}).then((r) => r.json());

console.log(created.data.link);

const result = await fetch(`${API}/records?email=you@example.com`, { headers }).then((r) => r.json());
console.log(result.data.records);

curl

BASE=https://你的域名/api/v1

curl -X POST "$BASE/links" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/activity","email":"you@example.com"}'

curl "$BASE/records?email=you@example.com"

若服务端设置了 API_KEY，请加上请求头 X-API-Key: 你的密钥。