拒绝黑产与老赖：Java后端如何接入天远个人风险报告API（COMBTY11）

一、打造金融级的数据风控中台

在信贷审批、保险核保、大额资产租赁以及企业高管背景审查等严谨的业务场景中，单一的数据源往往难以描绘出完整的用户风险画像。企业需要从信用历史、反欺诈评分、司法诉讼记录以及社会安防等多个维度进行交叉验证。天远个人风险报告API （接口代码 COMBTY11）正是为此类高净值、高风险场景设计的核心数据产品。

该产品不仅提供了基础的身份核验，更通过AI模型输出了"谛听多维报告"与深度的"司法涉诉"详情。本文将面向Java后端工程师，特别是使用Spring Boot构建微服务架构的开发者，详细阐述如何将此API封装为标准化的RPC服务，解析其复杂的组合包结构，助力企业构建稳健的自动化风控决策引擎。

二、 API接口调用示例（Java版）

本接口涉及敏感数据的传输，采用了严格的加密与授权机制，非常适合在Java后端通过 OkHttp 或 RestTemplate 进行安全调用。

1. 接口配置概览

ini 复制代码

**接口地址**：`https://api.tianyuanapi.com/api/v1/COMBTY11?t=13位时间戳`

markdown 复制代码

**请求方式**：POST

javascript 复制代码

**核心安全**：业务参数需序列化为JSON，加密后转Base64，放入 `data` 字段。请求中必须包含用户的授权书URL。

2. Curl 命令行预验证

Bash

jsx 复制代码

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

3. Java 完整服务封装示例

以下代码展示了如何在Spring Boot风格的项目中，封装一个强类型的 RiskControlService。本示例使用 OkHttp3 处理网络请求，Fastjson2 处理JSON。

Java

jsx 复制代码

import okhttp3.*;
import com.alibaba.fastjson2.JSON;
import com.alibaba.fastjson2.JSONObject;
import com.alibaba.fastjson2.JSONArray;
import java.io.IOException;
import java.util.Base64;
import java.util.concurrent.TimeUnit;

/**
 * 天远API - 个人风险报告服务实现
 */
public class RiskControlService {

    // API 基础配置
    private static final String API_URL = "https://api.tianyuanapi.com/api/v1/COMBTY11";
    private static final OkHttpClient client = new OkHttpClient.Builder()
            .connectTimeout(20, TimeUnit.SECONDS) // 报告生成可能耗时，建议适当延长时间
            .readTimeout(20, TimeUnit.SECONDS)
            .build();

    /**
     * 模拟加密逻辑
     * 实际生产中请使用天远API提供的AES/RSA工具类
     */
    private String encryptPayload(JSONObject params) {
        String jsonString = params.toJSONString();
        // TODO: 在此处实现AES加密：byte[] encrypted = AesUtil.encrypt(jsonString, SECRET_KEY);
        // 此处仅演示Base64编码
        return Base64.getEncoder().encodeToString(jsonString.getBytes());
    }

    /**
     * 获取个人风险报告
     *
     * @param name 姓名
     * @param idCard 身份证号
     * @param mobile 手机号
     * @param authUrl 授权书图片/PDF链接
     * @param authDate 授权周期 "YYYYMMDD-YYYYMMDD"
     * @return JSONObject 解析后的核心风险数据
     */
    public JSONObject queryPersonalRisk(String name, String idCard, String mobile, String authUrl, String authDate) {
        // 1. 组装业务参数
        JSONObject bizParams = new JSONObject();
        bizParams.put("name", name);
        bizParams.put("id_card", idCard);
        bizParams.put("mobile_no", mobile);
        bizParams.put("authorization_url", authUrl); // 必填 
        bizParams.put("auth_date", authDate);        // 必填 // 2. 加密请求体
        String encryptedData = encryptPayload(bizParams);
        JSONObject requestBody = new JSONObject();
        requestBody.put("data", encryptedData);

        // 3. 构建Request
        long timestamp = System.currentTimeMillis();
        String finalUrl = API_URL + "?t=" + timestamp;
        
        RequestBody body = RequestBody.create(
                requestBody.toJSONString(), 
                MediaType.parse("application/json; charset=utf-8")
        );

        Request request = new Request.Builder().url(finalUrl).post(body).build();

        // 4. 执行调用与解析
        try (Response response = client.newCall(request).execute()) {
            if (response.isSuccessful() && response.body() != null) {
                String respStr = response.body().string();
                JSONObject result = JSON.parseObject(respStr);
                
                // 校验组合包响应
                if (result.containsKey("responses")) {
                    return parseRiskData(result.getJSONArray("responses"));
                }
            }
            // 记录错误日志
            System.err.println("API Request Failed: " + response.code());
        } catch (IOException e) {
            e.printStackTrace();
        }
        return null;
    }

