一、赋能二手车交易与移动端实时核验
在二手车电商交易、汽车租赁APP以及车主服务小程序等移动互联网场景中，用户体验的核心在于“快”与“准”。当用户上传行驶证信息时，后台系统需要实时确认车辆所有人信息与官方登记记录是否一致，以阻断虚假车源上架或冒名租赁行为。
天远API提供的车辆二要素核验API，凭借其毫秒级的响应速度和官方数据源的权威性，成为此类场景的首选方案。本文将面向Node.js开发者，详细解析如何利用JavaScript的异步非阻塞特性，实现该API代码的高效对接。我们将深入讲解基于Node.jscrypto模块的AES加解密实现，帮助开发者快速构建安全、可靠的车辆信息核验服务。
二、API接口调用示例
本节将展示如何在Node.js环境中实现API的完整调用流程。由于接口涉及严格的AES-128加密机制，我们推荐使用Node.js原生内置的crypto模块来处理安全逻辑，无需引入额外的重量级加密库。
2.1 接口配置概览
- 接口地址：
https://api.tianyuanapi.com/api/v1/QCXGGB2Q - 请求方式：POST
- 安全协议：
- 算法：AES-128-CBC
- 填充：PKCS7 (Node.js默认支持)
- 编码：Base64
- 密钥：16字节 Access Key
- IV：随机生成的16字节向量
2.2 Curl 命令行测试
Bash
curl -X POST "https://api.tianyuanapi.com/api/v1/QCXGGB2Q?t=1737361234567" \ -H "Content-Type: application/json" \ -H "Access-Id: YOUR_ACCESS_ID" \ -d '{ "data": "Base64_Encoded_String_Here" }'2.3 Node.js 完整调用示例
以下代码使用axios发送请求，并包含了完整的加解密工具函数。请确保已安装依赖：npm install axios。
JavaScript
const axios = require('axios'); const crypto = require('crypto'); // 配置信息 const CONFIG = { apiUrl: 'https://api.tianyuanapi.com/api/v1/QCXGGB2Q', accessId: 'YOUR_ACCESS_ID', accessKey: 'YOUR_ACCESS_KEY_16_BYTES' // 必须是16字节长度 }; /** * AES加密工具函数 * 1. 生成随机IV * 2. AES-128-CBC加密 * 3. 拼接 IV + 密文 * 4. 转Base64 */ function encryptData(data, key) { try { const iv = crypto.randomBytes(16); // 生成16字节随机IV const cipher = crypto.createCipheriv('aes-128-cbc', Buffer.from(key), iv); // JSON序列化 const payload = JSON.stringify(data); let encrypted = cipher.update(payload, 'utf8'); encrypted = Buffer.concat([encrypted, cipher.final()]); // 拼接 IV 和 密文 const resultBuffer = Buffer.concat([iv, encrypted]); return resultBuffer.toString('base64'); } catch (error) { console.error('Encryption Failed:', error); return null; } } /** * AES解密工具函数 * 1. Base64解码 * 2. 提取前16字节IV * 3. 解密剩余密文 */ function decryptData(base64Data, key) { try { const buffer = Buffer.from(base64Data, 'base64'); // 提取IV (前16字节) const iv = buffer.slice(0, 16); // 提取密文 (剩余部分) const encryptedText = buffer.slice(16); const decipher = crypto.createDecipheriv('aes-128-cbc', Buffer.from(key), iv); let decrypted = decipher.update(encryptedText); decrypted = Buffer.concat([decrypted, decipher.final()]); return JSON.parse(decrypted.toString()); } catch (error) { console.error('Decryption Failed:', error); return null; } } // 核心业务调用函数 async function verifyVehicle(plateNo, plateType, name) { // 1. 准备请求数据 const requestData = { plate_no: plateNo, carplate_type: plateType, name: name }; // 2. 加密 const encryptedPayload = encryptData(requestData, CONFIG.accessKey); if (!encryptedPayload) return; // 3. 构造请求 const timestamp = Date.now(); const url = `${CONFIG.apiUrl}?t=${timestamp}`; try { console.log('>>> Sending request to 天远API...'); const response = await axios.post(url, { data: encryptedPayload }, { headers: { 'Access-Id': CONFIG.accessId, 'Content-Type': 'application/json' }, timeout: 5000 }); const resBody = response.data; console.log('API Response Status:', resBody.code, resBody.message); // 4. 处理响应与解密 if (resBody.data) { const result = decryptData(resBody.data, CONFIG.accessKey); if (result) { if (result.verify_code === 1) { console.log('✅ 核验通过：姓名与登记信息一致'); } else { console.log('❌ 核验失败：信息不匹配'); } } } } catch (error) { console.error('API Request Error:', error.message); } } // 执行调用 verifyVehicle('浙A12345', '02', '张三');三、核心数据结构解析
在Node.js全栈开发中，通常需要处理JSON对象与Buffer流的转换。理解天远API的数据包裹结构对于正确解析响应至关重要。
- 外部信封 (Envelope)：
- API HTTP响应直接返回的JSON对象。
- 包含
code(Int) 和message(String) 用于前端展示或日志记录。 - 关键字段
data是一个Base64字符串，代表加密后的负载。
- 内部负载 (Payload)：
- 开发者必须对
data进行Base64 Decode -> Split IV -> AES Decrypt操作。 - 解密后的内容才是包含
verify_code的真实业务JSON对象。
- 开发者必须对
数据流向图解：
Plaintext
[Client] JSON Params -> Encrypt -> Base64 -> HTTP Request ⬇️ [Server API] ⬇️ [Client] Decrypt JSON <- AES Decrypt <- Base64 <- HTTP Response四、字段详解
以下表格列出了对接过程中需要用到的字段定义，请确保Node.js对象属性名与下表完全一致（区分大小写）。
4.1 业务请求字段 (需加密)
| 字段名 | 类型 | 必填 | 含义 | 示例/说明 |
|---|---|---|---|---|
| plate_no | String | 是 | 车牌号 | 如 “京A88888” |
| carplate_type | String | 是 | 号牌类型 | 02=小型汽车，01=大型汽车 |
| name | String | 是 | 车辆所有人 | 必须与行驶证一致的姓名 |
4.2 响应字段说明
| 分类 | 字段名 | 类型 | 含义 | 说明 |
|---|---|---|---|---|
| 外层 | code | Number | 状态码 | 业务请求的返回状态 |
| 外层 | transaction_id | String | 流水号 | 建议存储至数据库，用于对账 |
| 外层 | data | String | 密文数据 | 需解密处理 |
| 内层 | verify_code | Number | 核验结果 | 1：一致 |
| 0：不一致 |
五、应用价值分析
对于使用Node.js构建的各类即时应用，接入天远API能显著提升业务流程的自动化水平：
二手车C2C交易平台
在买家查询车辆报告或卖家发布车源时，通过API实时验证车主身份。这不仅能防止虚假车源干扰平台秩序，还能作为“官方认证”标签，增加买家信任度，提升成交转化率。
汽车租赁小程序
用户在微信/支付宝小程序租赁车辆时，通过Node.js后端快速调用API核验用户姓名与绑定车辆是否匹配，实现“免押金”或“自助取还车”风控闭环，无需人工介入审核。
智慧停车与物业管理
在高端社区或商业园区的车辆门禁系统中，通过API校验长期租赁车位的车主身份真实性，防止车位私下转租或违规占用，优化停车资源管理。
六、总结
本文详细阐述了Node.js环境下对接车辆二要素核验API的最佳实践。通过利用Node.js强大的crypto模块，开发者可以轻松处理天远API所要求的AES-128加密通信，确保数据在传输过程中的绝对安全。
无论是打造高效的二手车交易平台，还是构建便捷的汽车金融SaaS系统，掌握这套API代码的接入流程，都能帮助企业快速具备官方级的车辆数据核验能力，从而在激烈的市场竞争中构建起坚实的风控壁垒。开发者在实际集成中，应注意密钥的环境变量管理，避免硬编码带来的安全隐患。
