165 lines
3.5 KiB
Markdown
165 lines
3.5 KiB
Markdown
|
# <接口名称>
|
||
|
|
|
||
|
|
## 接口说明
|
||
|
|
|
||
|
|
<一句话说明接口用途，面向外部系统开发人员。>
|
||
|
|
|
||
|
|
## 前置条件
|
||
|
|
|
||
|
|
### 获取 access_token
|
||
|
|
|
||
|
|
E10 OpenAPI 使用 OAuth2 code 换取 access_token 的方式。业务接口调用时，`access_token` 作为请求体参数传入，不通过 HTTP `Authorization` Header 传入。
|
||
|
|
|
||
|
|
#### Step 1: 获取 code
|
||
|
|
|
||
|
|
- **URL**: `POST https://<E10_BASE>/papi/openapi/oauth2/authorize`
|
||
|
|
- **Content-Type**: `application/json`
|
||
|
|
|
||
|
|
| 参数 | 必填 | 类型 | 说明 |
|
||
|
|
|---|---|---|---|
|
||
|
|
| `corpid` | 是 | String | 企业 corpId。 |
|
||
|
|
| `response_type` | 是 | String | 固定为 `code`。 |
|
||
|
|
| `state` | 是 | String | 自定义参数，建议使用随机字符串。 |
|
||
|
|
|
||
|
|
请求示例：
|
||
|
|
|
||
|
|
```json
|
||
|
|
{
|
||
|
|
"corpid": "<CORP_ID>",
|
||
|
|
"response_type": "code",
|
||
|
|
"state": "state001"
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
响应示例：
|
||
|
|
|
||
|
|
```json
|
||
|
|
{
|
||
|
|
"errcode": "0",
|
||
|
|
"code": "<CODE>"
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
#### Step 2: code 换 access_token
|
||
|
|
|
||
|
|
- **URL**: `POST https://<E10_BASE>/papi/openapi/oauth2/access_token`
|
||
|
|
- **Content-Type**: `application/json`
|
||
|
|
|
||
|
|
| 参数 | 必填 | 类型 | 说明 |
|
||
|
|
|---|---|---|---|
|
||
|
|
| `app_key` | 是 | String | 应用 key。 |
|
||
|
|
| `app_secret` | 是 | String | 应用密钥。 |
|
||
|
|
| `grant_type` | 是 | String | 固定为 `authorization_code`。 |
|
||
|
|
| `code` | 是 | String | 上一步获取的 code。 |
|
||
|
|
|
||
|
|
请求示例：
|
||
|
|
|
||
|
|
```json
|
||
|
|
{
|
||
|
|
"app_key": "<APP_KEY>",
|
||
|
|
"app_secret": "<APP_SECRET>",
|
||
|
|
"grant_type": "authorization_code",
|
||
|
|
"code": "<CODE>"
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
响应示例：
|
||
|
|
|
||
|
|
```json
|
||
|
|
{
|
||
|
|
"errcode": "0",
|
||
|
|
"accessToken": "<ACCESS_TOKEN>",
|
||
|
|
"refreshToken": "<REFRESH_TOKEN>",
|
||
|
|
"expires_in": 7200
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
## 身份标识转换
|
||
|
|
|
||
|
|
外部系统通常不持有 E10 内部用户 ID 或部门 ID。调用接口时应通过外部稳定标识进行转换。
|
||
|
|
|
||
|
|
| 标识类型 | 可选值 | 说明 |
|
||
|
|
|---|---|---|
|
||
|
|
| `userType` | `JOB_NUM` / `EMAIL` / `MOBILE` / `idNos` / `loginID` / `account` | 用于指定人员标识类型。推荐优先使用工号。 |
|
||
|
|
| `deptType` | `DEPT_CODE` / `DEPT_NAME` | 用于指定部门标识类型。推荐优先使用部门编号。 |
|
||
|
|
|
||
|
|
表单中的人员、部门等关联字段应通过 `dataOptions` 传值，并指定相应的 `type`、`userType` 或 `deptType`。
|
||
|
|
|
||
|
|
## 请求信息
|
||
|
|
|
||
|
|
- **URL**: `POST https://<E10_BASE>/papi/openapi/<PATH>`
|
||
|
|
- **Content-Type**: `application/json`
|
||
|
|
|
||
|
|
## 请求参数
|
||
|
|
|
||
|
|
| 参数名 | 类型 | 必填 | 说明 |
|
||
|
|
|---|---|---|---|
|
||
|
|
| `access_token` | String | 是 | 接口调用凭证，请求体参数。 |
|
||
|
|
| `<PARAM>` | `<TYPE>` | `<是/否/需确认>` | `<说明>` |
|
||
|
|
|
||
|
|
## 请求示例
|
||
|
|
|
||
|
|
### 最小请求
|
||
|
|
|
||
|
|
```bash
|
||
|
|
curl -X POST "https://<E10_BASE>/papi/openapi/<PATH>" \
|
||
|
|
-H "Content-Type: application/json" \
|
||
|
|
-d '{
|
||
|
|
"access_token": "<ACCESS_TOKEN>"
|
||
|
|
}'
|
||
|
|
```
|
||
|
|
|
||
|
|
### 完整请求
|
||
|
|
|
||
|
|
```bash
|
||
|
|
curl -X POST "https://<E10_BASE>/papi/openapi/<PATH>" \
|
||
|
|
-H "Content-Type: application/json" \
|
||
|
|
-d '{
|
||
|
|
"access_token": "<ACCESS_TOKEN>",
|
||
|
|
"userType": "JOB_NUM",
|
||
|
|
"deptType": "DEPT_CODE"
|
||
|
|
}'
|
||
|
|
```
|
||
|
|
|
||
|
|
## 响应参数
|
||
|
|
|
||
|
|
| 参数名 | 类型 | 说明 |
|
||
|
|
|---|---|---|
|
||
|
|
| `errcode` | String | 返回码，`0` 表示成功。 |
|
||
|
|
| `<FIELD>` | `<TYPE>` | `<说明>` |
|
||
|
|
|
||
|
|
## 响应示例
|
||
|
|
|
||
|
|
### 成功
|
||
|
|
|
||
|
|
```json
|
||
|
|
{
|
||
|
|
"errcode": "0",
|
||
|
|
"errmsg": "success"
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
### 失败
|
||
|
|
|
||
|
|
```json
|
||
|
|
{
|
||
|
|
"errcode": "<ERROR_CODE>",
|
||
|
|
"errmsg": "<ERROR_MESSAGE>"
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
## 错误码
|
||
|
|
|
||
|
|
| 错误码 | 说明 |
|
||
|
|
|---|---|
|
||
|
|
| `0` | 成功。 |
|
||
|
|
| `<ERROR_CODE>` | `<错误说明>` |
|
||
|
|
|
||
|
|
## 流程字段说明
|
||
|
|
|
||
|
|
### <业务字段分组>
|
||
|
|
|
||
|
|
| 字段名 | 类型 | 必填 | 说明 |
|
||
|
|
|---|---|---|---|
|
||
|
|
| `<字段名>` | `<类型>` | `<是/否/需确认>` | `<说明>` |
|