认证机制

认证流程

客户端请求 → 验证签名 → 验证时间戳 → 验证Nonce → 频率限制 → 处理业务 → 返回响应

必需参数

每个 API 请求都必须包含以下认证参数：

签名算法详解

第一步：构造签名字符串

签名字符串 = HTTP方法 + 请求路径 + timestamp + nonce + 规范化参数

第二步：规范化参数

1. 排除 signature 参数
2. 将剩余参数按字母顺序排序
3. 使用 = 连接键值对
4. 使用 & 连接多个参数

示例：

原始参数: {'{'}
  "access_key": "ak_test123",
  "card_no": "CARD123456789",
  "nonce": "test123",
  "signature": "abc123",
  "timestamp": "1730619000"
{'}'}

规范化后: access_key=ak_test123&card_no=CARD123456789&nonce=test123&timestamp=1730619000

第三步：生成签名

# 使用 OpenSSL 生成签名
signature = HMAC-SHA256(签名字符串, secret_key)

完整示例代码

使用 Python：

import hmac
import hashlib
import time
import uuid

def generate_signature(method, path, params, secret_key):
    # 1. 排除签名参数，按字母顺序排序
    sorted_params = "&".join(
        f"{'{'}k{'}'}={'{'}v{'}'}" for k, v in sorted(params.items())
        if k != 'signature'
    )

    # 2. 构造签名字符串
    sign_str = f"{'{'}method{'}'}{'{'}path{'}'}{'{'}params['timestamp']{'}'}{'{'}params['nonce']{'}'}{'{'}sorted_params{'}'}"

    # 3. HMAC-SHA256 签名
    return hmac.new(
        secret_key.encode(),
        sign_str.encode(),
        hashlib.sha256
    ).hexdigest()

# 使用示例
params = {'{'}
    'access_key': 'ak_test123',
    'timestamp': str(int(time.time())),
    'nonce': str(uuid.uuid4()),
{'}'}
signature = generate_signature('GET', '/api/v1/heartbeat', params, 'sk_test456')
print(f"生成签名: {'{'}signature{'}'}")

签名验证失败排查

1. 检查时间戳

   • 确保时间戳在当前时间的 ±300 秒内
   • 检查服务器时间是否准确同步

2. 检查参数顺序

   • 确保所有参数按字母顺序排序
   • 确保排除 signature 参数

3. 检查密钥

   • 确认 SecretKey 正确无误
   • 检查是否有前导或后缀空格

4. 检查编码

   • 确保使用 UTF-8 编码
   • 检查特殊字符是否正确转义

请求格式说明

GET 请求

• 参数传递: 通过 URL Query String 传递
• 示例: /api/v1/info?card_no=CARD123&access_key=ak_xxx&timestamp=1234567890&nonce=abc123&signature=xyz789
• 注意: GET 请求不需要设置 Content-Type 头

POST 请求

• 支持格式:
  • application/json (推荐)
  • application/x-www-form-urlencoded
• JSON 格式优势:
  • 更清晰的参数结构
  • 更好的错误提示
  • 支持复杂数据类型
  • 便于参数验证
• 签名计算: 两种格式的签名算法相同,都需要对参数进行排序和拼接

请求头设置

# JSON 格式
Content-Type: application/json

# Form 格式
Content-Type: application/x-www-form-urlencoded

# 通用请求头（建议）
User-Agent: YourAppName/1.0
X-Request-ID: unique-request-id