调用方式

# 服务地址
**https://open.eqxiu.cn**
# 接口URL格式

![](/media/202206/2022-06-01_185500_747504.png)

- 1. 为默认前缀
- 2. 代表当前版本
- 3. 代表业务主模块标识
- 4. 代码子模块以及功能

# 通用请求参数
- token：请求令牌，通过令牌接口获得
- secretId：密钥id，在控制台密钥管理处获得
- openId：当前操作人id，它是客户系统中的员工（账号）唯一id

# 返回值格式

- 数据结构
```json
{
	  success:true,
	  code:"200",
	  msg:"",
	  obj:{...},
	  list:{...},
	  map:{...}
}
```

- 字段说明
| **参数** | **参数类型** | **说明** |
| --- | --- | --- |
| success | boolean | 请求成功：true，请求失败：false |
| code | String | 状态码，[参见共公代码](https://hc.eqxiu.cn/doc/18/) |
| msg | String | 异常提示信息 |
| obj | Object | 返回数据节点 |
| list | Array |  |
| map | Object |  |

# 鉴权机制

> 接口请求时需要在后面增加一个 token 参数，token通过请求密钥申请，有效期2小时。token获取方式如下。

## 获取令牌接口（Token）

- **接口描述：**用于生成服务端请求动态凭证，所有服务端请求都必须有token参数。
- **接口地址：**`/api/v1/base/oauth/token`
- **请求方式：**`POST`
- **传参方式：**content-type: application/x-www-form-urlencoded
- **参数列表：**
| **参数名** | **是否必须** | **参数类型** | **说明** |
| --- | --- | --- | --- |
| secretId | 必须 | String | 标识身份一个 SecretId 对应唯一的 SecretKey ，SecretKey 会用来生成请求签名 Signature。获取方式参见 |
| type | 必须 | String | Server |
| timestamp | 必须 | Long | 当前 UNIX 时间戳，可记录发起 API 请求的时间。单位：毫秒，5分钟内有效，例如1620626322562 |
| signatureMethod | 否 | String | 默认为SHA256，当前只支持一种算法（未来会支持国密算法），如果参与签名需要传此参数 |
| signature | 必须 | String | 请求签名，签名算法见下一节内容|

参数直接拼接在url后，或使用x-www-form-urlencoded形式的body参数，不支持form-data。

- **返回值示例：**
```json
{
    success:true,
    code:"200",
    map:{
        token:"32f909e22ba842fe09a192",
        expires:7200,
        type:"server",
        corpId:"ba842fe0baxxxxxxxx842fe0ba842fe0"
    }
}
```

- 返回值说明
| **参数** | **参数类型** | **说明** |
| --- | --- | --- |
| token | String | 目前有效时间为2小时，需要缓存，避免频繁调用获取 access_token 接口导致超出频率限制被拦截 |
| expires | Long | 有效期，单位：秒 |
| type | String | token类型 |
| corpId | String | 归属公司id |

## 参数签名算法
示例：假设URL业务参数为`secretId=38774YX&type=Server&timestamp=1620626322562`
注：
	1、signatureMethod如果参与签名，需要在接口中增加signatureMethod参数
	2、参与生成的signature的参数必须包含请求的所有业务参数，详见示例与示例代码

签名示例代码：
```java
Long timestamp = System.currentTimeMillis();
List<String> paramList = Arrays.asList(secretId, type, timestamp.toString(), secretKey);
Collections.sort(paramList);
String signatureStr = StringUtils.arrayToDelimitedString(paramList.toArray(), "");
String signature = getSHA256Str(signatureStr);
```
[完整代码地址](https://gitee.com/eqxiu-ee/oa_system/blob/master/src/main/java/cn/gson/oasys/controller/eqxiu/ECMPController.java)
注意：排序时是将参数值进行排序运算，非键值对。