API 文档

# 数据签名规范

# 签名说明

在 API 请求通过互联网传输的过程中，为防止请求被篡改或伪造，所有**私有接口（如资金相关、交易类接口）**必须进行签名校验。

通过签名机制可确保参数在传输过程中未被篡改，并有效防止重放攻击。

请求组成结构

一个合法请求包含以下关键字段（其中除 secret_key 外，全部通过请求 Header 传递）：

参数名 说明
access_key API 访问密钥，标识用户身份
secret_key 签名所使用的密钥，仅在创建 API Key 时展示一次，请妥善保管，不得传输
timestamp 发起请求时的时间戳（毫秒级，13 位，如：1632811287325），用于防止重放攻击
nonce 随机 UUID（如：053a1b81-48a0-4bb1-96b2-60f6e509d911），确保请求唯一性
sign 通过签名算法生成的签名字符串，用于校验参数完整性

除 secret_key 外，以上字段需全部作为 Header 参数传递。

# 签名步骤

# Step 1：定义参数 Map

定义一个字典（Map）对象，将接口请求中使用的业务参数按 key-value 形式放入其中。

# Step 2：添加公共参数

将以下三个签名公共参数加入该 Map 中：

  • access_key：访问密钥
  • timestamp：毫秒级时间戳（13 位）
  • nonce：随机 UUID 字符串

# Step 3：参数排序 & 拼接

对 Map 中的所有参数按 ASCII 字典序进行升序排序。

然后将排序后的参数拼接为如下格式的字符串：

key1=value1&key2=value2&key3=value3

# Step 4：生成签名值 sign

使用 secret_key 对上一步拼接的字符串执行以下加密操作：

  • 加密方式：HMAC-SHA1
  • 编码方式：Base64

最终输出的值即为签名参数 sign。

secret_key 是您在商户平台创建 API Key 时生成的密钥，仅展示一次，请务必妥善保存。

# Step 5：构建请求并发送

将以下字段添加到 HTTP 请求的 Header 中：

access_key: your_access_key
timestamp : 毫秒时间戳
nonce     : UUID 随机字符串
sign      : 第 4 步生成的签名

然后将请求发送至对应接口地址。

商户签名流程图例

img

# 签名调试工具使用

为帮助开发者快速验证签名逻辑，平台提供内置的签名调试工具 SignUtil，支持在线生成签名并校验参数格式。

# 访问路径

登录收银台后台 → 【开发者中心】 → 【API 文档】 → 点击【签名工具】入口

img

# 使用说明

  1. 打开签名工具页面；
  2. 输入接口所需的业务参数；
  3. 填写有效的 access_key；
  4. 输入对应的 secret_key（用于本地调试，不会上传）；
  5. 点击「生成签名」按钮查看计算结果；
  6. 将生成的 sign 值用于请求 Header 测试调用接口。

img

# 安全建议

  • 签名工具仅供调试使用，请勿在生产环境暴露 secret_key；
  • 调试所用的 access_key 建议设置其 IP 白名单为 0.0.0.0，便于测试；
  • 强烈建议在调试完成后，废弃该 access_key 并重新创建新 Key 用于生产调用；
  • 不要使用已有生产 API Key 进行调试，避免潜在风险。

← 接口连通性测试 →