API 文档
通过 Quik.mn REST API 以编程方式创建、管理链接并获取统计数据。
全部服务
Quik.mn 平台的全部产品——支持 REST API 与网页端。
基础地址
所有接口均以下列基础地址开头：
身份验证
每次请求都需在 Authorization 请求头中带上控制台生成的 API 密钥：
切勿把密钥透露给任何人。一旦泄露，请在控制台重新生成。
接口列表
参数
POST /api/v1/links — 请求体字段：
GET /api/v1/links — 查询参数：
错误格式
每个错误都会返回 HTTP 状态码（401、404、409、422、429）以及统一的 JSON 结构：
{ "error": "alias_taken", "message": "该别名已被保留或已被使用。" }
常见错误码： unauthorized (401), not_found (404), alias_taken (409), invalid_url / invalid_alias / invalid_expires_at / invalid_starts_at (422), rate_limited (429).
调用限制
请求示例
创建短链接的 cURL 示例：
curl -X POST https://quik.mn/api/v1/links \
-H "Authorization: Bearer qk_live_xxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/很长的/路径",
"alias": "promo",
"title": "春季活动",
"expires_at": "2026-12-31 23:59:59"
}'
Webhook
在控制台的回调板块注册接口地址后，所选事件一旦发生，我们就会向你的网址发送 JSON POST 请求。返回 200~299 状态码即视为成功；否则将按 1 分钟 → 10 分钟的间隔最多重试 3 次。连续失败 10 次后，该回调会自动停用。
每次投递的数据结构（示例）：
{
"event": "link.created",
"created_at": "2026-07-18T09:30:00+00:00",
"data": {
"link": {
"id": 42, "slug": "promo", "short_url": "https://quik.mn/promo",
"long_url": "https://example.com/很长的/路径", "title": "春季活动",
"clicks": 0, "active": true, "state": "ok",
"created_at": "2026-07-18 09:30:00", "expires_at": "2027-07-18 09:30:00"
}
}
}
校验签名
每次投递都会带上以下请求头： X-Quik-Event (事件名称), X-Quik-Signature — sha256=HMAC_SHA256(body, secret). 密钥仅在创建回调时显示一次。校验签名时务必基于原始请求体，并使用恒定时间比较：
<?php
// PHP — 对原始请求体(raw body)验证签名
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_QUIK_SIGNATURE'] ?? '';
$expected = 'sha256=' . hash_hmac('sha256', $payload, $secret);
if (!hash_equals($expected, $signature)) {
http_response_code(401);
exit('invalid signature');
}
$event = json_decode($payload, true);
// $event['event'], $event['data'] ...
http_response_code(200);
// Node.js (Express) — 对原始请求体(raw body)验证签名
const crypto = require('crypto');
app.post('/quik-webhook', express.raw({ type: 'application/json' }), (req, res) => {
const signature = req.get('X-Quik-Signature') || '';
const expected = 'sha256=' +
crypto.createHmac('sha256', secret).update(req.body).digest('hex');
const a = Buffer.from(expected), b = Buffer.from(signature);
if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
return res.status(401).send('invalid signature');
}
const event = JSON.parse(req.body); // event.event, event.data ...
res.sendStatus(200);
});
限制：Free 套餐 1 个、Pro 3 个、Business 10 个回调。接口地址必须是可公网访问的 http/https 地址（内网地址会被拦截）。
