RESTful API v2.5

开发者友好的
API 接口

完整的 RESTful API，支持短链创建、访问统计、积分签到、AI 对话生成、批量生成、速率限制与 Webhook 事件推送（均已上线）。简洁的请求格式，结构化的响应，丰富的代码示例，助你快速集成。

🚀 查看接口 代码示例
认证

API 认证方式

两种认证方式，灵活选择

🔑 API Key 认证

在请求头中携带 Authorization: Bearer YOUR_API_KEY，适合服务端集成与自动化脚本。

Authorization: Bearer sk_live_xxxxxxxxxxxx
👤 登录态认证

通过用户登录接口获取会话 Cookie，后续请求自动携带。适合前端应用与用户中心相关接口。

POST /api.php?action=login
Cookie: session=xxx (自动携带)
接口列表

核心接口

覆盖短链全生命周期管理、Webhook 事件推送与企业级协作接口

POST /api.php?action=create 🔒 API Key 创建短链接
请求参数
参数名 类型 必填 说明
url string 必填 原始长链接 URL，需包含协议（http/https）
custom_code string 可选 自定义短码，3-16 位字母数字，不填则自动生成
password string 可选 访问密码，为空则不设密码
expire_hours int 可选 过期时间（小时），为空则永久有效
template_id int 可选 跳转模板 ID，默认使用系统默认模板
folder_id int 可选 所属文件夹 ID
响应示例
{
  "code": 0,
  "message": "创建成功",
  "data": {
    "short_url": "https://duan.hshen.eu.cc/abc123",
    "code": "abc123",
    "created_at": "2024-01-15 10:30:00"
  }
}
GET /api.php?action=get_stats 🔒 API Key 获取链接统计
请求参数
参数名 类型 必填 说明
code string 必填 短码
响应示例
{
  "code": 0,
  "data": {
    "total_visits": 1234,
    "unique_visitors": 567,
    "devices": {"pc": 600, "mobile": 500, "tablet": 134},
    "browsers": {"Chrome": 500, "Safari": 300, "Firefox": 200},
    "daily_stats": [
      {"date": "2024-01-14", "visits": 100}
    ]
  }
}
POST /api.php?action=batch_create 🔒 API Key 批量创建短链接
请求参数
参数名 类型 必填 说明
urls array 必填 URL 数组，每项可包含 url/custom_code/password 等字段
common_settings object 可选 通用设置（密码、有效期、模板等）
响应示例
{
  "code": 0,
  "message": "批量创建成功",
  "data": {
    "total": 10,
    "success": 9,
    "failed": 1,
    "results": [...]
  }
}
GET /api.php?action=list 🔒 API Key 获取链接列表
请求参数
参数名 类型 必填 说明
page int 可选 页码，默认 1
limit int 可选 每页数量，默认 20，最大 100
folder_id int 可选 按文件夹筛选
status string 可选 状态筛选：enabled/disabled/expired
响应示例
{
  "code": 0,
  "data": {
    "total": 156,
    "page": 1,
    "limit": 20,
    "links": [...]
  }
}
POST /api.php?action=update 🔒 API Key 更新链接信息
请求参数
参数名 类型 必填 说明
code string 必填 要更新的短码
password string 可选 新密码（为空则移除密码）
expire_hours int 可选 新的过期时间
status string 可选 enabled/disabled
响应示例
{
  "code": 0,
  "message": "更新成功"
}
POST /api.php?action=delete 🔒 API Key 删除短链接
请求参数
参数名 类型 必填 说明
code string 必填 要删除的短码
响应示例
{
  "code": 0,
  "message": "删除成功"
}
POST /api.php?action=points_signin 🔒 登录态 / API Key 积分签到
请求参数
参数名 类型 必填 说明
无参数
响应示例
{
  "code": 0,
  "message": "签到成功",
  "data": {
    "points_earned": 10,
    "total_points": 150,
    "consecutive_days": 5
  }
}
POST /api.php?action=ai_chat 🔒 API Key AI 对话生成短链
请求参数
参数名 类型 必填 说明
message string 必填 自然语言指令，如"生成 example.com 的短链"
session_id string 可选 会话 ID 以保持上下文
响应示例
{
  "code": 0,
  "message": "AI 处理完成",
  "data": {
    "reply": "已为您生成短链",
    "short_url": "https://duan.hshen.eu.cc/abc123",
    "action": "create"
  }
}
GET /api.php?action=team_list 🔒 登录态 团队列表
请求参数
参数名 类型 必填 说明
无参数
响应示例
{
  "code": 0,
  "data": {
    "teams": [
      {"id": 1, "name": "营销组", "role": "owner", "member_count": 4}
    ]
  }
}
POST /api.php?action=team_create 🔒 登录态 创建团队
请求参数
参数名 类型 必填 说明
name string 必填 团队名称
slug string 可选 团队标识（URL 友好）
description string 可选 团队描述
响应示例
{"code": 0, "message": "创建成功", "data": {"team_id": 1}}
POST /api.php?action=team_invite 🔒 登录态 生成团队邀请码
请求参数
参数名 类型 必填 说明
team_id int 必填 团队 ID
role string 可选 邀请角色：admin/member，默认 member
max_uses int 可选 最大使用次数，默认 1
expires_hours int 可选 邀请码有效期（小时）
响应示例
{"code": 0, "message": "ok", "data": {"code": "ABC123XYZ"}}
POST /api.php?action=team_join 🔒 登录态 通过邀请码加入团队
请求参数
参数名 类型 必填 说明
code string 必填 邀请码
响应示例
{"code": 0, "message": "加入成功", "data": {"team_id": 1}}
GET /api.php?action=webhook_list 🔒 登录态 Webhook 配置列表
请求参数
参数名 类型 必填 说明
team_id int 可选 团队 ID，不传返回个人 Webhook
响应示例
{
  "code": 0,
  "data": {
    "webhooks": [
      {"id": 1, "url": "https://...", "events": "link.created,link.clicked", "status": 1, "total_sent": 12}
    ]
  }
}
POST /api.php?action=webhook_create 🔒 登录态 创建 Webhook
请求参数
参数名 类型 必填 说明
url string 必填 推送目标 URL
events string 可选 订阅事件，逗号分隔：link.created/link.updated/link.clicked/link.expired
secret string 可选 HMAC-SHA256 签名密钥
team_id int 可选 归属团队 ID
retry_count int 可选 失败重试次数，默认 3
响应示例
{"code": 0, "message": "创建成功", "data": {"webhook_id": 1}}
GET /api.php?action=dashboard_stats 🔒 登录态 数据看板统计
请求参数
参数名 类型 必填 说明
mode string 可选 personal/team，默认 personal
team_id int 可选 查看团队数据时必填
range int 可选 时间范围天数：7/30/90，默认 7
响应示例
{
  "code": 0,
  "data": {
    "total_links": 120,
    "total_clicks": 3456,
    "daily": [{"date": "2024-01-15", "visits": 100}],
    "top_links": [...]
  }
}
快速开始

