Open API通用说明

1.1. 通用说明

1.1.1. API协议

本API文档所涉及接口均遵循HTTPS协议，请求和响应数据格式如无特殊说明均为 JSON。

1.1.2. 编码方式

若无特殊说明或响应头中的 Content-Type 未指定编码，请求和响应中的字符编码均使用UTF-8编码。

1.1.3. 接入授权

API所有接口根据请求头(HEADER)中的bearer token进行身份认证和鉴权，系统会校验bearer token的有效性。

通过Authorization HTTP Header传递Bearer的授权token，如下:

HTTP Header名称	Value	描述
Authorization	token	token表示为授权令牌，由调用方根据规则生成

1.1.3.1. token

token生成规则如下，所有内容使用半角逗号(,)按照顺序拼接，再经过base64编码。

token=base64(app_id + "," + timestamp + "," + signature)

1.1.3.2. signature

signature生成规则如下，采用sha1加密算法生成签名串(此处加号+ 代码字符串拼接)

signature=sha1(app_id + app_secret + timestamp)

1.1.3.3. timestamp

timestamp取值规则如下，发起请求时的时间戳，精确到秒。这个值和接收到请求时的服务器时间戳偏差(正负)超过1200秒(20分钟)时，请求会被拒绝，需要重新生成token(请使用UTC+08:00 中国北京时间)。

1.1.3.4. app_id、app_secret

请联络和您对接的业务代表获取接入授权。

1.1.3.5. 示例

浏览器调试控制台输出示例：

1.1.4. 时间格式

API中涉及到时间字段的，使用时间戳传值；

1.1.5. API请求

HTTP Header

调用方应遵循 HTTP 协议设置相应的 Header，目前支持的 Header 为 Content-Type, 用于指定数据格式。

若接口中没有特殊说明，本文档中所有接口调用时的 Content-Type 应为 application/json。

HTTP Method

调用方应根据具体接口的要求设置 HTTP Method 为 GET、POST、DELETE等。

GET – 获取单个或一组资源信息

POST – 创建或更新资源

DELETE – 删除资源

Query Parameter

API 请求中需要提供必要的通用参数(Query Parameter 方式传递)、每个接口要求的参数, 并声明正确的编码方式。

1.1.6. API响应

HTTP Header

响应会根据接口要求设置 Content-Type。本文档中 Content-Type 均设置为 application/json。

HTTP 状态码

支持 HTTP 标准状态码，具体如下:

状态码	名称	说明
200	成功	当API请求被正确处理,且能按设计获取结果时,返回该状态码; 亦适用于批量接口返回部分结果
3xx	跳转	在特定情况下,API 可能会返回这些状态码,建议调用方按照 HTTP 标准来处理
4xx	客户端错误	由客户端原因造成的错误
5xx	服务器端错误	API 或其下层服务发生内部错误

其中，4xx和5xx的状态码仅用于辅助快速识别问题，不作为包含实际语义的返回码。

HTTP Body

响应的 JSON 数据中包含三部分内容，分别为返回码、返回信息和数据，如下表所示：

名称	类型	描述	限制	是否必填
code	int32	返回码	等于200表示成功，不等于 200 表示错误	Y
msg	string	错误信息	code不等于 0 时，msg 为错误信息	N
result	object	资源数据	具体返回内容见各接口定义，如果code不等于0，则data字段不出现。	Y
trace	string	接口调用标识串	无实际作用，仅用于接口数据排查	N

更多详细返回码和错误信息见，附录“返回码定义”。

如果调用参数不正确，则会返回错误信息，并且data字段不出现，举例如下：

{
   "code": 4902,
   "msg": "error message",
   "traceId": "xxxxxxxxxxxxxx",
}

正常响应示例：

{
   "code": 200,
   "traceId": "xxxxxxxxxxxxxx",
   "result":{}
}

1.1.7. API安全

以下三个层面来保证API安全：

HTTPS

IP白名单

API授权（签名验证）

1.1.8. 配额和频次控制

基于账号的订阅计划进行频次限定。

1.1. 通用说明#

1.1.1. API协议#

1.1.2. 编码方式#

1.1.3. 接入授权#

1.1.3.1. token#

1.1.3.2. signature#

1.1.3.3. timestamp#

1.1.3.4. app_id、app_secret#

1.1.3.5. 示例#

1.1.4. 时间格式#

1.1.5. API请求#

1.1.6. API响应#

1.1.7. API安全#

1.1.8. 配额和频次控制#