📋接口加密签名

一、接口调用规范

1.1 接口基础信息

接口前缀：所有业务接口均需添加统一前缀 /api/v1/exchange

拼接规则：/api/v1/exchange + 原始业务接口路径

示例：原始接口 /application/v1/query，实际请求路径为 /api/v1/exchange/application/v1/query

二、签名规范（Signature）

2.1 请求头参数

所有请求均需在 Header 中携带以下鉴权参数：

参数名	说明
`X-Auth-AppId`	应用 ID
`X-Auth-Timestamp`	当前时间戳（毫秒）
`X-Auth-Sign`	签名值
`Authorization`	鉴权令牌

⚠️ 例外：获取 Token 接口无需携带 Authorization Header。

2.2 签名生成算法

第一步：准备固定字符串

按顺序拼接：AppId + 时间戳(毫秒) + AppSecret

第二步：准备业务字符串

请求方式	处理规则
GET	将所有参数按 Key 的字母顺序排序，拼接为 `key=value` 格式（多个参数用 `&` 连接，忽略空值，不进行 UrlEncode）
POST	直接使用请求体（Body）的原始内容

第三步：生成签名

将"固定字符串"与"业务字符串"首尾相连，对完整字符串进行 SHA-256 哈希运算，输出小写十六进制字符串。

三、数据加密规范（Encryption）

为保证数据安全，接口数据需进行加密传输。

⚠️ 例外：获取 Token 接口无需加密但需要签名，直接以明文方式传输即可。

3.1 加密前置准备

参数	说明
密钥（data_secret）	由后台分配，作为 AES 加密的密码
偏移量（IV）	客户端随机生成 16 字节数据，并进行 Base64 URL Safe 编码
加密算法	AES-256-CBC，填充模式：PKCS5

3.2 GET 请求加密流程

构造明文：将所有业务参数拼接为 key=value 格式（多个参数用 & 连接，Key 和 Value 均需进行 UrlEncode）

执行加密：使用 data_secret 和 IV 对明文进行 AES 加密，再进行 Base64 URL Safe 编码，得到密文

重组请求：将原有的 Query 参数替换为以下两个参数：

data = 加密后的密文

iv = 生成的 IV 字符串

3.3 POST 请求加密流程

构造明文：直接使用原始请求体（Body）内容

执行加密：使用 data_secret 和 IV 对明文进行 AES 加密，再进行 Base64 URL Safe 编码，得到密文

重组请求：将请求体替换为以下 JSON 格式：

{
  "data": "加密后的密文",
  "iv": "生成的IV字符串"
}

4.响应内容规范 (Response)

服务端返回的响应内容同样遵循上述加密与签名机制，具体规则如下：
●响应加密：响应体（Body）的加密逻辑与请求端完全一致，使用 AES-256-CBC + PKCS5 算法，并将加密后的密文与新的 IV 一并返回（Token 相关接口除外）。
●响应签名：响应 Header 中同样会携带X-Auth-Timestamp 和 X-Auth-Sign 供客户端验签。
●鉴权参数更新：响应中的 X-Auth-Timestamp 为服务端生成响应时的新时间戳。客户端需使用新时间戳及响应体内容重新计算签名，以验证响应的真实性与完整性。

5.错误响应 (Error Response)

statusCode 说明触发场景
40000 参数错误缺少必填参数或参数格式不合法
40100 鉴权失败鉴权失败、签名校验不通过、数据解密失败
40000 错误响应示例：

{
  "statusCode": 40000,
  "message": "缺少必填参数"
}

40100 错误响应示例：

{
  "statusCode": 40100,
  "message": "鉴权失败"
}

💡 排查建议：
●收到 40000 时：检查请求中是否遗漏了必填参数，参数类型和格式是否符合接口要求。
●收到 40100 时：检查 AppId / AppSecret 配置是否正确、时间戳是否存在较大偏差、签名拼接逻辑是否符合规范、加密密钥与 IV 是否匹配。

接口调用规范说明

1. 接口基础信息

接口前缀：所有业务接口均需添加统一前缀 /api/v1/exchange。

拼接规则：/api/v1/exchange + 原始业务接口路径。

