# IVYZ9K2L - 身份认证三要素(人脸图像版) WestDex API 文档

## 接口信息

- **接口名称**: 身份认证三要素(人脸图像版)
- **接口代码**: IVYZ9K2L
- **WestDex API Code**: `idCardThreeElements`
- **请求方式**: POST
- **Content-Type**: application/json

## 请求URL

```
https://apimaster.westdex.com.cn/api/invoke/{secret_id}/{api_code}?timestamp={timestamp}
```

### URL 参数说明

| 参数 | 说明 | 示例值 |
|------|------|--------|
| secret_id | 西部数据 SecretID（从配置获取） | `449159` |
| api_code | API代码 | `idCardThreeElements` |
| timestamp | 毫秒级时间戳（URL参数） | `1713421668375` |

### 完整URL示例

```
https://apimaster.westdex.com.cn/api/invoke/449159/idCardThreeElements?timestamp=1713421668375
```

## 请求头

```
Content-Type: application/json
```

## 请求体

### 请求体结构

```json
{
  "data": {
    "timeStamp": "1713421668375",
    "customNumber": "449159",
    "xM": "fU4B3fR3Dw+UkHNkFsHIjA==",
    "gMSFZHM": "qL3GFeI7JO8txKDT25hjuXe5IhnGJ00Jg8+YYbnQ6wg="
  },
  "photoData": "Qk3OlwAAAAAAADYAAAAoAAAAZgAAAH4AAAABABgAAA..."
}
```

### 参数说明

#### data 对象（必填）

| 参数名 | 类型 | 必填 | 说明 | 示例值 |
|--------|------|------|------|--------|
| timeStamp | string | 是 | 毫秒级时间戳，与URL参数中的timestamp一致 | `"1713421668375"` |
| customNumber | string | 是 | 自定义编号，使用配置中的 secret_id | `"449159"` |
| xM | string | 是 | 加密后的姓名（使用AES加密，密钥为配置中的key） | `"fU4B3fR3Dw+UkHNkFsHIjA=="` |
| gMSFZHM | string | 是 | 加密后的身份证号（使用AES加密，密钥为配置中的key） | `"qL3GFeI7JO8txKDT25hjuXe5IhnGJ00Jg8+YYbnQ6wg="` |

#### photoData（必填）

| 参数名 | 类型 | 必填 | 说明 | 示例值 |
|--------|------|------|------|--------|
| photoData | string | 是 | Base64编码的人脸图片数据，仅支持JPG、BMP、PNG格式 | `"Qk3OlwAAAAAAADYAAAAoAAAAZgAAAH4AAAABABgAAA..."` |

## 加密说明

### 姓名和身份证号加密

使用 AES-ECB 模式加密，密钥为配置中的 `key`（示例：`121a1e41fc1690dd6b90afbcacd80cf4`）

**加密步骤**：
1. 使用密钥生成 AES 密钥
2. 使用 AES-ECB 模式加密原始数据
3. 将加密结果进行 Base64 编码

**示例**：
- 原始姓名：`"张三"`
- 加密后：`"fU4B3fR3Dw+UkHNkFsHIjA=="`

## 完整请求示例

### cURL 示例

```bash
curl -X POST "https://apimaster.westdex.com.cn/api/invoke/449159/idCardThreeElements?timestamp=1713421668375" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "timeStamp": "1713421668375",
      "customNumber": "449159",
      "xM": "fU4B3fR3Dw+UkHNkFsHIjA==",
      "gMSFZHM": "qL3GFeI7JO8txKDT25hjuXe5IhnGJ00Jg8+YYbnQ6wg="
    },
    "photoData": "Qk3OlwAAAAAAADYAAAAoAAAAZgAAAH4AAAABABgAAA..."
  }'
```

### JavaScript 示例

```javascript
const timestamp = Date.now().toString();
const url = `https://apimaster.westdex.com.cn/api/invoke/449159/idCardThreeElements?timestamp=${timestamp}`;

const requestBody = {
  data: {
    timeStamp: timestamp,
    customNumber: "449159",
    xM: "fU4B3fR3Dw+UkHNkFsHIjA==",  // 加密后的姓名
    gMSFZHM: "qL3GFeI7JO8txKDT25hjuXe5IhnGJ00Jg8+YYbnQ6wg="  // 加密后的身份证号
  },
  photoData: "Qk3OlwAAAAAAADYAAAAoAAAAZgAAAH4AAAABABgAAA..."  // Base64图片数据
};

