深度解析天远多头借贷API：5大维度风险评分与共债压力量化

一、精细化风控时代的“多头”计量工具

在互金与银行信贷业务中，“多头借贷”（Multi-Lending）往往是借款人资金链断裂的前兆。然而，传统的借贷次数统计已难以满足精细化风控的需求——借款人是在银行申请房贷，还是在夜间频繁申请高息网贷？这两种行为的风险等级截然不同。

天远API 推出的“多头借贷行业风险版”接口，正是解决这一痛点的利器。它不同于普通的黑名单查询，而是通过通用、短周期、长周期、非银行、银行 5大细分维度，输出 0-100 分的量化风险评分。同时，它提供了细致到“凌晨申请占比”、“近7天新增平台数”等数百个行为指标。本文将作为一份详尽的技术指南，帮助开发者使用 Python 对接此 API，并解析其特有的 List<KV> 数据结构，助力企业构建更精准的授信模型。

二、API接口调用示例

本接口沿用了天远API的高安全标准，采用 AES-128-CBC 对称加密传输。开发者需注意请求体 data 的加密逻辑以及响应数据的解密与格式转换。

1. 接口基础信息

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

• 请求方式：POST

• 安全机制：

  • Header: Access-Id
  • Body: data (AES加密 + Base64编码)

2. Curl 调用示例

Bash

curl -X POST "<https://api.tianyuanapi.com/api/v1/DWBG7F3A?t=1716345678000>" \
  -H "Content-Type: application/json" \
  -H "Access-Id: YOUR_ACCESS_ID" \
  -d '{
    "data": "U2FsdGVkX1+..." 
  }'

3. Python 完整调用代码 (含数据清洗)

由于该接口返回的数据是 [{"riskCode":..., "riskCodeValue":...}] 的数组格式，直接使用极其不便。下方的 Python 示例中增加了一个 parse_risk_report 函数，将其转换为易于读取的字典格式。

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 TianyuanIndustryRiskAPI:
    def __init__(self, access_id, access_key):
        self.access_id = access_id
        # 确保密钥为16字节二进制
        self.access_key = access_key.encode('utf-8')[:16]
        self.api_url = "<https://api.tianyuanapi.com/api/v1/DWBG7F3A>"

    def _encrypt(self, plain_dict):
        """AES-128-CBC 加密核心逻辑"""
        try:
            # 1. 序列化并转成 bytes
            plain_text = json.dumps(plain_dict).encode('utf-8')
            # 2. 生成随机 IV
            iv = get_random_bytes(16)
            # 3. 初始化加密器
            cipher = AES.new(self.access_key, AES.MODE_CBC, iv)
            # 4. 填充并加密
            encrypted_bytes = cipher.encrypt(pad(plain_text, AES.block_size))
            # 5. 拼接 IV + 密文 -> Base64
            return base64.b64encode(iv + encrypted_bytes).decode('utf-8')
        except Exception as e:
            print(f"[Encryption Error] {e}")
            return None

    def _decrypt(self, base64_str):
        """AES-128-CBC 解密核心逻辑"""
        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"[Decryption Error] {e}")
            return None

    def query_industry_risk(self, name, id_card, mobile):
        # 1. 构造请求参数
        payload = {
            "name": name,
            "id_card": id_card,
            "mobile_no": mobile
        }

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

        # 3. 发送请求
        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()

            if res_json.get("code") == 0:
                print(">>> 请求成功，正在解密...")
                raw_data = self._decrypt(res_json.get("data"))
                
                # 4. 数据清洗（将列表转为字典）
                clean_report = self.parse_risk_report(raw_data)
                self.print_key_indicators(clean_report)
            else:
                print(f"API Error: {res_json.get('message')}")
                
        except Exception as e:
            print(f"Network Error: {e}")

    def parse_risk_report(self, raw_data):
        """
        将 [{"riskCode": "41001", "riskCodeValue": "43"}, ...] 
        转换为 {"41001": "43", ...} 以便快速查找
        """
        report_list = raw_data.get("riskInfo_report_v3.1", [])
        risk_map = {}
        for item in report_list:
            # 兼容 int 和 string 类型的 code
            code = str(item.get("riskCode"))
            val = item.get("riskCodeValue")
            risk_map[code] = val
        return risk_map

    def print_key_indicators(self, risk_map):
        print("\n=== 多头借贷行业风险核心指标 ===")
        # 41001: 多头申请通用分
        print(f"通用评分 (0-100): {risk_map.get('41001', 'N/A')}")
        # 41002: 短周期多头共债子分
        print(f"短周期风险分 (7天-3月): {risk_map.get('41002', 'N/A')}")
        # 40001: 7天内总申请次数
        print(f"近7天总申请次数: {risk_map.get('40001', '0')}")
        # 40002: 7天内银行申请次数
        print(f"近7天银行申请次数: {risk_map.get('40002', '0')}")
        # 40105: 7天总申请夜晚次数
        print(f"近7天深夜申请次数: {risk_map.get('40105', '0')}")

