BFF层必备实战：天远全能入职背调报告API接口调用代码流程详解

天远API
59 阅读6分钟

一、 构建实时高效的灵活用工风控体系

在灵活用工平台（如网约车、外卖配送）、互联网蓝领招聘以及房屋租赁风控等高频、高并发场景中，对候选人或用户的背景核验要求极高的实时性与准确性。全能入职背调报告API作为一款聚合型数据接口，能够在毫秒级时间内返回包含身份、学历、司法、借贷及社会不良记录在内的全维度报告。

天远API通过标准化的HTTP服务，完美契合Node.js的事件驱动与非阻塞I/O特性。本文将面向前端及Node.js服务端开发者，深入剖析该API的接入流程。我们将重点解读如何处理其复杂的异步“组合包”数据结构，解析核心字段含义，帮助开发者在BFF层或Serverless函数中快速集成天远API，实现轻量级、低延迟的人员风险筛查。

二、 API接口调用示例（Node.js版）

本接口支持POST请求，数据采用JSON格式交互。在Node.js环境中，推荐使用 axios 或 node-fetch 进行调用。

1. 接口技术参数

  • 接口地址：https://api.tianyuanapi.com/api/v1/COMBQN12?t=13位时间戳
  • 请求方式：POST
  • 参数传递：业务参数需封装在 data 字段中（Base64编码后的加密字符串）。
  • 响应格式：JSON组合包结构。

2. Curl 命令行测试

Bash

curl -X POST "<https://api.tianyuanapi.com/api/v1/COMBQN12?t=1715068800000>" \
-H "Content-Type: application/json" \
-d '{
    "data": "eyJhdXRob3JpemVkIjoiMSIsIm5hbWUiOiLnjovkuoQiLCJpZF9jYXJkIjoiMTEwMTAxMTk5MDAxMDEwMTIzIiwiYm9iaWxlX25vIjoiMTM5MDAwMDAwMDAifQ==" 
}'

3. Node.js (Async/Await) 调用示例

以下代码展示了基于 axios 的完整调用流程，包含加密占位与错误处理，适用于Koa、Express或NestJS框架。

JavaScript

const axios = require('axios');
const crypto = require('crypto'); // 用于加密实现

// 1. 配置API基础信息
const API_CONFIG = {
    url: '<https://api.tianyuanapi.com/api/v1/COMBQN12>',
    timeout: 5000
};

/**
 * 模拟加密函数
 * 实际接入时请替换为天远API提供的AES/RSA加密逻辑
 */
function encryptPayload(payload) {
    const jsonStr = JSON.stringify(payload);
    // 假设此处执行了加密操作
    // const encrypted = aesEncrypt(jsonStr, secretKey);
    // 返回Base64字符串
    return Buffer.from(jsonStr).toString('base64');
}

/**
 * 获取背调报告主函数
 */
async function fetchBackgroundReport(userInfo) {
    const { name, idCard, mobile } = userInfo;
    const timestamp = Date.now();

    // 2. 构建请求体
    const rawPayload = {
        authorized: "1",      // 必须参数：0-未授权 1-已授权 name: name,
        id_card: idCard,
        mobile_no: mobile
    };

    try {
        const encryptedData = encryptPayload(rawPayload);
        
        // 3. 发送POST请求
        const response = await axios.post(`${API_CONFIG.url}?t=${timestamp}`, {
            data: encryptedData // 
        }, {
            headers: { 'Content-Type': 'application/json' },
            timeout: API_CONFIG.timeout
        });

        const result = response.data;

        // 4. 处理组合包响应
        if (result && result.responses) {
            console.log('✅ 背调报告获取成功');
            return parseReportData(result.responses);
        } else {
            console.error('❌ API调用异常:', result);
            return null;
        }

    } catch (error) {
        console.error('❌ 网络或系统错误:', error.message);
        throw error;
    }
}

/**
 * 解析子产品数据工具函数
 */
