一、 构建实时、轻量级的个人风控网关
在互联网金融（FinTech）、共享经济（如网约车、房屋短租）以及电商分期等高频交易场景中，用户体验与风险控制往往是一对矛盾体。前端业务需要毫秒级的响应速度，而后台风控却需要查询海量数据。天远个人风险报告API （接口代码 COMBTY11）通过聚合谛听多维报告与深度司法数据，为解决这一矛盾提供了完美的"数据中间件"。
该API不仅提供基础的实名与运营商核验，更输出了反欺诈评分、借贷意向分析及详细的司法涉诉记录。对于使用 Node.js 构建 BFF 层或微服务的团队而言，天远API 标准化的 JSON 数据结构与高效的响应能力，能够帮助开发者快速搭建起一道轻量级、高并发的人员风险防火墙，在不牺牲用户体验的前提下实现精准拦截。
二、 API接口调用示例（Node.js版）
本接口支持 HTTPS POST 请求，数据交互采用 JSON 格式。Node.js 的非阻塞 I/O 特性非常适合处理此类外部 API 的聚合调用。
1. 接口技术参数
- 接口地址 ：
https://api.tianyuanapi.com/api/v1/COMBTY11?t=13位时间戳 - 请求方式：POST
- 鉴权与加密 ：业务参数（含授权书URL）需序列化后加密，并转为 Base64 字符串放入
data字段。
2. Curl 命令行测试
Bash
jsx
curl -X POST "https://api.tianyuanapi.com/api/v1/COMBTY11?t=1715068800000" \
-H "Content-Type: application/json" \
-d '{
"data": "eyJpZF9jYXJkIjoiNDUyMTIyMjAwMDA4Mjc0MjNYIiwibmFtZSI6IuW8oOS7SiIsIm1vYmlsZV9ubyI6IjEzODAwMTM4MDAwIiwiYXV0aG9yaXphdGlvbl91cmwiOiJodHRwczovL29zcy5leGFtcGxlLmNvbS9hdXRoLnBuZyIsImF1dGhfZGF0ZSI6IjIwMjMwMTAxLTIwMjMxMjMxIn0="
}'3. Node.js (Axios + Async/Await) 调用示例
以下代码展示了如何在 Node.js 环境中（适用于 Express/Koa/NestJS）封装一个通用的风控查询服务。
JavaScript
jsx
const axios = require('axios');
// const crypto = require('crypto'); // 实际加密需要用到
// 1. API 配置
const API_CONFIG = {
url: 'https://api.tianyuanapi.com/api/v1/COMBTY11',
timeout: 10000 // 建议设置较长超时，因为涉及多维数据查询
};
/**
* 模拟加密处理函数
* 实际接入时，请使用天远API提供的加密算法（通常为AES）替换此函数
*/
function encryptPayload(payload) {
const jsonStr = JSON.stringify(payload);
// TODO: 实现真实的加密逻辑
// const encrypted = aesEncrypt(jsonStr, secretKey);
// 这里仅做 Base64 编码演示
return Buffer.from(jsonStr).toString('base64');
}
/**
* 获取个人风险报告
* @param {Object} userInfo 用户信息对象
* @returns {Promise<Object>} 解析后的风险数据
*/
async function fetchRiskReport(userInfo) {
const { name, idCard, mobile, authUrl, authDate } = userInfo;
// 2. 构建业务参数
const payload = {
name: name,
id_card: idCard,
mobile_no: mobile,
authorization_url: authUrl, // 必须提供授权书 URL auth_date: authDate // 格式 YYYYMMDD-YYYYMMDD
};
const encryptedData = encryptPayload(payload);
const timestamp = Date.now();
try {
// 3. 发起异步请求
const response = await axios.post(`${API_CONFIG.url}?t=${timestamp}`, {
data: encryptedData
}, {
headers: { 'Content-Type': 'application/json' }
});
const result = response.data;
// 4. 处理组合包响应
if (result && result.responses) {
return transformData(result.responses);
} else {
console.error('API Error:', result);
throw new Error('Risk API response format error');
}
} catch (error) {
console.error('Request Failed:', error.message);
return null;
}
}
/**
* 数据清洗与转换工具函数
* 将复杂的组合包结构扁平化，便于前端使用
*/
function transformData(responses) {
const report = {
summary: { score: 0, suggestion: '' },
risks: [],
legal: []
};
responses.forEach(item => {
if (!item.success || !item.data) return;
// 谛听多维报告 (DWBG8B4D)
if (item.api_code === 'DWBG8B4D') {
const data = item.data;
report.summary.fraudScore = data.fraudScore; // 反欺诈分
report.summary.creditScore = data.creditScore; // 信用分
report.summary.suggestion = data.checkSuggest; // 审核建议
// 提取高风险项
if (data.riskWarning) {
Object.entries(data.riskWarning).forEach(([key, value]) => {
if (value === 1 && key !== 'totalRiskCounts') {
report.risks.push(key); // 将命中的风险标签加入数组
}
});
}
}
// 个人司法涉诉 (FLXG0V4B)
else if (item.api_code === 'FLXG0V4B') {
const entout = item.data.entout?.data || {};
const sxbzxr = item.data.sxbzxr?.data?.sxbzxr || []; // 失信被执行人
if (sxbzxr.length > 0) {
report.legal.push(...sxbzxr.map(c => ({
type: '失信被执行',
court: c.zxfy, // 执行法院 caseNo: c.ah, // 案号 duty: c.yw // 义务
})));
}
}
});
return report;
}
// 5. 执行调用测试
(async () => {
const user = {
name: "张三",
idCard: "110101199001011234",
mobile: "13900000000",
authUrl: "http://oss.example.com/auth/user_123.jpg",
authDate: "20230101-20250101"
};
const result = await fetchRiskReport(user);
console.log('清洗后的风控报告:', JSON.stringify(result, null, 2));
})();三、 核心数据结构解析
天远API 的响应设计遵循"组合模式"，这对于 JavaScript 的解构赋值非常友好。
数据层级概览：
- Response Body : 包含
responses数组。 - Item Object : 数组元素，包含
api_code和data。- DWBG8B4D : 核心风控数据。重点关注
fraudScore（反欺诈分）、creditScore（信用分）和riskWarning（风险清单）。 - FLXG0V4B : 司法详情。重点关注
sxbzxr（失信名单）和entout.data.criminal（刑事案件）。
- DWBG8B4D : 核心风控数据。重点关注
四、 字段详解
为了方便 Node.js 开发者在 TypeORM 或 Mongoose 中定义 Schema，以下列出核心字段的详细说明。
1. 评分与建议 (DWBG8B4D -> data)
| 字段名 (JSON) | JS类型 | 含义 | 业务逻辑参考 |
|---|---|---|---|
fraudScore |
Number | 反欺诈评分 | 范围 [0,100]。>80 为高风险，建议前端直接提示拒绝。 |
creditScore |
Number | 信用评分 | 范围 [300,1000]。<500 为信用一般，建议人工复审。 |
checkSuggest |
String | 审核建议 | 值示例："建议拒绝"、"建议复审" 。 |
2. 借贷与逾期风险 (DWBG8B4D -> overdueRiskProduct)
此模块数据适合做贷前评估。
| 字段名 (JSON) | JS类型 | 含义 | 说明 |
|---|---|---|---|
currentOverdueAmount |
String | 当前逾期金额 | 如 "(0,1000)"，表示逾期金额区间。 |
overdueLast30Days |
String | 近30天逾期状态 | "逾期" 或 "未逾期"。 |
totalLoanInstitutions |
String | 贷款总机构数 | 多头借贷指标，数值过大风险高。 |
3. 司法涉诉 (FLXG0V4B)
重点关注"老赖"和刑事记录。
| 字段名 (JSON) | JS类型 | 含义 | 说明 |
|---|---|---|---|
sxbzxr |
Array | 失信被执行人列表 | 包含 xwqx (失信行为具体情形)。 |
xgbzxr |
Array | 限高被执行人列表 | 包含 fbrq (发布日期) 。 |
criminal |
Object | 刑事案件 | 位于 entout.data 下，包含 dzzm (定罪罪名)。 |
五、 应用价值分析
在 Node.js 生态中，接入 天远API 可以为多种互联网业务场景提供强大的风控支持：
-
电商分期/先用后付 (BNPL)
在用户点击"开通分期"的瞬间，BFF 层异步调用 天远API。通过 creditScore 和 overdueRiskProduct 数据，实时计算用户的信用额度。如果 currentOverdueAmount 不为空，则自动拒绝开通，有效控制坏账率。
-
C2C 租赁平台 (房屋/电子产品)
在租客提交订单时，调用接口检查 leasingRiskAssessment（租赁风险评估）15。如果发现租客在近期频繁申请租赁机构（veryFrequentRentalApplications == 1）16 或存在司法执行记录，系统可自动调整押金比例或要求第三方担保。
-
社交/婚恋平台的高端认证
针对实名认证的高端用户，利用 FLXG0V4B 中的婚姻状况（如有）和司法涉诉记录进行背景核实。若发现用户存在"重婚罪"或严重的"经济诈骗"前科（hasCriminalRecord == 1）17，平台可及时封禁账号，维护社区生态安全。
六、 总结
天远个人风险报告API 为 Node.js 开发者提供了一套高效、全面的数据解决方案。通过一次请求，即可获取横跨征信、司法、社会安全三大领域的全景画像，极大地简化了风控系统的开发复杂度。
集成小贴士：
- 文件上传 ：由于接口需要
authorization_url，开发者需先将用户签署的授权书上传至对象存储（如 COS/OSS），再将公网链接传给 API。 - 数据缓存：风险报告数据量大且更新频率相对较低，建议在 Redis 中缓存查询结果（如缓存 24 小时），以节省 API 调用成本并提升响应速度。
- 隐私保护：在前端展示报告时，务必对敏感信息（如具体案号、涉案金额）进行脱敏处理，仅展示风险等级或建议。