add ivyz9k2l
This commit is contained in:
261
docs/IVYZ9K2L_WestDex_API文档.md
Normal file
261
docs/IVYZ9K2L_WestDex_API文档.md
Normal file
@@ -0,0 +1,261 @@
|
||||
# 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=`
|
||||
|
||||
**注意**：实际加密结果会根据密钥和原始数据不同而变化，以上仅为示例格式。
|
||||
|
||||
Reference in New Issue
Block a user