调用流程

概述

本文档详细介绍了如何调用开放平台 API，包括签名验证机制、请求格式和示例代码。

认证方式

API 使用基于 HMAC-SHA1 的签名验证机制，确保请求的安全性和完整性。

请求头参数

每个 API 请求都必须包含以下请求头：

参数名	类型	必填	描述
secretId	string	是	密钥ID，用于标识调用方身份
signature	string	是	请求签名，用于验证请求的合法性
timestamp	string	是	请求时间戳（Unix时间戳，单位：秒）

签名生成规则

1. 参数拼接

按照排序后的顺序，将参数拼接成字符串：

key1=value1&key2=value2&key3=value3

注意：参数值需要进行 URL 编码。

2. 签名字符串构建

签名字符串 = 请求路径 + "?" + 参数字符串

3. 签名计算

使用 HMAC-SHA1 算法，以 secretKey 为密钥，对签名字符串进行签名：

signature = HMAC-SHA1(签名字符串, secretKey)

请求示例

GET 请求示例

签名计算过程：

排序后的参数：

category_id=1&page=1&secret_id=your_secret_id&timestamp=1640995200

签名字符串：

/v1/courses?category_id=1&page=1&secret_id=your_secret_id&timestamp=1640995200

计算签名：

signature = HMAC-SHA1(签名字符串, secretKey)

POST 请求示例（JSON）

签名计算过程：

排序后的参数：

course_id=123&price=99.99&quantity=1&secret_id=your_secret_id&timestamp=1640995200

签名字符串：

/v1/orders?course_id=123&price=99.99&quantity=1&secret_id=your_secret_id&timestamp=1640995200

计算签名：

signature = HMAC-SHA1(签名字符串, secretKey)

输出结果

接口返回结果的格式（JSON 结构体，utf8 编码格式），具体说明如下:

名称	类型	描述
code	Number	接口返回状态码(具体查看通用错误码)
message	String	错误状态下提示信息
data	Object	接口处理后，返回的对象。具体见各接口内详细定义

代码示例

Python 示例

JavaScript 示例

注意事项

时间同步: 确保客户端时间与服务器时间同步，时间偏差不能超过 60 秒

参数编码: 参数值必须进行 URL 编码

签名算法: 使用 HMAC-SHA1 算法生成签名

密钥安全: 妥善保管 secretKey，不要在客户端代码中明文存储

环境区分: 在生产环境下，才会做签名验证，其他环境只验证 secretId 是否有效

常见问题

Q: 签名验证失败怎么办？

A: 请检查以下几点：

参数是否按字典序排序

参数值是否进行了 URL 编码

时间戳是否在有效范围内

签名字符串构建是否正确

使用的 secretKey 是否正确

Q: 如何获取 secretId 和 secretKey？

A: 机构后台的基本资料，可以获取和重新生成密钥对。

概述#

认证方式#

请求头参数#

签名生成规则#

1. 参数拼接#

2. 签名字符串构建#

3. 签名计算#

请求示例#

GET 请求示例#

POST 请求示例（JSON）#

输出结果#

代码示例#

Python 示例#

JavaScript 示例#

注意事项#

常见问题#

Q: 签名验证失败怎么办？#

Q: 如何获取 secretId 和 secretKey？#

概述