开放接口文档

1. 接口规范

1.1 基础信息

项目	说明
认证方式	HMAC请求签名认证
编码格式	UTF-8
数据格式	JSON
基础URL	https://api.example.com
accessKey	test
accessSecret	pWy3TNfTiUKDKgzZPDwmrQ

TIP

💡基础url、accessKey、acessSecret在系统上线时联系平台管理员获取

1.2 公共请求头

所有请求必须包含以下Header参数：

参数名	类型	必填	说明
accessKey	string	是	平台分配的身份标识（例：test）
timestamp	long	是	请求发起时间戳（UNIX秒级时间戳）
nonce	string	是	6位随机字符串（建议数字字母组合）
sign	string	是	请求签名（计算方式见签名算法）

2. 签名算法

2.1 签名生成流程

1. 参数排序拼接：
   按以下顺序拼接参数：

[method]&[url]&[accessKey]&[timestamp]&[nonce]

- method：全大写（GET/POST/PUT等）
- url：去除协议和域名的接口路径（例：`/api/sysOpenAccess/helloWorld`）

2. 生成签名串：

POST&/api/sysOpenAccess/helloWorld&test&1717641235&a1B2c3

3. 加密处理：
   • 使用对应accessSecret作为密钥
   • 使用HMAC-SHA256算法生成签名
   • 对结果进行Base64编码

TIP

💡HMAC-SHA256在线计算：https://1024tools.com/hmac

2.2 签名生成示例

Python

import hmac
import hashlib
import base64

def generate_sign(access_secret: str, sign_str: str) -> str:
    """
    生成HMAC-SHA256签名

    :param access_secret: 平台分配的密钥 	pWy3TNfTiUKDKgzZPDwmrQ
    :param sign_str: 待签名字符串
    :return: Base64编码的签名
    """
    # 将密钥和签名字符串转换为bytes类型
    secret_bytes = access_secret.encode('utf-8')
    message_bytes = sign_str.encode('utf-8')

    # 创建HMAC对象
    hmac_obj = hmac.new(secret_bytes, message_bytes, hashlib.sha256)

    # 生成Base64编码的签名
    return base64.b64encode(hmac_obj.digest()).decode('utf-8')

# 调用示例
if __name__ == "__main__":
    # 平台分配的密钥（示例）
    access_secret = "pWy3TNfTiUKDKgzZPDwmrQ"

    # 构造签名字符串（实际需要根据请求动态生成）
    sign_str = "POST&/api/sysOpenAccess/helloWorld&test&1717641235&a1B2c3"

    # 生成签名
    signature = generate_sign(access_secret, sign_str)

    print(f"生成的签名: {signature}")

Java

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.util.Base64;

public class SignatureGenerator {
    /**
     * 生成 HMAC-SHA256 签名
     * @param accessSecret 平台分配的密钥
     * @param signStr 待签名字符串
     * @return Base64编码的签名
     */
    public static String generateSign(String accessSecret, String signStr) {
        try {
            Mac sha256_HMAC = Mac.getInstance("HmacSHA256");
            SecretKeySpec secret_key = new SecretKeySpec(
                accessSecret.getBytes("UTF-8"),
                "HmacSHA256"
            );
            sha256_HMAC.init(secret_key);

            byte[] hashBytes = sha256_HMAC.doFinal(signStr.getBytes("UTF-8"));
            return Base64.getEncoder().encodeToString(hashBytes);
        } catch (Exception e) {
            throw new RuntimeException("Error generating signature", e);
        }
    }

    public static void main(String[] args) {
        String accessSecret = "pWy3TNfTiUKDKgzZPDwmrQ";

        String signStr = "POST&/api/sysOpenAccess/helloWorld&test&1717641235&a1B2c3"; // 示例待签名字符串
        String signature = generateSign(accessSecret, signStr);
        System.out.println("Generated Signature: " + signature);
    }
}

C#

using System;
using System.Security.Cryptography;
using System.Text;

class SignatureGenerator
{
    /// <summary>
    /// 生成 HMAC-SHA256 签名
    /// </summary>
    /// <param name="accessSecret">平台分配的密钥</param>
    /// <param name="signStr">待签名字符串</param>
    /// <returns>Base64编码的签名</returns>
    public static string GenerateSign(string accessSecret, string signStr)
    {
        using (HMACSHA256 hmac = new HMACSHA256(
            Encoding.UTF8.GetBytes(accessSecret)))
        {
            byte[] hashBytes = hmac.ComputeHash(
                Encoding.UTF8.GetBytes(signStr));
            return Convert.ToBase64String(hashBytes);
        }
    }

    static void Main(string[] args)
    {
        string accessSecret = "pWy3TNfTiUKDKgzZPDwmrQ";
        string signStr = "POST&/api/sysOpenAccess/helloWorld&test&1717641235&a1B2c3";

        string signature = GenerateSign(accessSecret, signStr);
        Console.WriteLine($"生成的签名: {signature}");
    }
}

3. 响应规范

3.1 通用响应格式

{
  "code": 200,
  "type": "success",
  "message": "success",
  "result": {}
}

3.2 状态码说明

状态码	说明	处理建议
200	请求成功	正常处理返回数据
400	参数错误或缺失	检查参数格式和必填项
401	签名无效/身份验证失败	检查签名算法和密钥有效性
403	权限不足	检查接口权限配置
429	请求过于频繁	降低调用频率
500	服务器内部错误

4. 安全要求

1. 密钥管理：
   • accessSecret需加密存储
   • 禁止在客户端代码明文存储密钥
2. 时间戳验证：
   • 服务端会校验时间戳与服务器时间差异（建议误差±300秒）