OpenAPI 文档：签名方式说明

1. 概述

本文档描述了客户端如何使用非对称加密（RSA）对API请求进行签名，并将签名、用户ID和时间戳放在请求头中发送到服务端。

2. 流程说明

2.1 密钥生成

用户使用RSA算法生成公私钥对。

将公钥上传到代理商后台，私钥由客户端妥善保管。

2.2 请求签名（客户端）

客户端生成当前时间的时间戳（Unix时间戳，精确到秒）。

按照规则对请求体进行JSON压缩和排序。

将时间戳和请求体拼接成一个字符串，使用私钥对其进行签名。

将签名、用户ID和时间戳放在请求头中。

2.3 请求发送

客户端将签名后的请求发送到服务端，请求头中包含以下字段：

X-Agency-ID: 代理商ID

X-Signature: 使用私钥生成的签名（Base64编码）

X-Timestamp: 时间戳

·X-Trace·: UUID

3. JSON压缩和排序规则

为了确保客户端和服务端在生成和验证签名时的一致性，请求体必须按照以下规则进行 JSON 字符串化：

JSON 字符串化：

使用 json.dumps() 将整个请求体转换为 JSON 字符串。

数据类型：

数字不能加引号。

示例

原始请求体

{
    "key2": "value2",
    "key1": "value1",
    "key3": {
        "nestedKey2": "nestedValue2",
        "nestedKey1": "nestedValue1"
    }
}

格式化后的请求体

{"key1":"value1","key2":"value2","key3":{"nestedKey1":"nestedValue1","nestedKey2":"nestedValue2"}}

4. 请求示例

请求头

请求体

{
    "key1": "value1",
    "key2": "value2"
}

5. 代码示例

5.1 生成签名（客户端）

5.2 发送请求（客户端）

6. 注意事项

密钥安全：私钥必须妥善保管，避免泄露。

时间同步：确保客户端的系统时间与服务端同步，避免因时区差异导致验证失败。

HTTPS：使用HTTPS协议传输数据，确保数据在传输过程中的安全性。

接口返回code说明：
1.Unauthorized：验签不通过
2.Not Found：资源不存在。（错误的请求参数，如：accountId不存在）
3.Too Many Requests：请求频繁
4.invalidBody：请求体不符合规范
5.insufficientBalance: 余额不足

通过以上说明和代码示例，客户端可以正确生成签名并发送请求，确保API请求的完整性和安全性。

7. Webhook 签名方式说明

7.1 概述

本文档描述了服务端如何对 webhook 回调请求进行签名，以及代理商如何验证签名。

7.2 密钥管理

服务端使用 RSA 算法生成公私钥对

将公钥提供给代理商，代理商在后台配置公钥

服务端保管私钥，用于对 webhook 请求进行签名

7.3 签名流程

服务端生成当前时间的时间戳（Unix时间戳，精确到秒）

将请求体转换为 JSON 字符串

将时间戳和请求体拼接成一个字符串，使用私钥对其进行签名

将签名和时间戳放在请求头中

7.4 请求头

服务端发送 webhook 请求时，请求头中包含以下字段：

X-Agency-ID: 代理商ID

X-Signature: 使用私钥生成的签名（Base64编码）

X-Timestamp: 时间戳

X-Trace: UUID

7.5 验签示例（代理商）

7.6 注意事项

代理商端注意事项：

时间验证：建议验证时间戳是否在合理的时间范围内（如5分钟），防止重放攻击

公钥安全：公钥虽然可以公开，但仍建议通过安全渠道传输和存储

HTTPS：webhook 回调必须使用 HTTPS 协议，确保传输安全

服务端实现说明：
4. 重试机制 ✅：

针对 webhook 回调请求实现了智能重试机制

根据不同错误类型进行相应处理：

网络超时：等待 30 秒后重试

服务器错误（5xx）：等待 1 分钟后重试

客户端错误（4xx）：仅对特定错误码进行重试

最多进行 3 次重试尝试

每次重试都会记录详细的日志信息

确保消息最终送达代理商服务器

8. OpenAPI情况说明

8.1 错误状态码

invalidBody：请求体不符合规范

Unauthorized：验签不通过

Not Found：资源不存在

insufficientBalance：余额不足

Too Many Requests：请求频繁

verifySignFailed：所有 secret 比对都未通过

accountNotExist：账户/代理商不存在

notAgencyMerchant：筛选商户信息时accountId不是代理商的商户，或者currencyAcoount的商户不是代理商的商户

tradeCurrencyAccountFoundErr：币种商户查询失败

dbNotMatch：对于精确匹配单一数据，请求数据规范的情况下，未匹配到数据状态码

OpenAPI 文档：签名方式说明