短链接、安全与高级路由接口

短链接资源位于 /api/v1/short_links。所有接口需要认证和工作区上下文；创建、修改、删除需要 owner、admin 或 member。

核心接口

方法	路径	说明
POST	/api/v1/short_links	创建短链
GET	/api/v1/short_links	分页筛选
GET	/api/v1/short_links/:id	详情
PUT	/api/v1/short_links/:id	更新
PUT	/api/v1/short_links/:id/status	启停
DELETE	/api/v1/short_links/:id	删除；应先禁用
GET	/api/v1/short_links/:id/statistics?days=7	1–365 天简要统计
POST	/api/v1/short_links/batch	最多 100 个 URL 批量创建
POST	/api/v1/short_links/batch/status	最多 100 条批量启停
POST	/api/v1/short_links/batch/delete	最多 100 条批量删除

创建示例

curl -sS https://s.example.com/api/v1/short_links \
  -H 'Authorization: Bearer <token>' \
  -H 'X-Workspace-Id: 1' \
  -H 'Content-Type: application/json' \
  -d '{
    "original_url": "https://example.com/landing",
    "domain": "s.example.com",
    "custom_code": "summer-26",
    "title": "夏季活动",
    "fallback_url": "https://example.com/fallback",
    "redirect_code": 302,
    "campaign_id": 12,
    "tag_ids": [3, 8],
    "utm_source": "newsletter",
    "utm_medium": "email",
    "find_if_exists": true
  }'

original_url 必须是完整 URL。redirect_code 只接受 301、302、307、308。find_if_exists 仅在域名重复策略为 by_request 且没有 custom_code 时生效；命中既有短链时响应 is_existing=true。

列表支持 page、page_size、domain、keyword、campaign_id、tag_id、created_by、security_status 和 routing_status。

链接安全

方法	路径	说明
GET	/api/v1/short_links/:id/security	读取策略
PUT	/api/v1/short_links/:id/security	设置密码、时间窗、次数、IP/Bot 和举报开关
POST	/api/v1/short_links/:id/security/rescan	重新按 URL 规则扫描
GET/POST	/api/v1/security/url_rules	查询/创建 URL 规则
PUT/DELETE	/api/v1/security/url_rules/:id	修改/删除规则
GET	/api/v1/security/events	安全事件
GET	/api/v1/abuse_reports	滥用举报列表
PUT	/api/v1/abuse_reports/:id	处理举报，可同时禁用短链

安全策略示例：

{
  "password_enabled": true,
  "password": "一次性传入的新密码",
  "access_window_start": "2026-08-01T00:00:00+08:00",
  "access_window_end": "2026-08-31T23:59:59+08:00",
  "max_clicks": 10000,
  "ip_policy": "blocklist",
  "ip_rules": [{"cidr": "192.0.2.0/24", "description": "示例保留地址"}],
  "bot_policy": "block_known_bots",
  "report_enabled": true
}

ip_policy 为 off、allowlist 或 blocklist；bot_policy 为 record_only、allow 或 block_known_bots。

高级路由

方法	路径	说明
GET/POST	/api/v1/short_links/:id/routes	列表/创建
PUT/DELETE	/api/v1/short_links/:id/routes/:route_id	修改/删除
POST	/api/v1/short_links/:id/routes/reorder	批量设置优先级
POST	/api/v1/short_links/:id/routes/test	用模拟客户端属性测试命中结果

路由中的条件组之间按 OR 处理，组内条件按 AND 处理；服务按优先级判断，未命中时使用短链 fallback_url 或原始 URL。创建示例：

{
  "name": "移动端",
  "priority": 100,
  "target_url": "https://m.example.com/landing",
  "is_active": true,
  "condition_groups": [{
    "conditions": [{
      "condition_type": "device_type",
      "operator": "eq",
      "condition_value": "mobile"
    }]
  }]
}

实际可用条件类型和操作符以管理端当前选择项为准；上线前调用 routes/test 验证典型 IP、User-Agent、语言、Referer 与 Query。

相关章节：域名接口、统计与归因。