API 加签文档

Python 示例参考

• Github: https://github.com/ComNergy/openapi-python
• Gitee: https://gitee.com/gjy_5/openapi-python

1. 接入准备

1.1 获取接入凭证

请访问管理后台获取接入所需凭证：

• 管理后台地址：https://dockerweb.gongjiyun.com
• 操作路径：账号管理 > API 管理 > 创建 Token

1.2 接入必要参数

参数名	说明	示例值
生产环境地址	API 网关地址	https://openapi.suanleme.cn
API 版本号	当前支持的版本	1.0.0
token	接口调用凭证	a0e13fe1-5626-4c05-926b-20f586c69102-20240821144204
user_rsa_prik	用户上传的 RSA 私钥	-
system_rsa_pubk	系统分配的 RSA 公钥	-

2. 接口调用规范

2.1 请求规范

• 字符编码：UTF-8
• 请求方式：仅支持 POST/GET
• Content-Type：application/json

2.2 请求头 Header 参数

参数名	是否必填	说明	示例值
version	是	API 版本号	1.0.0
token	是	接口调用凭证	a0e13fe1-5626-4c05-926b-20f586c69102-20240821144204
timestamp	是	时间戳 (毫秒)	1721299458423
sign_str	是	签名字符串 (Base64)

2.3 响应格式

列名	类型	不是 null	说明	实例值
code	String	是	响应 code	0000
message	String	否	响应说明	success
data	Object	否	数据体	{"username":"user1","password":"password1"}

{
    "code": "0000",      // 响应码
    "message": "success", // 响应说明
    "data": {            // 业务数据
        "key": "value"
    }
}

3. 加签规则

3.1 签名规则

1. 计算请求体待签名字符串，如果为请求 GET 请求，则验签是 data 字段为空字符串。

构造待签名字符串，按以下格式拼接：

{path}\n{version}\n{timestamp}\n{token}\n{data}

Rust 示例如下

//format!("{}\n{}\n{}\n{}\n{}", path, version, timestamp, token, data)

/api/user/order/get_this_week_residue_withdrawal_count
1.0.0
1724222524375
a0e13fe1-5626-4c05-926b-20f586c69102-20240821144204
{"username":"user1","password":"password1"}

2. 获取到待签名字符串后，获取 RSA 私钥通过 rsa_sha256_prik_sign 签名算法，进行计算签名，然后生成 BASE64 字符串。
3. 然后设置请求头里的 sign_str 字段，值为生成的 BASE64 格式的加签字符串。

3.2 加密规则

1. 只对请求体（Body）内容进行加密
2. 加密需要通过获取的 RSA 公钥进行加密操作。
3. 首先将请求体内容序列化为 bytes 数组，然后根据 RSA 公钥对该字符串进行 rsa_pubk_encrypt 算法加密。
4. 之后将加密 bytes 数组转换为 BASE64 字符串，放入请求体中。
5. 如果请求同时需要加密和加签，则需要先进行加密步骤，再进行加签步骤。

3.3 调用示例

curl --location --request POST 'https://openapi.suanleme.cn/api/{api-path}' \
--header 'version: 1.0.0' \
--header 'token: a0e13fe1-5626-4c05-926b-20f586c69102-20240821144204' \
--header 'timestamp: 1724222524375' \
--header 'sign_str: {签名结果}' \
--data-raw '{"key":"value"}'

例如

curl --location --request POST 'https://openapi.suanleme.cn/api/{api-path}' \\  
\--header 'token: a0e13fe1-5626-4c05-926b-20f586c69102-20240821144204' \\  
\--header 'timestamp: 1724222524375' \\  
\--header 'version: 1.0.0' \\  
\--header 'sign_str: EowIBAAKCAQEArbNcSNSLjHzqOzrYL+7afEh5TI4hn1BCxsuzY02c1RMn24a2YEvpqCCVDxmgN/dcAdcCcvhO/2wDG389LuEkw+QhVPzdAE29bbzz+Gb/FDusVNo6tl8mbfd/XA53h3sOCekEMP2QCoPAoUO94wUWK5RpjsONf9Bs0Q6YUmL4TWqvPGmWjc/Y8winDtFzKN2his5PhbWlRiSkENGXSma6lr66BA/SduAY/Fl8YxEWThVkYsAurg0rEd83DilN4zp7hZf82Msjgp8kPm/SMHTEF2V2cOo82m12HyRJKuKS0L8WPVIwQmXJ6VN55ue+b96sryUs/WZyfiXTh0thoa9vqQIDAQABAoIBAQCsOMDQSUTPl27aKR7+b5FbVrRF7kpx3i9HUeLcG7DbJrIHHAspcTsLgrqoDR1pQC2OeXMpMP+KirqOAdtU5tAAFenijRBGY83kx0sSSHSyx/O28eTyu2ar84/oY0OqJZ0mwE1ykYXGlxlgC31zYLC5pt3+Oe/LAYlSwmjOjuhoQDMZoiCByIw6oDAVLIlZwTl8A/HAR1yacDTh6lps1vTZ5lBfIDpbn1gHb2GWqHu8q9oD9G9IEyWwwTE1IsNXVwBKEifjLubd2WfTWDmROVZZ9T4AXm/40/Eb6ALApwY5s7lBMIiapmcJZzlyELEukUMmYN7vHBjdMDOPK3tjLSKNA' \\  
\--data-raw '{"username":"test1","password":"password1"}'