# <接口名称>

## 接口说明

<一句话说明接口用途，面向外部系统开发人员。>

## 前置条件

### 获取 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>` | `<错误说明>` |

## 流程字段说明

### <业务字段分组>

| 字段名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `<字段名>` | `<类型>` | `<是/否/需确认>` | `<说明>` |