# 使用示例
if __name__ == "__main__":
    client = TianyuanIndustryRiskAPI("YOUR_ACCESS_ID", "YOUR_ACCESS_KEY_HEX")
    client.query_industry_risk("张三", "110101199001011234", "13800138000")

三、核心数据结构解析

与通用查询不同，本接口的响应数据结构通过 code 来定义语义，极大地压缩了传输体积。

1. 响应根节点

• code: 0 表示成功。
• data: 加密字符串，解密后包含一个核心键 riskInfo_report_v3.1。

2. 报告列表结构

解密后的 riskInfo_report_v3.1 是一个对象数组 11111。

• riskCode: 风险指标代码（如 41001, 40001）。
• riskCodeValue: 对应的具体数值（如 43 分，或 0 次）。

开发者务必在业务层建立一个映射表（Mapping），将这些数字代码转换为具有业务含义的字段名（如 score_general, count_7d_apply）。

四、字段详解（风控核心代码表）

以下表格精选了天远API行业风险版中最具业务价值的字段 2222222222222222222222222。

1. 多头共债评分（决策核心）

Code	名称	取值范围	业务解读
41001	多头申请通用分	0-100	综合评估，分数越高多头倾向越严重。
41002	短周期多头共债分	0-100	聚焦 7天-3个月 的急借行为，反映短期资金缺口。
41003	长周期多头共债分	0-100	聚焦 6个月+ 的行为，反映长期债务累积压力。
41005	银行多头共债子分	0-100	专门衡量在银行体系内的多头行为。

2. 行业维度申请统计（画像核心）

Code	名称	说明	适用场景
40002	7天内银行申请次数	银行系数据	判断用户是否在通过正规渠道融资。
40004	7天内互金申请次数	P2P/网贷数据	高频申请通常意味着资质较差或急需用钱。
40003	7天内持牌消金申请次数	持牌机构数据	衡量用户在消费场景下的活跃度。

3. 时间与行为异常（反欺诈核心）

Code	名称	说明	风险提示
40097	7天总申请白天次数	08:00 - 23:00	正常作息时间内的申请。
40105	7天总申请夜晚次数	00:00 - 07:00	高危指标：凌晨频繁申请往往对应赌博输钱或极度焦虑。
40161	7天相对过去30天新增平台	平台数差值	突发性地向大量新平台申请，是“撸口子”的典型特征。

五、应用价值分析

通过集成天远API的多头借贷行业风险版，金融机构可以在以下场景中显著提升风控效能：

1. 区分客群资质（银行 vs. 非银）：

   利用 41005 (银行分) 和 41004 (非银分) 的差异。如果一个用户在“非银”维度分数极高（频繁借网贷），但在“银行”维度分数低，说明其资质可能无法通过银行审批，属于次级客群，需谨慎授信。

2. 识别“以贷养贷”迹象：

   结合 41003 (长周期分) 和 40161 (新增平台数)。如果用户长期存在多头行为，且近期突然新增了大量借贷平台，极大概率正在寻求“拆东墙补西墙”，建议直接拒绝。

3. 夜间反欺诈阻断：

   编写规则：当 40105 (7天夜晚申请次数) / 40001 (7天总次数) > 50% 时，触发人工审核。正常用户的借贷行为通常发生在日间，夜间聚集性申请往往通过机器脚本或中介代办，具有极高的欺诈风险。

六、总结

天远多头借贷行业风险版API，通过将笼统的“申请次数”拆解为分行业（银行/互金/消金）和分时段（白天/凌晨）的精细化指标，为风控模型提供了更高维度的特征输入。

对于 Python 开发者，虽然 List 的数据结构处理起来比扁平 JSON 略繁琐，但其带来的数据密度和扩展性极高。建议在接入层编写通用的解析器（如文中的 parse_risk_report），将这些高价值的 RiskCode 转化为业务可用的决策因子，从而构建出更稳健的信贷防御体系。