    /**
     * 解析组合包中的核心风险指标
     */
    private JSONObject parseRiskData(JSONArray responses) {
        JSONObject riskSummary = new JSONObject();
        
        for (int i = 0; i < responses.size(); i++) {
            JSONObject item = responses.getJSONObject(i);
            String apiCode = item.getString("api_code");
            boolean success = item.getBooleanValue("success");
            JSONObject data = item.getJSONObject("data");

            if (!success || data == null) continue;

            // 根据子产品代码提取关键信息
            switch (apiCode) {
                case "DWBG8B4D": // 谛听多维报告 
                    riskSummary.put("fraudScore", data.getIntValue("fraudScore")); // 反欺诈分 
                    riskSummary.put("creditScore", data.getIntValue("creditScore")); // 信用分 
                    riskSummary.put("riskWarning", data.getJSONObject("riskWarning")); // 风险标签 break;
                case "FLXG0V4B": // 个人司法涉诉 // 提取失信被执行人列表
                    JSONObject sxbzxr = data.getJSONObject("sxbzxr");
                    if (sxbzxr != null && sxbzxr.containsKey("data")) {
                         riskSummary.put("dishonestList", sxbzxr.getJSONObject("data").getJSONArray("sxbzxr"));
                    }
                    break;
            }
        }
        return riskSummary;
    }
    
    // Test Main
    public static void main(String[] args) {
        RiskControlService service = new RiskControlService();
        JSONObject report = service.queryPersonalRisk(
            "张三", "110101199001011234", "13900000000", 
            "http://oss.url/auth.pdf", "20230101-20240101"
        );
        System.out.println("风险报告摘要: " + report);
    }
}

三、核心数据结构解析

天远API 的个人风险报告采用"组合模式"设计，这要求Java开发者建立合理的对象模型来接收数据。

数据层级架构：

Response Wrapper : 最外层包含 responses 列表。
Sub-Product Item : 每个子项包含 api_code 和 data。
- DWBG8B4D (谛听多维报告)：核心风控数据源，包含评分、标签和借贷统计。
- FLXG0V4B (个人司法涉诉)：详细法律文书数据源，包含民刑行案件及失信记录。

四、字段详解

为了方便Java开发者定义DTO（Data Transfer Object），以下列出需要重点关注的核心字段及其业务含义。

1. 评分与综合建议 (DWBG8B4D)

此模块适合映射为 RiskScoreDTO。

字段名	Java类型	含义	业务逻辑说明
`fraudScore`	`Integer`	反欺诈评分	[0,100]，>80 为高风险，建议直接拦截。
`creditScore`	`Integer`	信用评分	[300,1000]，<500 为信用一般，需人工复审。
`checkSuggest`	`String`	审核建议	枚举值如 "建议拒绝"、"建议复审"。
`fraudRule`	`String`	反欺诈规则等级	枚举值：低风险、中风险、高风险。

2. 风险预警标签 (DWBG8B4D -> riskWarning)

此模块包含大量布尔型（0/1）标记，是风控引擎的决策依据。

字段名	Java类型	含义	风险等级
`isKeyPerson`	`Integer`	是否重点人员	高风险 (涉恐/涉稳/涉黑)
`hasCriminalRecord`	`Integer`	是否有前科	高风险
`hitExecutionCase`	`Integer`	命中执行案件	高风险 (存在未履行的法院判决)
`hitCurrentOverdue`	`Integer`	命中当前逾期	中风险 (当前有未结清贷款)

3. 司法与失信记录 (FLXG0V4B)

数据结构较深，建议使用 JSONObject 或特定 JudicialDTO 处理。

字段名	Java类型	含义	说明
`sxbzxr`	`List`	失信被执行人	即"老赖"名单，包含 `lxqk`(履行情况)。
`xgbzxr`	`List`	限高被执行人	限制高消费记录。
`criminal`	`Object`	刑事案件详情	包含 `dzzm`(定罪罪名) 如"开设赌场罪"。

五、应用价值分析

将天远API集成到Java企业级系统中，可以显著提升以下场景的业务效能：

智能信贷审批引擎

在Spring Batch批处理或实时审批流中，通过调用API获取 fraudScore 和 riskWarning。系统可配置规则引擎（如Drools）：若 fraudScore > 80 或 isKeyPerson == 1，则自动触发 REJECT 动作，无需人工干预，将欺诈风险拦截在放款之前。
供应链金融准入

对于申请融资的小微企业主或个体户，利用 overdueRiskProduct（逾期风险）和 leasingRiskAssessment（租赁风险）数据，评估其多头借贷压力。如果发现申请人近期在多家租赁机构频繁申请（veryFrequentRentalApplications == 1），系统应提示可能存在骗租或资金链断裂风险。
高管与关键岗位背调

在HR系统中集成该接口，针对财务总监、司机等关键岗位进行背景扫描。重点关注 FLXG0V4B 返回的司法数据，排查是否存在"职务侵占"、"危险驾驶"等刑事前科，保障企业合规用人。

六、总结

天远个人风险报告API 为Java开发者提供了一套标准化的风控数据接入方案。通过一次接口调用，即可获取涵盖征信、司法、社会安全等维度的全量数据。

开发集成建议：

数据脱敏：由于报告包含身份证、案件详情等极度敏感信息，建议在落库（DB）时对关键字段进行加密存储，日志中严禁打印明文。
授权管理 ：API强制校验 authorization_url 和 auth_dat，开发者需在前端实现授权书签署与上传功能，确保业务合规。
降级策略 ：在解析 responses 数组时，务必判断 success 状态。如果某子产品（如司法信息）偶尔超时，应保证主流程（如基础评分）继续运行，避免因局部异常导致整个业务中断。