前端全栈必读：天远车辆二要素核验API接口调用代码流程与Node.js实战

天远数科
0 阅读6分钟

一、赋能二手车交易与移动端实时核验

在二手车电商交易、汽车租赁APP以及车主服务小程序等移动互联网场景中，用户体验的核心在于“快”与“准”。当用户上传行驶证信息时，后台系统需要实时确认车辆所有人信息与官方登记记录是否一致，以阻断虚假车源上架或冒名租赁行为。

天远API 提供的车辆二要素核验API，凭借其毫秒级的响应速度和官方数据源的权威性，成为此类场景的首选方案。本文将面向Node.js开发者，详细解析如何利用JavaScript的异步非阻塞特性，实现该API代码的高效对接。我们将深入讲解基于Node.js crypto 模块的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 的数据包裹结构对于正确解析响应至关重要。

  1. 外部信封 (Envelope) ：

    • API HTTP响应直接返回的JSON对象。
    • 包含 code (Int) 和 message (String) 用于前端展示或日志记录。
    • 关键字段 data 是一个Base64字符串，代表加密后的负载。

  2. 内部负载 (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_noString是车牌号如 "京A88888"
carplate_typeString是号牌类型02=小型汽车，01=大型汽车
nameString是车辆所有人必须与行驶证一致的姓名

4.2 响应字段说明

分类字段名类型含义说明
外层codeNumber状态码业务请求的返回状态
外层transaction_idString流水号建议存储至数据库，用于对账
外层dataString密文数据需解密处理
内层verify_codeNumber核验结果1：一致
0：不一致

五、应用价值分析

对于使用Node.js构建的各类即时应用，接入天远API 能显著提升业务流程的自动化水平：

  1. 二手车C2C交易平台

    在买家查询车辆报告或卖家发布车源时，通过API实时验证车主身份。这不仅能防止虚假车源干扰平台秩序，还能作为“官方认证”标签，增加买家信任度，提升成交转化率。

  2. 汽车租赁小程序

    用户在微信/支付宝小程序租赁车辆时，通过Node.js后端快速调用API核验用户姓名与绑定车辆是否匹配，实现“免押金”或“自助取还车”风控闭环，无需人工介入审核。

  3. 智慧停车与物业管理

    在高端社区或商业园区的车辆门禁系统中，通过API校验长期租赁车位的车主身份真实性，防止车位私下转租或违规占用，优化停车资源管理。

六、总结

本文详细阐述了Node.js环境下对接车辆二要素核验API的最佳实践。通过利用Node.js强大的 crypto 模块，开发者可以轻松处理天远API 所要求的AES-128加密通信，确保数据在传输过程中的绝对安全。

无论是打造高效的二手车交易平台，还是构建便捷的汽车金融SaaS系统，掌握这套API代码的接入流程，都能帮助企业快速具备官方级的车辆数据核验能力，从而在激烈的市场竞争中构建起坚实的风控壁垒。开发者在实际集成中，应注意密钥的环境变量管理，避免硬编码带来的安全隐患。

avatar
文章
阅读
粉丝