262 lines
6.8 KiB
Markdown
262 lines
6.8 KiB
Markdown
# 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=`
|
||
|
||
**注意**：实际加密结果会根据密钥和原始数据不同而变化，以上仅为示例格式。
|
||
|