深度解析天远数据综合多头API：从共债申请到团伙欺诈的 AES 解密与数据清洗

天远API
55 阅读8分钟

一、一站式洞察借款人的“隐形债务”与“欺诈风险”

在信贷风控领域，风控人员常常面临“数据孤岛”的困扰：查询多头借贷需要调一个接口，查询逾期黑名单需要调另一个接口，反欺诈又是第三个接口。这不仅增加了对接成本，也降低了决策效率。

天远API 推出的“综合多头”接口（JRZQ8F7C），正如其名，是一款全能型的风控工具。它聚合了 多头借贷评分、分行业申请记录、多头逾期详情、圈团欺诈风险 以及 可疑准入风险 等五大类、数百个关键指标。通过这一接口，企业可以一次性获取借款人在银行、消金、P2P等全行业的借贷轨迹及违约风险。

本文将作为一份详尽的开发指南，演示如何使用 Python 对接此高安全级别的 AES 加密接口，并提供一套高效的数据清洗方案，将接口返回的数百个 KV 键值对转化为结构化的风控报告。

二、API接口调用示例

本接口采用金融级安全传输标准，要求请求体进行 AES-128-CBC 加密。由于涉及 authorized（授权状态）等合规字段，开发者需严格遵守调用规范。

1. 接口基础信息

  • 接口地址：https://api.tianyuanapi.com/api/v1/JRZQ8F7C?t={13位时间戳}

  • 请求方式：POST

  • 安全机制：

    • Header: Access-Id
    • Body: data (AES加密 + Base64编码，IV拼接在密文前)

  • 核心入参：id_card, name, mobile_no, authorized ("1"代表已获授权)

2. Curl 调用示例

Bash

# 注意：实际 data 字段需由代码生成，包含随机 IV 和加密内容
curl -X POST "<https://api.tianyuanapi.com/api/v1/JRZQ8F7C?t=1716345678000>" \
  -H "Content-Type: application/json" \
  -H "Access-Id: YOUR_ACCESS_ID" \
  -d '{
    "data": "U2FsdGVkX1+..." 
  }'

3. Python 完整调用代码 (含全维度数据解析)

为了应对接口返回的庞大 KV 列表，本示例封装了一个 RiskDataParser 类，能够将分散的指标自动归类为“多头”、“逾期”、“反欺诈”三个维度。

Python

import requests
import json
import time
import base64
from Crypto.Cipher import AES
from Crypto.Util.Padding import pad, unpad
from Crypto.Random import get_random_bytes

class TianyuanComprehensiveAPI:
    def __init__(self, access_id, access_key):
        self.access_id = access_id
        # 密钥截取前16位作为AES Key
        self.access_key = access_key.encode('utf-8')[:16]
        self.api_url = "<https://api.tianyuanapi.com/api/v1/JRZQ8F7C>"

    def _encrypt(self, plain_dict):
        """AES-128-CBC 加密，IV拼接到密文前"""
        try:
            plain_text = json.dumps(plain_dict).encode('utf-8')
            iv = get_random_bytes(16)
            cipher = AES.new(self.access_key, AES.MODE_CBC, iv)
            encrypted_bytes = cipher.encrypt(pad(plain_text, AES.block_size))
            # 组合: IV + CipherText -> Base64
            return base64.b64encode(iv + encrypted_bytes).decode('utf-8')
        except Exception as e:
            print(f"[加密错误] {e}")
            return None

    def _decrypt(self, base64_str):
        """AES-128-CBC 解密，提取前16位IV"""
        try:
            encrypted_data = base64.b64decode(base64_str)
            iv = encrypted_data[:16]
            cipher_text = encrypted_data[16:]
            cipher = AES.new(self.access_key, AES.MODE_CBC, iv)
            decrypted_text = unpad(cipher.decrypt(cipher_text), AES.block_size)
            return json.loads(decrypted_text.decode('utf-8'))
        except Exception as e:
            print(f"[解密错误] {e}")
            return None

    def query_comprehensive_risk(self, name, id_card, mobile):
        # 1. 构造参数 (注意 authorized 字段)
        payload = {
            "name": name,
            "id_card": id_card,
            "mobile_no": mobile,
            "authorized": "1" # 必须获得用户授权
        }

        # 2. 加密请求
        encrypted_data = self._encrypt(payload)
        if not encrypted_data: return

        # 3. 发送 POST
        timestamp = int(time.time() * 1000)
        url = f"{self.api_url}?t={timestamp}"
        headers = {"Access-Id": self.access_id}
        
        try:
            resp = requests.post(url, json={"data": encrypted_data}, headers=headers)
            res_json = resp.json()

            # 4. 处理响应
            if res_json.get("code") == "200" or res_json.get("code") == 200:
                print(">>> API调用成功，正在解析全维度报告...")
                # 注意：部分接口返回的 data 是直接的列表，部分是加密串，需根据实际情况调整
                # 假设此处遵循文档标准流程，Data为加密串
                if isinstance(res_json.get("data"), str):
                     raw_data = self._decrypt(res_json.get("data"))
                else:
                     raw_data = res_json.get("data") # 若未加密直接返回列表

                # 5. 数据清洗与展示
                parser = RiskDataParser(raw_data)
                parser.print_summary()
            else:
                print(f"API 业务异常: Code {res_json.get('code')} - {res_json.get('message')}")
                
        except Exception as e:
            print(f"网络请求失败: {e}")

