Open API

API 使用文档

短阵通 ShortLink 开放接口让你在自己的系统里创建短链、查询短链与获取统计摘要。所有接口使用 Bearer Token 认证，密钥在「控制台 → API 密钥」中创建，一个账号最多 5 个。

1. 认证

所有请求在 Header 中携带密钥：

Authorization: Bearer sk_0123456789abcdef0123456789abcdef

安全提示：完整密钥仅在创建时展示一次，请立即复制保存；密钥泄露请到控制台删除后重新创建。密钥使用时会自动记录last_used_at。

2. 创建短链

POST /api/v1/links

curl -X POST https://s.yinzhantong.com/api/v1/links \
  -H "Authorization: Bearer sk_0123456789abcdef0123456789abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/long/article/123",
    "title": "产品文档",
    "custom_code": "doc-123",
    "expires_at": "2026-12-31T23:59",
    "max_clicks": 10000,
    "access_password": "visit888"
  }'

参数说明：

参数	类型	说明
url	string *	目标长链接（http/https）
title	string	标题，选填
custom_code	string	自定义短码，3-32 位字母/数字/_-，选填
expires_at	string	有效期，格式 2026-12-31T23:59，选填
max_clicks	number	有效点击上限（正整数），选填
access_password	string	访问密码，选填

返回示例：

HTTP/1.1 201 Created
{
  "code": "doc-123",
  "short_url": "https://s.yinzhantong.com/s/doc-123",
  "target": "https://example.com/long/article/123"
}

短链域名默认使用 https://s.yinzhantong.com；当请求携带 Origin 头（浏览器 / 应用内请求）时，short_url 会基于该 Origin 拼接。

3. 查询短链列表

GET /api/v1/links?page=1&page_size=20

curl "https://s.yinzhantong.com/api/v1/links?page=1&page_size=20" \
  -H "Authorization: Bearer sk_0123456789abcdef0123456789abcdef"

分页参数：page 默认 1，page_size 默认 20、最大 100。返回该密钥用户下的短链（访问量默认排除机器访问）。

{
  "items": [
    {
      "id": 12,
      "code": "doc-123",
      "title": "产品文档",
      "target": "https://example.com/long/article/123",
      "short_url": "https://s.yinzhantong.com/s/doc-123",
      "status": "active",
      "created_at": "2026-08-11 10:00:00",
      "expires_at": null,
      "max_clicks": 10000,
      "has_password": true,
      "expired": false,
      "visit_count": 128
    }
  ],
  "total": 1,
  "page": 1,
  "page_size": 20,
  "total_pages": 1
}

4. 获取统计摘要

GET /api/v1/links/[code]/stats

curl "https://s.yinzhantong.com/api/v1/links/doc-123/stats" \
  -H "Authorization: Bearer sk_0123456789abcdef0123456789abcdef"

返回统计摘要：总点击（排除机器访问）、UV、近 7 天趋势与设备分布。

{
  "code": "doc-123",
  "total_clicks": 128,
  "uv": 96,
  "bot_clicks": 31,
  "last_7_days": {
    "pv": 42,
    "uv": 30,
    "trend": [
      { "date": "2026-08-05", "pv": 3, "uv": 3 },
      { "date": "2026-08-06", "pv": 7, "uv": 6 }
    ]
  },
  "devices": [
    { "name": "mobile", "count": 26 },
    { "name": "desktop", "count": 14 }
  ]
}

5. 错误码

HTTP 状态	含义
400	参数错误：缺少 url、链接非法、有效期格式不正确等
401	无效的 API 密钥：未携带 Bearer、密钥不存在或已停用
404	资源不存在：短链不存在或不属于该密钥用户
409	短码冲突：custom_code 已被占用

6. 密钥管理

登录后在控制台 → API 密钥页面创建与管理密钥。列表只展示脱敏值（前 8 位 + ***），完整密钥仅创建时展示一次；删除密钥后对应请求立即返回 401。