#概述
LinkFlow 智链 API 是一套 RESTful 风格的 HTTP 接口，面向企业版用户提供卡片管理、数据查询、短链生成等能力的程序化访问。通过 API，您可以将 LinkFlow 集成到您的 CRM、ERP 或自动化运营系统中。
Base URL
ENVIRONMENT
# Production environment https://api.linkflow.cn/v1 # Sandbox environment (for testing) https://sandbox-api.linkflow.cn/v1
当前版本
当前 API 版本为 v1，所有接口路径需包含版本前缀。我们承诺向后兼容，破坏性变更将使用新的版本号。
💡 提示：API 仅对企业版客户开放。如需开通，请前往 价格方案 升级套餐或在控制台「API 设置」中申请。
请求约定
- 请求与响应均使用
UTF-8编码 - 请求体格式为
application/json，需在 Header 中声明Content-Type - 所有时间字段使用 ISO 8601 格式：
2025-07-25T10:30:00Z - 金额字段单位为人民币分，例如
9900表示 ¥99.00
#认证方式
LinkFlow API 使用 API Key 进行身份认证。每个企业账号可在控制台「API 设置」中创建多个 API Key，分别对应不同的应用或环境。
获取 API Key
- 登录控制台，进入「账户中心 → API 设置」
- 点击「创建 API Key」，填写应用名称和描述
- 系统将生成一对
Access Key（公开标识）和Secret Key（私密密钥） - 请妥善保存 Secret Key，创建后仅展示一次，丢失只能重新生成
请求头示例
所有 API 请求需在 HTTP Header 中携带以下字段：
HTTP HEADERS
Authorization: Bearer your_access_key:your_signature Content-Type: application/json X-LF-Timestamp: 1721900000 X-LF-Nonce: a1b2c3d4e5f6
签名算法
签名用于验证请求的完整性与身份。生成步骤如下：
SIGNATURE ALGORITHM
# 1. 拼接签名字符串 string_to_sign = method + "\n" + path + "\n" + sorted_query_string + "\n" + timestamp + "\n" + nonce + "\n" + body_md5 # 2. 使用 Secret Key 进行 HMAC-SHA256 signature = hmac_sha256(secret_key, string_to_sign) # 3. Base64 编码 signature = base64_encode(signature) # 4. 拼接 Authorization Header authorization = "Bearer " + access_key + ":" + signature
⚠️ 注意：时间戳与服务器时间相差超过 5 分钟的请求将被拒绝。请确保服务器时间同步（NTP）。
#创建卡片
创建一个新的跳转卡片，返回卡片 ID 和卡片代码。
POST
/v1/cards
创建跳转卡片，支持抖音、快手、小红书、视频号、B 站等全平台。
请求参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| platform | string | 必填 | 平台标识，可选值：douyin / kuaishou / xiaohongshu / videohao / bilibili |
| type | string | 必填 | 卡片类型：jump（跳转卡片）/ auto_reply（自动回复）/ short_link（短链接） |
| title | string | 必填 | 卡片标题，1-30 个字符 |
| description | string | 可选 | 卡片描述，1-100 个字符 |
| target_url | string | 必填 | 目标跳转链接，必须为合法的 http/https URL |
| template_id | string | 可选 | 卡片模板 ID，不传则使用默认模板 |
| expire_at | string | 可选 | 过期时间，ISO 8601 格式。不传则长期有效 |
请求示例
cURL
curl -X POST https://api.linkflow.cn/v1/cards \
-H "Authorization: Bearer ak_xxxx:signature" \
-H "Content-Type: application/json" \
-H "X-LF-Timestamp: 1721900000" \
-H "X-LF-Nonce: a1b2c3d4e5f6" \
-d '{
"platform": "douyin",
"type": "jump",
"title": "添加微信领优惠券",
"description": "点击卡片立即添加客服微信领取专属优惠券",
"target_url": "https://work.weixin.qq.com/kfid/xxx",
"expire_at": "2025-12-31T23:59:59Z"
}'
响应示例
JSON · 200 OK
{
"code": 0,
"message": "success",
"data": {
"card_id": "card_8a7b6c5d4e3f",
"platform": "douyin",
"type": "jump",
"title": "添加微信领优惠券",
"description": "点击卡片立即添加客服微信领取专属优惠券",
"target_url": "https://work.weixin.qq.com/kfid/xxx",
"card_code": "v2_douyin_xxxxxxxxxxxxx",
"status": "active",
"expire_at": "2025-12-31T23:59:59Z",
"created_at": "2025-07-25T10:30:00Z"
}
}
#查询数据
查询指定时间范围内卡片的曝光、点击、跳转、转化等统计数据。
GET
/v1/cards/:card_id/stats
查询单张卡片的统计数据，支持按天/小时聚合。
请求参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| card_id | string | 必填 | 路径参数，卡片 ID |
| start_date | string | 必填 | 开始日期，格式 YYYY-MM-DD |
| end_date | string | 必填 | 结束日期，格式 YYYY-MM-DD，跨度不超过 90 天 |
| granularity | string | 可选 | 聚合粒度：day（默认）/ hour |
请求示例
cURL
curl -X GET "https://api.linkflow.cn/v1/cards/card_8a7b6c5d4e3f/stats?start_date=2025-07-01&end_date=2025-07-25&granularity=day" \ -H "Authorization: Bearer ak_xxxx:signature" \ -H "X-LF-Timestamp: 1721900000" \ -H "X-LF-Nonce: a1b2c3d4e5f6"
响应示例
JSON · 200 OK
{
"code": 0,
"message": "success",
"data": {
"card_id": "card_8a7b6c5d4e3f",
"summary": {
"impressions": 128450,
"clicks": 38240,
"jumps": 31850,
"conversions": 4520,
"ctr": 0.2977,
"cvr": 0.1419
},
"timeseries": [
{
"date": "2025-07-01",
"impressions": 5240,
"clicks": 1560,
"jumps": 1320,
"conversions": 180
},
{
"date": "2025-07-02",
"impressions": 5680,
"clicks": 1680,
"jumps": 1410,
"conversions": 205
}
]
}
}
#管理短链
更新已有短链的目标 URL、状态或过期时间。
PUT
/v1/short-links/:link_id
更新短链属性。支持部分字段更新，未传字段保持原值。
请求参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| link_id | string | 必填 | 路径参数，短链 ID |
| target_url | string | 可选 | 新的目标跳转链接 |
| status | string | 可选 | 状态：active / paused / expired |
| expire_at | string | 可选 | 新的过期时间，ISO 8601 格式 |
请求示例
cURL
curl -X PUT https://api.linkflow.cn/v1/short-links/sl_a1b2c3d4 \
-H "Authorization: Bearer ak_xxxx:signature" \
-H "Content-Type: application/json" \
-H "X-LF-Timestamp: 1721900000" \
-H "X-LF-Nonce: a1b2c3d4e5f6" \
-d '{
"target_url": "https://work.weixin.qq.com/kfid/new_url",
"status": "active"
}'
响应示例
JSON · 200 OK
{
"code": 0,
"message": "success",
"data": {
"link_id": "sl_a1b2c3d4",
"short_url": "https://lf.cn/x9K2pQ",
"target_url": "https://work.weixin.qq.com/kfid/new_url",
"status": "active",
"updated_at": "2025-07-25T11:00:00Z"
}
}
#卡片列表
分页查询当前账号下的所有卡片。
GET
/v1/cards
支持按平台、状态、创建时间筛选，分页返回。
请求参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| platform | string | 可选 | 按平台筛选 |
| status | string | 可选 | 按状态筛选：active / paused / expired |
| page | integer | 可选 | 页码，从 1 开始，默认 1 |
| page_size | integer | 可选 | 每页数量，1-100，默认 20 |
请求示例
cURL
curl -X GET "https://api.linkflow.cn/v1/cards?platform=douyin&status=active&page=1&page_size=20" \ -H "Authorization: Bearer ak_xxxx:signature" \ -H "X-LF-Timestamp: 1721900000" \ -H "X-LF-Nonce: a1b2c3d4e5f6"
#删除卡片
删除指定的卡片。删除后不可恢复，已生成的卡片代码将立即失效。
DELETE
/v1/cards/:card_id
软删除，30 天内可在控制台恢复，30 天后彻底清除。
请求示例
cURL
curl -X DELETE https://api.linkflow.cn/v1/cards/card_8a7b6c5d4e3f \ -H "Authorization: Bearer ak_xxxx:signature" \ -H "X-LF-Timestamp: 1721900000" \ -H "X-LF-Nonce: a1b2c3d4e5f6"
响应示例
JSON · 200 OK
{
"code": 0,
"message": "success",
"data": {
"card_id": "card_8a7b6c5d4e3f",
"deleted_at": "2025-07-25T12:00:00Z",
"recoverable_until": "2025-08-24T12:00:00Z"
}
}
⚠️ 危险操作：删除卡片将立即停止该卡片的所有跳转服务。如仅需暂停，请使用
PUT /v1/cards/:card_id 将 status 设为 paused。
#频率限制
为保障系统稳定，API 请求有频率限制。超限时返回 429 状态码。
| 接口类型 | 限制 | 说明 |
|---|---|---|
| 查询类（GET） | 100 次 / 分钟 | 统计、列表等只读接口 |
| 写入类（POST/PUT/DELETE） | 30 次 / 分钟 | 创建、更新、删除等写操作 |
| 单 IP 总请求 | 600 次 / 分钟 | 所有接口合并计算 |
响应 Header 中会返回剩余可用次数：
HTTP HEADERS
X-LF-RateLimit-Limit: 100 X-LF-RateLimit-Remaining: 87 X-LF-RateLimit-Reset: 1721900060
#错误码
所有 API 响应均包含 code 字段。0 表示成功，其他值表示失败。HTTP 状态码与业务错误码可能不完全一致，请以业务码为准。
| code | HTTP | message | 说明 |
|---|---|---|---|
| 0 | 200 | success | 请求成功 |
| 40001 | 401 | invalid_api_key | API Key 无效或已被禁用 |
| 40002 | 401 | invalid_signature | 签名验证失败，请检查签名算法 |
| 40003 | 401 | expired_timestamp | 时间戳过期，与服务器时间相差超过 5 分钟 |
| 40004 | 403 | permission_denied | 无权限访问该资源，请检查套餐或资源归属 |
| 40401 | 404 | card_not_found | 卡片不存在或已彻底删除 |
| 40901 | 409 | card_exists | 同标题卡片已存在，请更换标题 |
| 42201 | 422 | validation_failed | 参数校验失败，详见 errors 字段 |
| 42901 | 429 | rate_limit_exceeded | 请求频率超限，请稍后重试 |
| 45101 | 451 | quota_exceeded | 套餐跳转额度已用尽，请升级套餐或购买加油包 |
| 50001 | 500 | internal_error | 服务器内部错误，请联系客服 |
| 50301 | 503 | service_unavailable | 服务暂时不可用，请稍后重试 |
错误响应示例
JSON · Error
{
"code": 42201,
"message": "validation_failed",
"errors": [
{
"field": "target_url",
"message": "target_url must be a valid http(s) URL"
},
{
"field": "title",
"message": "title length must be between 1 and 30"
}
],
"request_id": "req_8a7b6c5d4e3f"
}
💡 提示：每次请求都会返回唯一的
request_id。遇到问题时请保留该 ID，联系客服可帮助我们快速定位问题。
需要更多帮助？ 如对接过程中遇到任何问题，欢迎联系技术支持：微信
LinkFlow_Help，或前往 帮助中心 查看更多文档。