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

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

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

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

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

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

1. 接口配置概览

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

**请求方式**：POST

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

2. Curl 命令行预验证

Bash

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

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开发者建立合理的对象模型来接收数据。

数据层级架构：

1. Response Wrapper: 最外层包含 responses 列表。
2. 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企业级系统中，可以显著提升以下场景的业务效能：

1. 智能信贷审批引擎

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

2. 供应链金融准入

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

3. 高管与关键岗位背调

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

六、 总结

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

开发集成建议：

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