接入与签名规范

接入准备

接入方需要申请 appid、应用密钥 secret、公私钥，并申请开发者账号及接口编码权限。申请资料包括企业信息、法定代表人或授权人信息；使用 OAuth2 时还需要登记 redirect_uri。

公共请求参数

请求头包含 sign-method、encrypt-mode、encrypt-algorithm、appid、nonce、timestamp、sign、app-sign 和可选的 trace-uuid。普通业务接口还使用 access_token、固定值为 op 的 openapi_tag，以及按下游系统约定的 endpoint_code。

• sign-method：RSA2、MD5 或 SM2WITHSM3。
• encrypt-mode：NONE、ALL 或 PARTIAL，省略时按 NONE 处理。
• encrypt-algorithm：AES、RSA 或 SM4WITHSM2；启用全部或部分加密时必填。
• nonce：五分钟内不应重复。
• timestamp：秒级时间戳。

摘要 sign

• GET：对 URL 查询参数进行 URL 编码后，使用 sign-method 指定的摘要算法计算摘要。
• POST：拼接 URL 查询参数和 application/json 请求体后计算摘要。其他 Content-Type 的请求体不参与拼接。
• 响应：直接对 JSON 响应体计算摘要。

签名 app-sign

将除 app-sign 外的请求头按 ASCII 升序排列，拼接为 key1=value1&key2=value2，再追加 &secret=应用密钥。RSA2 和 SM2WITHSM3 使用签名方私钥签名并输出小写 HEX；MD5 输出小写 32 位结果。

加密

GET 全部加密时使用 encrypted_resource；AES 还需附带 encrypt_nonce 与 associated_data。POST 全部加密时将请求体放入 encryptedResource，AES 对应使用 encryptNonce 与 associatedData。部分加密只适用于字符串和数字，不适用于对象或数组。

统一响应结构为 code、msg、data。附录给出的通用业务码为：0 成功、100 系统异常、401 认证失败。