示例：原始接口 /application/v1/query，实际请求路径为 /api/v1/exchange/application/v1/query。

2. 签名规范 (Signature)

所有请求均需在 Header 中携带以下三个鉴权参数：

X-Auth-AppId：应用 ID

X-Auth-Timestamp：当前时间戳

X-Auth-Sign：签名值

Authorization：鉴权令牌

⚠ 例外：获取Token 接口无需携带 Authorization Header

签名生成算法：

准备固定字符串：按顺序拼接 AppId + 时间戳(毫秒) + AppSecret。

准备业务字符串：

GET 请求：将所有参数按 Key 的字母顺序 排序，拼接为 key=value 格式（多个参数用 & 连接，忽略空值，不进行 UrlEncode）。

POST 请求：直接使用请求体（Body）的原始内容。

生成签名：将"固定字符串"与"业务字符串"首尾相连，对完整字符串进行 SHA-256 哈希运算，输出 小写十六进制 字符串。

3. 数据加密规范 (Encryption)

为保证数据安全，接口数据需进行加密传输。

⚠ 例外：获取Token接口无需加密但需要签名，直接以明文方式传输即可。

加密前置准备：

密钥 (data_secret)：由后台分配，作为 AES 加密的密码。

偏移量 (IV)：客户端随机生成 16 字节数据，并进行 Base64 URL Safe 编码。

加密算法：AES-256-CBC，填充模式：PKCS5。
各请求类型加密流程：
GET 请求：

构造明文：将所有业务参数拼接为 key=value 格式（多个参数用 & 连接，Key 和 Value 均需进行 UrlEncode）。

执行加密：使用 data_secret 和 IV 对明文进行 AES 加密，得到密文。

重组请求：将原有的 Query 参数替换为以下两个参数：

data = 加密后的密文

iv = 生成的 IV 字符串

POST 请求：

构造明文：直接使用原始请求体（Body）内容。

执行加密：使用 data_secret 和 IV 对明文进行 AES 加密，得到密文。

重组请求：将请求体替换为 JSON 格式：

{
  "data": "加密后的密文",
  "iv": "生成的IV字符串"
}

4. 响应内容规范 (Response)

服务端返回的响应内容同样遵循上述加密与签名机制，具体规则如下：

响应加密：响应体（Body）的加密逻辑与请求端完全一致，使用 AES-256-CBC + PKCS5 算法，并将加密后的密文与新的 IV 一并返回（Token 相关接口除外）。

响应签名：响应 Header 中同样会携带X-Auth-Timestamp 和 X-Auth-Sign 供客户端验签。

鉴权参数更新：响应中的 X-Auth-Timestamp 为服务端生成响应时的新时间戳。客户端需使用新时间戳及响应体内容重新计算签名，以验证响应的真实性与完整性。

5. 错误响应 (Error Response)

statusCode	说明	触发场景
40000	参数错误	缺少必填参数或参数格式不合法
40100	鉴权失败	鉴权失败、签名校验不通过、数据解密失败

40000 错误响应示例：

{
  "statusCode": 40000,
  "message": "缺少必填参数"
}

40100 错误响应示例：

{
  "statusCode": 40100,
  "message": "鉴权失败"
}

💡 排查建议：
收到 40000 时：检查请求中是否遗漏了必填参数，参数类型和格式是否符合接口要求。
收到 40100 时：检查 AppId / AppSecret 配置是否正确、时间戳是否存在较大偏差、签名拼接逻辑是否符合规范、加密密钥与 IV 是否匹配。

一、接口调用规范#

1.1 接口基础信息#

二、签名规范（Signature）#

2.1 请求头参数#

2.2 签名生成算法#

第一步：准备固定字符串#

第二步：准备业务字符串#

第三步：生成签名#

三、数据加密规范（Encryption）#

3.1 加密前置准备#

3.2 GET 请求加密流程#

3.3 POST 请求加密流程#

4.响应内容规范 (Response)#

5.错误响应 (Error Response)#

接口调用规范说明#

1. 接口基础信息#

2. 签名规范 (Signature)#

3. 数据加密规范 (Encryption)#

4. 响应内容规范 (Response)#

5. 错误响应 (Error Response)#