tyapi-server/docs/IVYZ9K2L_WestDex_API文档.md

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

请求体

请求体结构

{
  "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 示例

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 示例

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));

响应格式

成功响应

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

错误响应

{
  "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，内容如下：

{
  "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. 前置脚本（用于生成时间戳）

在"前置脚本"中添加：

// 生成毫秒级时间戳
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=

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