# 概述

## 基本要求说明

- 接口域名：`https://solution.wps.cn`
- 所有接口调用与返回数据统一 UTF8 编码, JSON 格式
- HTTP-Header 中的 Date 参数使用 GMT 时间格式
- 接口调用全部使用 HTTPS
- 所有 API 参数返回值全部都区分大小写
- 文档中 app_key、app_secret，都指的 `应用密钥`,是同一个值

## 签名算法

转换服务接口，采用 WPS-2 签名算法计算请求签名。签名内容放在请求头中携带

:::tip 说明

> 请先仔细阅读以下签名校验规则，再开始开发，能够显著提高您的开发对接效率 
> 社区讨论：[signature not match](https://solution-community.wps.cn/questions/10010000000003634/10020000000003640)

**标准 sha1 算法结果为一个 40 个字符的字符串，16 进制小写表示的 string。**

- Content-Md5 HTTP Body 中数据的 md5 值十六进制表达方式, 必需小写,如果是 **GET请求** 一律使用 URI 计算 MD5。
  1. `POST`请求，Body计算用的序列化json字符串，计算时用的Body和HTTP发出后的Body数据必须一致（项目中，一般会用到各类封装的HTTP库,不排除某些框架会有自动格式化json，或者加上换行符之类的行为），如果遇到第三方框架库导致Content-Md5计算不对问题，可以利用抓包工具来排查,如wireshark、fiddler等。
  2. `GET`请求，例如: 查询接口  `https://solution.wps.cn/api/developer/v1/tasks/cedc9c82ae0c4127`，那么uri使用： `/api/developer/v1/tasks/cedc9c82ae0c4127`
- Content-Type 一般为: `application/json`
  1. 注意：WebOffice是从请求Header中拿 `Content-Type`。如果传的是 `application/json;charset=utf-8`,就需要使用 `application/json;charset=utf-8`来计算
- DATE 使用 [RFC1123](https://datatracker.ietf.org/doc/html/rfc822#section-5) 时间格式的当前时间, 格式: `Wed, 23 Jan 2022 06:43:08 GMT`
  1. GMT(格林尼治标准时间)，通常我们本地时间是 `东八区时间 UTC/GMT+08:00`。例如早晨 `10：00`，格林尼治标准时间为 `02：00`
  2. 如果仍然遇到时间格式不正确，可以参考相关讨论： [[not a valid datetime or too skewed]](https://solution-community.wps.cn/questions/10010000000006379/10020000000006380)
- Authorization: `"WPS-2:" + APPID + ":" + sha1( AppSecret + Content-Md5 + Content-Type + DATE)`
  1. APP在开发过程的两个关键信息：AppId、AppSecret。可以到[控制台](https://solution.wps.cn/console)去查看。
  2. 更多问题，可以到社区，搜索相关关键字，或者发起提问。

:::

## 接口限流
由于接口的安全保护策略，转换接口设置了QPS限制，具体如下：
:::tip 说明

- **转换接口：**
针对APPID设定QPS限制为10，批量转换超限可能会出现code:30002，message:RateLimiter，建议采用延时调用/队列调用等方式，避免触发接口限流。

- **转换查询接口：**
批量查询超限可能会出现code:30002，message:RateLimiter，建议排除无效轮询，避免触发接口限流。

:::

## 代码实例

### 完整 HTTP 实例

```vb
POST /api/v1/openapi/office/convert/to/pdf
Content-Md5: d41d8cd98f00b204e9800998ecf8427e
Content-Type: application/json
DATE: Wed, 23 Jan 2013 06:43:08 GMT
Authorization: WPS-2:******:ac59dac1460772a04b3a97d7ef78409f28241e3a

{
    "url": "https://***.com/***",
    "filename": "文字文稿.docx"
}***.com/***
```

### 完整 python 实例

```python
from hashlib import sha1

APPID = "******"
APPKEY = b"******"
Content_Md5 = b"d41d8cd98f00b204e9800998ecf8427e"
Content_Type = b"application/json"
Date = b"Wed, 23 Jan 2013 06:43:08 GMT"

signature = sha1(APPKEY+Content_Md5+Content_Type+Date).hexdigest()

print(signature)
# output > 083500176fa3aab58ca2dc962978013b3ca2b6df

Authorization = 'WPS-2:%s:%s' % (APPID, signature)
print(Authorization)
# output > WPS-2:******:083500176fa3aab58ca2dc962978013b3ca2b6df
```