多语言代码示例

复制即用，5 分钟完成集成

命令行
前端
服务端
脚本
# 创建短链接
curl -X POST 'https://duan.hshen.eu.cc/api.php?action=create' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'url=https://example.com&custom_code=mylink'

# 获取统计
curl 'https://duan.hshen.eu.cc/api.php?action=get_stats&code=mylink' \
  -H 'Authorization: Bearer YOUR_API_KEY'
// 创建短链接
const response = await fetch('https://duan.hshen.eu.cc/api.php?action=create', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/x-www-form-urlencoded'
  },
  body: new URLSearchParams({
    url: 'https://example.com',
    custom_code: 'mylink'
  })
});
const data = await response.json();
console.log(data.short_url);
<?php
$ch = curl_init('https://duan.hshen.eu.cc/api.php?action=create');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query([
  'url' => 'https://example.com',
  'custom_code' => 'mylink'
]));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'Authorization: Bearer YOUR_API_KEY'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
$data = json_decode($response, true);
echo $data['data']['short_url'];
import requests

# 创建短链接
response = requests.post(
    'https://duan.hshen.eu.cc/api.php?action=create',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    data={
        'url': 'https://example.com',
        'custom_code': 'mylink'
    }
)
data = response.json()
print(data['data']['short_url'])
错误处理

状态码参考

统一格式的错误响应，便于调试与处理

0
成功
400
请求参数错误
401
未授权（API Key 无效或缺失）
403
权限不足
404
短码不存在
409
短码已被占用
429
请求过于频繁
500
服务器内部错误
💡 错误响应格式
{ "code": 400, "message": "参数错误：url 不能为空", "data": null }
性能

速率限制 ✅ 已上线

速率限制与套餐配额体系已上线，按套餐与用户身份区分调用配额

100
次 / 小时
免费版（已生效）
1K
次 / 小时
基础版（已生效）
5K
次 / 小时
专业版（已生效）
10K+
次 / 小时
企业版（已生效）
响应头已包含 X-RateLimit-Remaining 与 X-RateLimit-Reset 便于客户端限流控制
事件通知

Webhook 回调 ✅ 已上线

实时事件推送已上线，无需轮询即可获得链接动态（创建/点击/停用/过期/归档）

link.created
新短链创建时触发
{"code": "abc123", "url": "...", "created_at": "..."}
link.clicked
短链被访问时触发
{"code": "abc123", "ip": "...", "device": "...", "timestamp": "..."}
link.expired
短链过期时触发
{"code": "abc123", "expire_at": "..."}
points.earned
积分变动时触发
{"user_id": 123, "points": 10, "type": "signin"}
⚡ Webhook 配置（已上线）

现可在 用户中心 > Webhook 中配置回调 URL，选择需要订阅的事件类型，并支持自定义签名密钥验证请求来源；可在 Webhook 管理页查看每次投递的状态码、耗时与响应内容。

// Webhook 签名验证（HMAC-SHA256） $signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE']; $expected = hash_hmac('sha256', $payload, $webhook_secret); if (hash_equals($expected, $signature)) { // 处理事件 }

开始集成 API

注册账号，获取 API Key，5 分钟完成第一个接口调用

🚀 注册获取 API Key 在线体验