一、多头借贷风险数据的风控价值与应用
在银行信贷审批、消费金融授信、小额贷款风控以及互联网金融反欺诈等众多场景中，精准评估申请人的多头借贷（Multi-Lending）行为是决定放款与否的关键依据。"全国自然人多头借贷风险信息查询"API，能够提供多维度的贷款行为统计与风险标签体系，通过区间化指标精准刻画用户在贷款申请、交易、还款及逾期等方面的历史与近期行为。
本文将作为一份详细的开发文档，深入剖析此API，详细解读其基于AES加密的请求响应机制、返回的原始数据结构以及每一个核心字段的业务含义。通过接入API提供的这项数据服务，开发者可以帮助企业快速构建贷前风控模型、完善贷中监控体系，并制定更科学的额度策略，从而有效降低坏账风险。
二、API接口调用示例
本接口采用高安全性的加密传输机制，开发者在调用前需确保已获取Access-Id和Access-Key。
1. 调用前置说明
- 接口地址：
https://api.tianyuanapi.com/api/v1/JRZQ9E2A?t={13位时间戳} - 请求方式：POST
- 安全机制：
- 请求头需携带
Access-Id。 - 请求体
data字段为 Base64 编码的 AES 加密字符串。 - 加密算法：AES-128-CBC，PKCS7 填充，IV（初始化向量）为随机生成的16字节，拼接在密文前一并 Base64 编码。
- 请求头需携带
2. Curl 调用示例
Bash
# 注意：data 字段必须是经过 AES 加密并 Base64 编码后的字符串 # 实际开发中请使用编程语言生成动态的 data 和 t (时间戳) curl -X POST "https://api.tianyuanapi.com/api/v1/JRZQ9E2A?t=1716345678000" \ -H "Content-Type: application/json" \ -H "Access-Id: YOUR_ACCESS_ID" \ -d '{ "data": "U2FsdGVkX1+..." }'3. Python 完整调用代码 (含加密解密逻辑)
本示例使用requests库进行网络请求，使用pycryptodome库进行 AES 加解密处理。
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 TianyuanRiskAPI: def __init__(self, access_id, access_key): self.access_id = access_id # 密钥通常为16进制字符串，需根据实际情况处理，此处假设为16字节 self.access_key = access_key.encode('utf-8')[:16] self.api_url = "https://api.tianyuanapi.com/api/v1/JRZQ9E2A" def encrypt_data(self, plain_dict): """ AES-128-CBC 加密逻辑 1. 生成随机 16 字节 IV 2. 使用 PKCS7 填充数据 3. 加密后将 IV 拼接到密文前 4. 进行 Base64 编码 """ 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 和 密文，然后 Base64 combined = iv + encrypted_bytes return base64.b64encode(combined).decode('utf-8') except Exception as e: print(f"加密失败: {e}") return None def decrypt_data(self, encrypted_base64): """ AES-128-CBC 解密逻辑 1. Base64 解码 2. 提取前 16 字节作为 IV 3. 解密剩余密文并去除填充 """ try: encrypted_bytes = base64.b64decode(encrypted_base64) iv = encrypted_bytes[:16] ciphertext = encrypted_bytes[16:] cipher = AES.new(self.access_key, AES.MODE_CBC, iv) decrypted_text = unpad(cipher.decrypt(ciphertext), AES.block_size) return json.loads(decrypted_text.decode('utf-8')) except Exception as e: print(f"解密失败: {e}") return None def query_risk_info(self, name, id_card, mobile, auth_code): # 1. 构造请求参数 payload = { "name": name, "id_card": id_card, "mobile_no": mobile, "auth_authorize_file_code": auth_code # 授权书编号 } # 2. 加密参数 encrypted_data = self.encrypt_data(payload) if not encrypted_data: return # 3. 发起请求 headers = {"Access-Id": self.access_id} timestamp = int(time.time() * 1000) url = f"{self.api_url}?t={timestamp}" try: response = requests.post(url, json={"data": encrypted_data}, headers=headers) res_json = response.json() # 4. 处理响应 if res_json.get("code") == 0: # 0 表示业务成功 print("请求成功，正在解密数据...") # 解密 data 字段 decrypted_result = self.decrypt_data(res_json.get("data")) print("多头借贷风险数据解析结果：") print(json.dumps(decrypted_result, indent=4, ensure_ascii=False)) else: print(f"API请求错误: Code {res_json.get('code')}, Message: {res_json.get('message')}") except Exception as e: print(f"网络请求异常: {e}") # 使用示例 if __name__ == "__main__": # 请替换为实际的 Access-Id 和 Access-Key api_client = TianyuanRiskAPI("YOUR_ACCESS_ID", "YOUR_ACCESS_KEY_128BIT") api_client.query_risk_info( name="张三", id_card="110101199001011234", mobile="13800138000", auth_code="AUTH20251210001" )三、核心数据结构解析
API 的响应数据分为两层。第一层是公共响应参数，包含状态码和流水号；第二层是加密的data业务数据，解密后是一个包含数百个风险指标的 JSON 对象。
1. 公共响应结构
| 字段名 | 类型 | 描述 |
|---|---|---|
| code | int | 状态码，0表示成功，非0表示异常（如1002参数解密失败） |
| message | string | 错误或成功信息描述 |
| transaction_id | string | 业务流水号，用于排查问题 |
| data | string | 加密后的业务数据，需解密查看 |
2. 业务数据层级
解密后的 JSON 数据主要包含以下几类指标：
- 机构数量统计：如贷款总机构数、近7天/30天贷款机构数。
- 交易与还款行为：历史还款成功笔数、交易失败笔数。
- 逾期风险指标：当前逾期状态、历史逾期天数。
- 金额统计：近30天/90天/180天的交易与还款金额统计。
**模型评分**：信用风险评分、小额网贷分等。四、字段详解
由于接口返回字段极其丰富，以下列举核心风控场景中最常用的字段进行解析。注意，大部分金额和次数类字段采用区间化输出（Mapping），例如 “1” 可能代表 “(0,9)” 区间。
1. 机构申请与借贷概览
| 参数代码 | 中文描述 | 说明/区间示例 |
|---|---|---|
| xyp_cpl0001 | 贷款总机构数 | 区间输出，如 "1"代表(0,9)家 |
| xyp_cpl0002 | 贷款已结清机构数 | 衡量用户过往信誉，区间输出 |
| xyp_cpl0044 | 当前是否存在逾期未结清 | 重要：1 - 逾期 ； 0 - 未逾期 |
| xyp_cpl0007 | 消费金融类机构数 | 包含有场景的分期业务 |
| xyp_cpl0008 | 网络贷款类机构数 | 主要指现金贷类机构 |
2. 短期申请集中度（多头预警）
| 参数代码 | 中文描述 | 说明 |
|---|---|---|
| xyp_cpl0070 | 最近1天贷款机构数 | 突发急借指标 |
| xyp_cpl0009 | 最近7天贷款机构数 | 衡量短期资金饥渴度 |
| xyp_cpl0011 | 最近30天贷款机构数 | 中短期多头借贷风险指标 |
3. 逾期与履约能力
| 参数代码 | 中文描述 | 说明 |
|---|---|---|
| xyp_cpl0028 | 最近1天是否发生过逾期 | 1-逾期，0-未逾期 |
| xyp_cpl0031 | 最近30天是否发生过逾期 | 反应近期还款压力 |
| xyp_cpl0071 | 当前逾期机构数 | 同时违约的平台数量 |
| xyp_cpl0072 | 当前逾期金额 | 违约资金规模（区间化） |
4. 信用评分与模型分
| 参数代码 | 中文描述 | 说明 |
|---|---|---|
| xyp_cpl0081 | 信用风险评分 | 0-1之间，分数越高用户信用越低 |
| xyp_model_score_high | 小额网贷分V1 | [350,950]，分数越大逾期率越 |
| xyp_model_score_mid | 小额分期分V1 | [350,950]，分数越大逾期率越低 |
五、应用价值分析
通过集成API的多头借贷风险查询服务，开发者可以为企业风控系统带来显著价值：
精准识别"拆东墙补西墙"：
通过分析 xyp_cpl0009 (近7天贷款机构数) 和 xyp_cpl0031 (近30天是否逾期) 等字段，系统能快速识别出急需资金周转的潜在高风险用户，有效拦截共债风险。
量化评估还款能力：
利用 xyp_cpl0039 (近30天还款成功总金额) 与 xyp_cpl0072 (当前逾期金额) 的对比，结合收入证明，金融机构可以更科学地核定授信额度，避免过度授信。
贷中动态监控：
对于存量客户，定期调用此API监控其 xyp_cpl0044 (当前是否存在逾期) 和 xyp_cpl0008 (网贷机构数) 的变化。一旦发现用户在短时间内在多家平台发生借贷行为，系统可触发预警，及时采取降额或催收策略。
六、总结
全国自然人多头借贷风险信息查询API为金融科技开发者提供了一套标准化、数据化、区间化的风控解决方案。虽然其接口涉及 AES 加密与 Base64 编码，增加了一定的对接门槛，但这也极大地保障了用户隐私数据的传输安全。
建议开发者在接入过程中，重点关注错误码处理（如 1002 解密失败、1007 余额不足），并建立完善的日志系统。通过合理利用API提供的丰富维度数据，企业将能够构建出更加坚固的风险防火墙。
