API 与系统集成

木雷短网址的业务 API 使用 /api/v1 前缀。除登录、安装、健康检查和 /api/v1/public/* 外，接口都需要认证并解析工作区上下文。

基础约定

Base URL: https://s.example.com
Content-Type: application/json

成功响应：

{
  "code": 0,
  "message": "操作成功",
  "data": {}
}

失败响应通常使用对应 HTTP 状态码：

{
  "code": 400,
  "message": "请求参数错误"
}

请求上下文

受保护接口支持登录 JWT、API Bearer Token 或 HMAC 请求签名，详见认证与工作区。除认证外，建议显式携带：

X-Workspace-Id: 1

未提供时，服务会选择当前用户第一个可用工作区；集成程序不应依赖这个顺序。

资源导航

• 认证、签名与工作区
• 短链接、安全与高级路由
• 域名接口
• A/B 测试接口
• 用户、Token 与系统管理
• 统计、Campaign 与 Tag
• 公开接口与短链访问

集成建议

• 服务端集成优先使用 signature Token；简单可信内网任务可使用 Bearer Token。
• 创建 Token 时立即保存明文凭据；列表接口不会再次返回完整 Token 或 App Secret。
• 将工作区 ID 固定在集成配置中，每个请求都发送 X-Workspace-Id。
• 为创建、反馈等操作设计业务幂等键；A/B 转化反馈原生使用 event_id 去重。
• 仅对 HTTP 429、502、503 和明确的网络失败进行有界重试，不要无条件重试参数错误。