function parseReportData(responses) {
    const reportSummary = {};

    responses.forEach(item => {
        // 判断子产品调用状态 if (!item.success) {
            console.warn(`子产品 ${item.api_code} 查询失败: ${item.error}`);
            return;
        }

        const data = item.data;

        // 根据 api_code 映射数据 switch (item.api_code) {
            case 'JRZQ09J8': // 收入评估(社保评级)
                reportSummary.incomeLevel = data.level; // break;
            case 'IVYZ81NC': // 婚姻状况
                reportSummary.maritalStatus = data.op_type_desc; // [cite: 10]
                break;
            case 'FLXGDEA9': // 公安不良
                reportSummary.securityRisk = data.level; // break;
            case 'FLXG7E8F': // 司法涉诉
                // 提取案件总数
                reportSummary.legalCases = data.judicial_data?.count?.count_total || 0; // [cite: 22, 49]
                break;
            default:
                break;
        }
    });

    return reportSummary;
}

// 执行测试
(async () => {
    const candidate = {
        name: "李四",
        idCard: "110101199003071234",
        mobile: "13900000000"
    };
    
    const report = await fetchBackgroundReport(candidate);
    console.log('解析后的报告摘要:', report);
})();

三、核心数据结构解析

对于JavaScript开发者来说，API返回的JSON结构非常直观。核心在于理解 responses 数组的“容器”概念。

数据层级说明：

  • Root Level: 包含 responses 数组 。

  • Response Item: 数组中的每个对象代表一个独立的查询维度。

    • api_code (String): 区分是查学历、查案底还是查征信 。
    • data (Object): 该维度下的具体业务数据（可能包含嵌套对象或数组） 。
    • success (Boolean): 该特定维度是否查询成功，便于前端做降级展示 。

四、 字段详解

以下表格列出了Node.js开发中常需处理的高频字段，特别是针对社会风险与经济画像的模块。

1. 公安不良人员名单 (FLXGDEA9)

这是风控最核心的模块，用于“一票否决”。

字段名类型含义详细说明
levelstring风险等级/类型返回具体代码 。

0: 正常人员 A: 在逃/侵犯人身权利（如故意伤害） B: 经济类前科（如诈骗） C: 涉毒涉黄 E: 涉交通案件 |

2. 收入评估与社保评级 (JRZQ09J8)

字段名类型含义枚举/范围
levelstring社保收入评级-: 无记录
A级: 2k-4k元
E级: 10k-14k元
J级: 30k+元

3. 全景雷达 (JRZQ7F1A) - 借贷行为分析

字段名类型含义说明
B22170026string近12个月M0+逾期笔数逾期次数，反映履约能力
B22170054string最近一次放款时间格式 yyyy-mm
B22170053string信用贷款时长借贷活跃周期
C22180006string网贷机构平均授信额度评估其负债潜力

五、 应用价值分析

对于使用Node.js构建的现代Web应用或小程序，API提供了以下场景的赋能：

  1. 灵活用工平台即时风控

    在网约车或外卖平台的注册流程中，需要对司机/骑手进行秒级审核。通过调用FLXGDEA9（公安不良）和E类（交通肇事）筛查，平台可实时拦截有暴力犯罪或危险驾驶前科的人员，保障公共安全。

  2. 房屋租赁信用免押

    租房平台可集成该API中的JRZQ7F1A（全景雷达）和JRZQ09J8（收入评估）。如果租客的社保评级较高且无逾期记录，平台可自动通过“免押金”申请，提升用户转化率；反之则提示需加强审核。

  3. 金融助贷预筛选

    在BFF层直接聚合用户的FLXG7E8F（司法涉诉）中的“失信被执行”状态。如果用户命中“失信”或“限高”名单，前端可直接引导用户补充材料或拒绝申请，减轻后端核心风控系统的压力。

六、 总结

全能入职背调报告API为Node.js开发者提供了一个强大的数据工具箱。其“组合包”的设计思路，使得一次HTTP请求即可完成对候选人“身份+能力+信用+风险”的全方位扫描。

给开发者的建议：

  • 异步并发：虽然API本身是聚合返回，但在处理大量并发请求时（如批量导入候选人），建议使用Node.js的队列（Queue）机制来控制请求频率，避免触发系统限流。
  • 容错处理：在前端展示报告时，应充分利用 success 字段。例如，如果“学历查询”超时失败，不应导致整个报告页面崩溃，而是仅在该模块显示“数据获取中”或“暂无数据”。
  • 合规性：利用天远API进行数据采集时，务必在UI层面上设计清晰的“授权协议”勾选框，确保业务流程符合个人信息保护法的要求。
avatar
文章
阅读
粉丝