接入指南

1. 获取凭证

注册后在「用户中心」可获得 Token（公开，随请求发送）与 Secret（私密，仅用于本地计算签名，切勿外传）。

2. 签名规则

待签名字符串（\n 为换行）：

METHOD\nPATH\ntimestamp\nnonce\nk1=v1&k2=v2

METHOD：大写请求方法，如 GET / POST
PATH：接口路径，如 /api/v1/demo（不含域名与 query）
timestamp：秒级时间戳，与服务端相差不得超过 300 秒
nonce：每次请求唯一的随机串，600 秒内不可重复
参数：去掉 sign 后按 key 字典序排序，URL 编码后用 & 连接
签名值：HMAC-SHA256(待签串, Secret) 的小写十六进制

3. 请求头

Header	说明
X-Api-Token	你的 API Token
X-Api-Timestamp	秒级时间戳
X-Api-Nonce	随机串
X-Api-Signature	签名值

提示：也支持把 token / timestamp / nonce / sign 作为 URL 参数传递，方便在浏览器直接调试。

4. 示例代码

cURL

curl -X GET 'http://pan.u5zpgb.cn/api/v1/demo?keyword=test' \
  -H 'X-Api-Token: ym_your_token_here' \
  -H 'X-Api-Timestamp: 1789197761' \
  -H 'X-Api-Nonce: a1b2c3d4e5f6' \
  -H 'X-Api-Signature: 6f24ecaef16add6abaadc6307f5e24328292a4dc32cf24b98010e616d797f4d0'

PHP

$token  = 'ym_your_token_here';
$secret = 'your_secret_here';
$path   = '/api/v1/demo';
$params = ['keyword' => 'test'];

$ts    = time();
$nonce = bin2hex(random_bytes(8));
ksort($params);
$canonical = http_build_query($params);
$raw = "GET\n{$path}\n{$ts}\n{$nonce}\n{$canonical}";
$sign = hash_hmac('sha256', $raw, $secret);

$ch = curl_init('https://your-domain.com' . $path . '?' . $canonical);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-Api-Token: ' . $token,
        'X-Api-Timestamp: ' . $ts,
        'X-Api-Nonce: ' . $nonce,
        'X-Api-Signature: ' . $sign,
    ],
]);
echo curl_exec($ch);

Python

import time, hmac, hashlib, urllib.parse, requests

token, secret = 'ym_your_token_here', 'your_secret_here'
path, params = '/api/v1/demo', {'keyword': 'test'}
ts, nonce = str(int(time())), 'a1b2c3d4e5f6'
canonical = '&'.join(f'{k}={urllib.parse.quote(str(params[k]))}' for k in sorted(params))
raw = f"GET\n{path}\n{ts}\n{nonce}\n{canonical}"
sign = hmac.new(secret.encode(), raw.encode(), hashlib.sha256).hexdigest()

r = requests.get('https://your-domain.com' + path, params=params, headers={
    'X-Api-Token': token,
    'X-Api-Timestamp': ts,
    'X-Api-Nonce': nonce,
    'X-Api-Signature': sign,
})
print(r.json())

5. 错误码

Code	说明
1001	缺少 API Token
1002	Token 无效或账号已禁用
1003	签名校验失败
1004	时间戳超出容差范围
1005	nonce 重放请求
1006	接口不存在或已下线
1007	缺少必填参数
1008	请求过于频繁，触发限流
1009	积分不足
2000	上游接口返回异常
5000	服务内部错误