一、 构建实时响应的智能化车况查询应用
在微信小程序开发、H5二手车交易平台 以及即时报价系统等高频交互场景中，用户对数据的实时性和响应速度有着极高的要求。车辆出险查询API，作为连接用户终端与底层数据中心的纽带，能够以毫秒级的速度返回车辆的维修保养与出险详情。
本文将作为一份面向 JavaScript/TypeScript 开发者的技术指南，详细解读如何利用 Node.js 高效接入天远API，处理 AES 加密数据，并将解析后的车况评级、碰撞记录等核心数据无缝集成到您的 Web 应用或小程序后端中，助力企业快速构建轻量级、高性能的车辆数据服务。
二、 API接口调用示例（Node.js版）
本节演示如何在 Node.js 环境中（支持 CommonJS 与 ES Module）完成接口对接。我们将使用原生 crypto 模块处理加密，并使用流行的 axios 库发送请求。
1. 接入前准备
- 接口地址 ：
https://api.tianyuanapi.com/api/v1/QCXGP00W - 加密算法：AES-128-CBC (PKCS7 Padding) 1
- 环境要求：Node.js >= 12.0
- 依赖库 ：
npm install axios
2. Curl 命令行快速验证
在编写代码前，先通过 Curl 确认 Access-Id 是否有效。
Bash
jsx
# data 为加密后的 Base64 字符串
curl -X POST "https://api.tianyuanapi.com/api/v1/QCXGP00W?t=1720000000000" \
-H "Content-Type: application/json" \
-H "Access-Id: 您的ACCESS_ID" \
-d '{"data": "U2FsdGVkX1+..."}'3. Node.js (Async/Await) 完整调用示例
此代码展示了现代化的异步调用方式，并将加密/解密逻辑封装为通用工具函数。
JavaScript
jsx
const axios = require('axios');
const crypto = require('crypto');
// --- 配置常量 ---
const CONFIG = {
apiUrl: 'https://api.tianyuanapi.com/api/v1/QCXGP00W',
accessId: '您的Access-Id',
accessKey: '您的Access-Key', // 16位 16进制字符串
};
/**
* AES-128-CBC 加密工具函数
* @param {Object} data - 待加密的JSON对象
* @param {String} key - 16位密钥
*/
function encryptData(data, key) {
// 1. 生成16字节随机IV
const iv = crypto.randomBytes(16);
// 2. 创建加密实例
const cipher = crypto.createCipheriv('aes-128-cbc', Buffer.from(key), iv);
// 3. 加密数据 (JSON.stringify后加密)
let encrypted = cipher.update(JSON.stringify(data), 'utf8', 'base64');
encrypted += cipher.final('base64');
// 4. 拼接 IV 和 密文 (注意：此处仅为逻辑演示，具体拼接方式需参考官方文档)
// 假设官方要求是将IV(hex或bytes)与密文结合再Base64，此处用占位符简化
// 实际开发请参考文档：IV + CipherText -> Base64
return "ENCRYPTED_BASE64_PLACEHOLDER_WITH_IV";
}
/**
* AES-128-CBC 解密工具函数
* @param {String} encryptedBase64 - 接口返回的加密字符串
* @param {String} key - 16位密钥
*/
function decryptData(encryptedBase64, key) {
// 占位符：实际需从Base64中提取IV，再解密剩余部分
// const iv = ...
// const decipher = crypto.createDecipheriv(...)
// return JSON.parse(decrypted);
// 模拟返回解密后的对象
return {
ckdlpc: { type1: 0, type2: 2 }, // 车况排查
clxx: { brandName: "特斯拉", isFire: 0 } // 车辆信息
};
}
/**
* 主业务逻辑：查询车辆出险记录
*/
async function queryVehicleAccident() {
try {
const timestamp = new Date().getTime();
const requestUrl = `${CONFIG.apiUrl}?t=${timestamp}`;
// 1. 组装业务参数
const payload = {
vin_code: "LNVxxxxxx", // 车架号
plate_no: "粤Bxxxxx", // 车牌号 (可选)
return_url: "https://api.your-app.com/callback", // 回调地址
vlphoto_data: "data:image/jpeg;base64,..." // 行驶证图片Base64
};
// 2. 加密参数
console.log('[Step 1] 正在加密请求参数...');
const encryptedData = encryptData(payload, CONFIG.accessKey);
// 3. 发送请求
console.log(`[Step 2] 请求天远API: ${requestUrl}`);
const response = await axios.post(requestUrl, {
data: encryptedData
}, {
headers: {
'Content-Type': 'application/json',
'Access-Id': CONFIG.accessId
},
timeout: 10000 // 10秒超时
});
// 4. 处理响应
const resBody = response.data;
if (resBody.code && resBody.data) {
console.log('[Step 3] 接口调用成功，正在解密...');
const result = decryptData(resBody.data, CONFIG.accessKey);
console.log('=== 车辆出险报告 ===');
console.log('车辆品牌:', result.clxx.brandName);
console.log('骨架状态:', result.ckdlpc.type1 === 0 ? '正常' : '异常');
console.log('完整数据:', JSON.stringify(result, null, 2));
} else {
console.error('接口报错:', resBody.message);
}
} catch (error) {
if (error.response) {
console.error('HTTP错误:', error.response.status);
} else {
console.error('运行异常:', error.message);
}
}
}
// 执行调用
queryVehicleAccident();三、 核心数据结构解析
在 Node.js 中，API 返回的 JSON 数据可以直接映射为 JavaScript 对象。天远API 的返回数据解密后，结构清晰，非常适合前端直接渲染。
- ckdlpc (排查概览)：这是车辆的"体检报告"，包含骨架、外观、发动机等维度的状态码 2。
- clxx (车辆画像)：车辆的静态属性，包含品牌、车系、出厂日期等，用于确认车辆身份 3。
- pzlsmx (碰撞时间轴)：一个数组结构，按时间顺序列出所有的维修记录和金额，适合在前端渲染为时间轴 4。
- tjxx (统计看板)：包含了事故总次数、总金额等聚合数据，适合在管理后台 Dashboard 中直接展示 5。
四、 字段详解（JSON 结构对照）
以下表格按 JSON 对象层级分类，帮助前端或 Node.js 开发者快速定义 TypeScript 接口或 PropTypes。
1. clxx (Vehicle Info Object)
车辆的基础身份信息，通常用于头部展示。
| 字段名 (Key) | 类型 | 含义 | 前端展示建议 |
|---|---|---|---|
| brandName | String | 品牌名称 | 直接展示，如 "梅赛德斯-奔驰" |
| regDate | String | 上牌日期 | 建议格式化为 "YYYY年MM月" |
| properties | String | 使用性质 | 重点高亮，特别是"营运"类车辆 |
| warning | Number | 风险警示 | 1为高风险，建议红色Tag显示 |
| ownerType | String | 车主类型 | 区分 "个人" 或 "企业" 户 |
2. ckdlpc (Condition Check Object)
核心部件状态排查，状态码：0=正常, 1=不确定, 2=疑似, 3=维保异常, 4=碰撞异常。
| 字段名 (Key) | 类型 | 含义 | 前端展示建议 |
|---|---|---|---|
| type1 | Int | 骨架 | 核心指标，异常应弹窗警告 |
| type5 | Int | 水淹 | 0为正常，非0建议展示详细报告 |
| type4 | Int | 火烧 | 0为正常，非0需重点提示 |
| type6 | Int | 气囊 | 气囊弹出通常对应大额事故 |
3. pzlsmx (Repair Details Object)
维修明细记录。
| 字段名 (Key) | 类型 | 含义 | 说明 |
|---|---|---|---|
| serviceSumMoney | String | 维修总额 | 单位：分，需除以100转换为元 |
| serviceSumCount | String | 维修次数 | 历史进厂维修的总次数 |
| records | Array | 记录列表 | 包含 date (日期) 和 result (具体维修项) |
五、 应用价值分析
利用 Node.js 的事件驱动特性，结合 天远API，开发者可以构建出极具竞争力的应用场景：
-
微信小程序查车报告：
利用 Node.js 作为 BFF (Backend for Frontend) 层，直接透传 API 数据。用户上传行驶证照片后，后台实时调用接口，3秒内将包含 ckdlpc（车况排查）的可视化报告推送至小程序前端，提升用户留存率。
-
二手车直播实时检测工具：
在二手车直播带货中，通过集成API，主播输入车架号即可在直播画面上实时弹窗显示车辆的 totalAmount（维修总金额）和 claimCount（出险次数），增加直播间的信任度和互动性。
-
网约车入驻自动审核：
网约车平台可使用 Node.js 脚本批量跑批，调用 API 检查 properties 字段。若发现注册车辆历史上有"全损注销"或"火烧"记录（isFire=1），系统自动拒绝入驻，极大降低平台运营风险。
-
C端个人买车助手：
开发面向个人买家的 H5 应用，重点解析 clfwzj（损失方位总结），用 3D 模型图展示车辆受损部位（如左前翼子板受损），让不懂车的用户也能直观读懂车况。
六、 总结
在 Web 开发技术日新月异的今天，数据接口的易用性与响应速度决定了产品的用户体验。天远车辆出险查询API 提供了标准的 RESTful 接口与 JSON 数据格式，天然契合 Node.js 与 JavaScript 技术栈。
对于前端全栈开发者而言，只需关注 data 字段的加密解密流程，即可轻松获取原本需要专业评估师才能判断的深度车况数据。建议开发者在对接时，充分利用 Node.js 的异步特性处理网络请求，以实现最高吞吐量的查询服务。