一、精细化风控时代的“多头”计量工具
在互金与银行信贷业务中，“多头借贷”（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编码)
- Header:
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的多头借贷行业风险版，金融机构可以在以下场景中显著提升风控效能：
区分客群资质（银行 vs. 非银）：
利用 41005 (银行分) 和 41004 (非银分) 的差异。如果一个用户在“非银”维度分数极高（频繁借网贷），但在“银行”维度分数低，说明其资质可能无法通过银行审批，属于次级客群，需谨慎授信。
识别“以贷养贷”迹象：
结合 41003 (长周期分) 和 40161 (新增平台数)。如果用户长期存在多头行为，且近期突然新增了大量借贷平台，极大概率正在寻求“拆东墙补西墙”，建议直接拒绝。
夜间反欺诈阻断：
编写规则：当 40105 (7天夜晚申请次数) / 40001 (7天总次数) > 50% 时，触发人工审核。正常用户的借贷行为通常发生在日间，夜间聚集性申请往往通过机器脚本或中介代办，具有极高的欺诈风险。
六、总结
天远多头借贷行业风险版API，通过将笼统的“申请次数”拆解为分行业（银行/互金/消金）和分时段（白天/凌晨）的精细化指标，为风控模型提供了更高维度的特征输入。
对于 Python 开发者，虽然 List 的数据结构处理起来比扁平 JSON 略繁琐，但其带来的数据密度和扩展性极高。建议在接入层编写通用的解析器（如文中的parse_risk_report），将这些高价值的RiskCode转化为业务可用的决策因子，从而构建出更稳健的信贷防御体系。
