本文档用于指导代理商如何对每一次 API 请求进行签名，并通过 EVJ 平台的鉴权校验。

1. 概述

EVJ 代理商 API 使用 HMAC-SHA256 作为请求签名方式，用于确保：

请求未被篡改

请求来源可信

防止重放攻击

代理商在调用 API 时必须在请求头中加入签名字段：

Header	必填	说明
X-Access-Key	是	代理商的 API AccessKey
X-Timestamp	是	当前 Unix 时间戳（秒）
X-Nonce	是	唯一随机字符串（防重放）
X-Signature	是	HMAC-SHA256 签名值

2. 签名算法说明

签名原串（StringToSign）

StringToSign = timestamp + "|" + nonce + "|" + request_body

示例：

1736501200|a93bd912abc8fe12|{"cardholder_name":"John"}

说明：

timestamp 必须是 当前服务器时间(Asia/Shanghai) ± 5 分钟以内

nonce 必须是 每次请求唯一（平台会检测是否重复）

request_body 必须是 原始 JSON 字符串（不可格式化、不可加空格）

3. 计算签名

使用以下算法生成 X-Signature：

signature = HMAC_SHA256(StringToSign, SecretKey)

返回十六进制 HEX 字符串，例如：

9d51a43e2c0d1a34f98bd1e2fcd213c76232dc3be...

4. 发送时的 Header 示例

X-Access-Key: ak_XXXXXXXXXX
X-Timestamp: 1736501200
X-Nonce: a93bd912abc8fe12
X-Signature: 9d51a43e2c0d1a34...
Content-Type: application/json

5. 客户端示例代码

以下为 PHP / Node.js / Python 完整签名示例。

5.1 PHP

5.2 Node.js

5.3 Python

6. 平台验签规则

平台会严格执行以下验证：

校验项	说明
AccessKey 是否有效	校验是否存在且未禁用
时间戳是否超时	超过 ±300 秒拒绝请求
nonce 是否重复	防止重放攻击
签名是否正确	比较 HMAC 结果
Body 是否一致	必须使用原始 body

7. 常见错误

错误原因	描述
Body 经过格式化导致签名不一致	必须使用原始 JSON
时间戳偏差太大	超过 5 分钟将拒绝
nonce 重复使用	平台拒绝并记录安全日志
使用错误的 secret	会导致签名验证失败
风控拒绝	同一IP短时间超过10次验签失败会封禁1小时

8. 最佳实践

始终使用 HTTPS

所有请求都用 JSON

随机 nonce 不可重复

服务端时间至少每日同步一次（NTP）

secret 不要放在前端或日志中

敏感信息请脱敏处理

请求签名算法说明

1. 概述#

2. 签名算法说明#

签名原串（StringToSign）#

3. 计算签名#

4. 发送时的 Header 示例#

5. 客户端示例代码#

5.1 PHP#

5.2 Node.js#

5.3 Python#

6. 平台验签规则#

7. 常见错误#

8. 最佳实践#