天远综合多头风险查询API接口调用代码流程、接入方法以及应用场景

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

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

天远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. 硬指标：逾期与欺诈

2. 软指标：多头与意愿

五、应用价值分析

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

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

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

2. 穿透式的信用评估：

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

3. 降低API调用成本：

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

六、总结

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

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