class RiskDataParser:
    """风控数据解析器，将 KV 列表转换为结构化视图"""
    def __init__(self, data_list):
        # 将 [{"riskCode":..., "riskCodeValue":...}] 转为字典
        self.data_map = {str(item.get("riskCode")): str(item.get("riskCodeValue")) for item in data_list}

    def get_val(self, code):
        return self.data_map.get(str(code), "未命中")

    def print_summary(self):
        print("\n======== 借款人综合风险画像 ========")
        
        print(f"[1. 核心评分]")
        print(f"  > 多头通用分(41001): {self.get_val(41001)} (0-100, 分高风险大)")
        print(f"  > 银行系共债分(41005): {self.get_val(41005)}")
        
        print(f"\n[2. 申请行为 - 7天窗口]")
        print(f"  > 总申请次数(40001): {self.get_val(40001)}")
        print(f"  > 网贷/互金申请(40004): {self.get_val(40004)}")
        print(f"  > 深夜(0-7点)申请(40105): {self.get_val(40105)}")

        print(f"\n[3. 逾期风险 - 核心预警]")
        print(f"  > 近3个月逾期平台数(17003): {self.get_val(17003)}")
        print(f"  > 当前是否有信贷逾期(17001): {self.get_val(17001)}")

        print(f"\n[4. 团伙欺诈风险]")
        print(f"  > 圈团风险等级(22006): {self.get_val(22006)} (1低/2中/3高)")
        print(f"  > 疑似准入风险(31006): {self.get_val(31006)}")
        print("====================================")

# 使用示例
if __name__ == "__main__":
    # 请替换为真实的 AccessId 和 Key
    client = TianyuanComprehensiveAPI("YOUR_ACCESS_ID", "YOUR_ACCESS_KEY_HEX")
    client.query_comprehensive_risk("张三", "110101199001011234", "13800138000")

三、核心数据结构解析

本接口返回的数据量巨大，理解其分类逻辑至关重要。解密后的数据是一个扁平的 Object List，但逻辑上分为五个板块。

1. 数据概览

JSON

{
  "code": "200",
  "data": [
    { "riskCode": 41001, "riskCodeValue": 85 },   // 评分
    { "riskCode": 40001, "riskCodeValue": 12 },   // 申请次数
    { "riskCode": 17003, "riskCodeValue": 2 },    // 逾期平台数
    { "riskCode": 22006, "riskCodeValue": 3 }     // 团伙风险等级
    ...
  ]
}

2. 五大风险维度

  1. 多头评分 (41xxx) ：宏观量化指标，0-100分，分数越高风险越大。
  2. 申请统计 (40xxx) ：包含分行业（银行/非银）、分时段（白天/深夜）、分周期（7天-720天）的申请次数与平台数。
  3. 多头逾期 (17xxx) ：本接口的核心亮点，统计用户在不同周期（1周-1年）内的逾期平台数和次数。
  4. 圈团风险 (2xxxx) ：基于关联网络识别的团伙欺诈风险。
  5. 可疑风险 (3xxxx) ：基于规则引擎识别的异常准入风险。

四、字段详解（综合风控核心表）

以下精选了在构建“贷前自动审批系统”时，建议纳入一票否决或强规则的核心字段。

1. 硬指标：逾期与欺诈

字段 Code字段名称业务含义建议策略
170011周内逾期平台数当前正在发生的违约直接拒绝。当前存在逾期，且为近期发生，还款能力极差。
170033个月内逾期平台数短期偿债压力测试若 > 1，建议转人工审核或拒绝，说明近期资金链断裂。
22006圈团2风险等级团伙欺诈识别返回 3 (高风险) 时，代表用户位于欺诈团伙关联网络中心，建议拦截。
31006疑似准入风险资料/行为异常1=低，2=中，3=高。高风险建议拦截。

2. 软指标：多头与意愿

字段 Code字段名称业务含义建议策略
41001多头申请通用分综合借贷活跃度作为评分卡输入变量（X变量）。
401057天总申请夜晚次数异常时段借贷若次数过高，提示赌博或中介代办风险。
400047天内互金申请次数网贷依赖度相比银行申请，互金申请过多代表资质下沉。
401617天新增平台数撸口子速度突发性新增大量平台，预示即将“跑路”。

五、应用价值分析

天远API 的综合多头接口将原本分散的风险数据进行了物理聚合，为企业带来了极大的应用价值：

  1. 构建全能型反欺诈（Anti-Fraud）防火墙：

    利用 22006（圈团风险）和 31006（疑似准入风险），可以在用户注册或申请的第一时间，识别出黑产攻击、中介代办或组团骗贷行为，无需单独对接复杂的图计算服务。

  2. 穿透式的信用评估：

    通过 17xxx 系列的逾期指标，企业不仅能知道用户“借了多少”（多头申请），还能知道用户“还了没有”（逾期详情）。例如，结合 40037（总申请数）和 17006（1年前逾期数），可以判断用户是“老赖”还是“近期突发困难”。

  3. 降低API调用成本：

    传统模式下，获取画像需要调用“多头查询”+“逾期黑名单”+“反欺诈”三个接口。本接口一次性返回所有数据，大幅降低了单次查询的综合成本（TPC）和网络延迟。

六、总结

综合多头风险查询API是天远API产品线中的旗舰级服务。它不仅提供了 Python 开发者急需的结构化风控数据，更通过引入“逾期”和“团伙”维度，填补了单纯多头数据的盲区。

在实际对接中，建议开发者重点关注数据清洗环节，将 nan 或 -1（未查得）的数据进行特殊处理（如填充默认值或标记为缺失），以确保风控模型的鲁棒性。通过这一接口，您的系统将具备银行级的风险识别能力。

avatar
文章
阅读
粉丝