快速开始

跟着以下步骤，5 分钟内完成第一次 Open API 调用。

第一步 — 创建 API Key

1. 登录控制台，在左侧导航点击开发者
2. 点击创建 API Key
3. 为 Key 起个名字（如 CI Bot 或 营销自动化）
4. 选择所需权限范围：
   • links:read — 列表查询、详情、统计
   • links:write — 创建和更新链接
   • links:delete — 禁用和删除链接
5. 点击创建

重要提示：完整的 API Key 仅在创建时显示一次，请立即复制并安全保存。不要将密钥提交到代码仓库或分享给他人。

Key 格式如下：

sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

第二步 — 发起第一个请求

创建短链接

curl -X POST https://open.utm.bar/v1/links \
  -H "Authorization: Bearer sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "original_url": "https://example.com/blog/launch-2026",
    "title": "产品发布文章",
    "utm_source": "newsletter",
    "utm_medium": "email",
    "utm_campaign": "launch-2026"
  }'

响应：

{
  "data": {
    "id": "01960000-0000-0000-0000-000000000000",
    "code": "xK3mP9",
    "short_url": "https://utm.bar/xK3mP9",
    "original_url": "https://example.com/blog/launch-2026",
    "title": "产品发布文章",
    "is_active": true,
    "click_count": 0,
    "expires_at": null,
    "utm_source": "newsletter",
    "utm_medium": "email",
    "utm_campaign": "launch-2026",
    "created_at": "2026-05-25T00:00:00Z"
  }
}

列出链接

curl https://open.utm.bar/v1/links \
  -H "Authorization: Bearer sk_live_xxxx"

第三步 — 正确传递认证信息

每次请求使用以下方式之一：

Authorization: Bearer sk_live_xxxx

X-API-Key: sk_live_xxxx

Key 缺失或无效时返回 401 Unauthorized。
Key 缺少所需权限时返回 403 Forbidden。

第四步 — 处理错误

API 始终返回统一的错误结构：

{
  "error": "invalid_request",
  "message": "original_url is required",
  "request_id": "req_abc123"
}

常见状态码：

下一步

• 阅读完整的 API 参考 了解所有端点
• 监控响应头中的 X-RateLimit-Remaining 避免触发限流
• 使用 custom_code 为活动创建品牌化短链接