公共请求格式

请求域名

测试环境请求域名:

api.pre-qiandun365.com

生产环境请求域名:

api.qiandun365.com

提示

测试环境下的接口均属于沙箱模拟环境，此环境仅用于开发调试，所签合同文件及认证等操作均不具备法律效力。正式上线使用时请务必切换到正式生产环境调用相关接口。

沙箱模拟环境中所创建的数据不可以直接使用到正式生产环境中，正式上线使用时请注意重新创建相关数据。

📌

本页末尾附Demo，其他语言请联系客服获取

API调用

公共入参

公共请求参数是指每个接口都需要使用到的请求参数。

参数名称	位置	必须	描述
X-Ca-Key	Header	是	Appkey，调用API的身份标识，可以到签盾企业控制台申请
X-Ca-Signature	Header	是	通过签名计算规则计算的请求签名串，参照：签名计算规则
X-Ca-Timestamp	Header	否	API 调用者传递时间戳，值为当前时间的毫秒数，也就是从1970年1月1日起至今的时间转换为毫秒，时间戳有效时间为15分钟
X-Ca-Nonce	Header	否	API请求的唯一标识符，15分钟内同一X-Ca-Nonce不能重复使用，建议使用 UUID，结合时间戳防重放
Content-MD5	Header	否	当请求 Body 非 Form 表单时，需要计算 Body 的 MD5 值传递给云网关进行 Body MD5 校验
X-Ca-Signature-Headers	Header	否	指定哪些Header参与签名，支持多值以","分割，默认只有X-Ca-Key参与签名，为安全需要也请将X-Ca-Timestamp、X-Ca-Nonce进行签名，例如：X-X-Ca-Signature-Headers:Ca-Timestamp,X-Ca-Nonce

签名计算规则

请求签名，是基于请求内容计算的数字签名，用于API识别用户身份。客户端调用API时，需要在请求中添加计算的签名（X-Ca-Signature）。

签名计算流程

准备APPkey → 构造待签名字符串stringToSign → 使用Secret计算签名

1.准备APPKey

Appkey，调用API的身份标识，可以到签盾申请

2.构造待签名字符串stringToSign

HTTPMethod

为全大写，如 POST。

Accept、Content-MD5、Content-Type、Date 如果为空也需要添加换行符”\n”，Headers如果为空不需要添加”\n”。

Content-MD5

Content-MD5 是指 Body 的 MD5 值，只有当 Body 非 Form 表单时才计算 MD5，计算方式为：
String content-MD5 = Base64.encodeBase64(MD5(bodyStream.getbytes("UTF-8"))); bodyStream 为字节数组。

Headers

Headers 是指参与 Headers 签名计算的 Header 的 Key、Value 拼接的字符串，建议对 X-Ca 开头以及自定义 Header 计算签名，注意如下参数不参与 Headers 签名计算：X-Ca-Signature、X-Ca-Signature-Headers、Accept、Content-MD5、Content-Type、Date。

Headers 组织方法：

先对参与 Headers 签名计算的 Header的Key 按照字典排序后使用如下方式拼接，如果某个 Header 的 Value 为空，则使用 HeaderKey + “:” + “\n”参与签名，需要保留 Key 和英文冒号。

String headers =
HeaderKey1 + ":" + HeaderValue1 + "\n"\+
HeaderKey2 + ":" + HeaderValue2 + "\n"\+
...
HeaderKeyN + ":" + HeaderValueN + "\n"

将 Headers 签名中 Header 的 Key 使用英文逗号分割放到 Request 的 Header 中，Key为：X-Ca-Signature-Headers。

Url

Url 指 Path + Query + Body 中 Form 参数，组织方法：对 Query+Form 参数按照字典对 Key 进行排序后按照如下方法拼接，如果 Query 或 Form 参数为空，则 Url = Path，不需要添加？，如果某个参数的 Value 为空只保留 Key 参与签名，等号不需要再加入签名。

String url =
Path +
"?" +
Key1 + "=" + Value1 +
"&" + Key2 + "=" + Value2 +
...
"&" + KeyN + "=" + ValueN

注意这里 Query 或 Form 参数的 Value 可能有多个，多个的时候只取第一个 Value 参与签名计算。

3.使用Secret计算签名

Mac hmacSha256 = Mac.getInstance("HmacSHA256");
byte[] keyBytes = secret.getBytes("UTF-8");
hmacSha256.init(new SecretKeySpec(keyBytes, 0, keyBytes.length, "HmacSHA256"));
String sign = new String(Base64.encodeBase64(Sha256.doFinal(stringToSign.getBytes("UTF-8")),"UTF-8"));

Secret 为 APP 的密钥，请在应用管理中获取。

公共相应参数格式

参数名称	参数类型	必选	参数说明
code	string	是	业务码，200表示成功
msg	string	是	业务信息
success	boolean	是	请求是否成功true/false 同code=200
result	object	否	业务数据

注意

success=false时代表业务失败或异常，开发者可使用业务码code 进行业务逻辑判断。

接口调用出现报错时，开发者可通过常见错误码查找错误排查方法。

DEMO

net-demo.zip
php-demo.zip
python-demo.zip
java-demo.zip

请求域名#

测试环境请求域名:#

生产环境请求域名:#

#

API调用#

公共入参#

签名计算规则#

签名计算流程#

1.准备APPKey#

2.构造待签名字符串stringToSign#

HTTPMethod#

为全大写，如 POST。#

Content-MD5#

Headers#

Headers 组织方法：#

Url#

3.使用Secret计算签名#

公共相应参数格式#

DEMO#

请求域名

测试环境请求域名:

生产环境请求域名:

API调用

公共入参

签名计算规则

签名计算流程

1.准备APPKey

2.构造待签名字符串stringToSign

HTTPMethod

为全大写，如 POST。

Content-MD5

Headers

Headers 组织方法：

Url

3.使用Secret计算签名

公共相应参数格式

DEMO