fetch(url, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(requestBody)
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));
```

## 响应格式

### 成功响应

```json
{
  "code": "00000",
  "message": "成功",
  "data": "加密后的响应数据（需要解密）",
  "id": "响应ID",
  "error_code": null,
  "reason": ""
}
```

### 错误响应

```json
{
  "code": "错误码",
  "message": "错误信息",
  "data": "加密后的错误数据（需要解密）",
  "id": "响应ID",
  "error_code": 错误码,
  "reason": "错误原因"
}
```

### 响应状态码说明

| 状态码 | 说明 |
|--------|------|
| `00000` | 成功 |
| `200` | 成功 |
| `0` | 成功 |
| 其他 | 失败 |

## 响应数据解密

响应中的 `data` 字段是加密的，需要使用相同的密钥进行解密：

**解密步骤**：
1. 使用配置中的 `key` 作为密钥
2. 对 `data` 字段进行 Base64 解码
3. 使用 AES-ECB 模式解密
4. 得到原始 JSON 字符串

## Apifox 配置步骤

### 1. 创建新请求

- 方法：`POST`
- URL：`https://apimaster.westdex.com.cn/api/invoke/449159/idCardThreeElements`

### 2. 设置URL参数

在"Params"标签页添加：
- `timestamp`: `{{$timestamp}}` （使用Apifox变量生成当前时间戳）

### 3. 设置请求头

在"Headers"标签页添加：
- `Content-Type`: `application/json`

### 4. 设置请求体

在"Body"标签页选择 `raw` 类型，格式选择 `JSON`，内容如下：

```json
{
  "data": {
    "timeStamp": "{{$timestamp}}",
    "customNumber": "449159",
    "xM": "fU4B3fR3Dw+UkHNkFsHIjA==",
    "gMSFZHM": "qL3GFeI7JO8txKDT25hjuXe5IhnGJ00Jg8+YYbnQ6wg="
  },
  "photoData": "Qk3OlwAAAAAAADYAAAAoAAAAZgAAAH4AAAABABgAAA..."
}
```

### 5. 配置环境变量（可选）

在Apifox中创建环境变量：
- `westdex_secret_id`: `449159`
- `westdex_key`: `121a1e41fc1690dd6b90afbcacd80cf4`
- `westdex_url`: `https://apimaster.westdex.com.cn/api/invoke`

然后在URL中使用：`{{westdex_url}}/{{westdex_secret_id}}/idCardThreeElements?timestamp={{$timestamp}}`

### 6. 前置脚本（用于生成时间戳）

在"前置脚本"中添加：

```javascript
// 生成毫秒级时间戳
pm.environment.set("timestamp", Date.now().toString());
```

然后在URL参数和请求体中使用 `{{timestamp}}`

## 注意事项

1. **时间戳同步**：URL参数中的 `timestamp` 和请求体 `data.timeStamp` 必须一致
2. **加密密钥**：姓名和身份证号必须使用配置中的 `key` 进行加密
3. **图片格式**：`photoData` 必须是纯Base64字符串（不包含 `data:image/xxx;base64,` 前缀）
4. **图片格式限制**：仅支持 JPG、BMP、PNG 三种格式
5. **请求超时**：建议设置60秒超时时间
6. **响应解密**：成功响应中的 `data` 字段需要解密后才能查看实际内容

## 配置信息

根据项目配置文件，当前使用的配置为：

- **URL**: `https://apimaster.westdex.com.cn/api/invoke`
- **Key**: `121a1e41fc1690dd6b90afbcacd80cf4`
- **SecretID**: `449159`
- **SecretSecondID**: `296804`

## 测试数据示例

### 原始数据
- 姓名：`张三`
- 身份证号：`110101199001011234`
- 人脸图片：需要转换为Base64格式

### 加密后的数据（示例）
- 加密姓名：`fU4B3fR3Dw+UkHNkFsHIjA==`
- 加密身份证号：`qL3GFeI7JO8txKDT25hjuXe5IhnGJ00Jg8+YYbnQ6wg=`

**注意**：实际加密结果会根据密钥和原始数据不同而变化，以上仅为示例格式。