## 一、多头借贷风险数据的风控价值与应用

在**银行信贷审批**、**消费金融授信**、**小额贷款风控**以及**互联网金融反欺诈**等众多场景中，精准评估申请人的多头借贷（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的多头借贷风险查询服务，开发者可以为企业风控系统带来显著价值：

1. 精准识别"拆东墙补西墙"：
	通过分析 xyp_cpl0009 (近7天贷款机构数) 和 xyp_cpl0031 (近30天是否逾期) 等字段，系统能快速识别出急需资金周转的潜在高风险用户，有效拦截共债风险。

2. 量化评估还款能力：
	利用 xyp_cpl0039 (近30天还款成功总金额) 与 xyp_cpl0072 (当前逾期金额) 的对比，结合收入证明，金融机构可以更科学地核定授信额度，避免过度授信。

3. 贷中动态监控：
	对于存量客户，定期调用此API监控其 xyp_cpl0044 (当前是否存在逾期) 和 xyp_cpl0008 (网贷机构数) 的变化。一旦发现用户在短时间内在多家平台发生借贷行为，系统可触发预警，及时采取降额或催收策略。


## 六、总结

全国自然人多头借贷风险信息查询API为金融科技开发者提供了一套标准化、数据化、区间化的风控解决方案。虽然其接口涉及 AES 加密与 Base64 编码，增加了一定的对接门槛，但这也极大地保障了用户隐私数据的传输安全。

建议开发者在接入过程中，重点关注错误码处理（如 1002 解密失败、1007 余额不足），并建立完善的日志系统。通过合理利用API提供的丰富维度数据，企业将能够构建出更加坚固的风险防火墙。

在银行信贷审批、消费金融授信、小额贷款风控以及互联网金融反欺诈等众多场景中，精准评估申请人的多头借贷（Multi-Lending）行为是决定放款与否的关键依据。"全国自然人多头借贷风险信息查询"API，能够提供多维度的贷款行为统计与风险标签体系，通过区间化指标精准刻画用户在贷款申请、交易、还款及逾期等方面的历史与近期行为。

金融风控实战：全国自然人多头借贷风险查询API接口接入指南与Python实现

编程语言

安全

后端

全国自然人多头借贷风险信息查询API提供精准风控数据，支持银行、消费金融等机构评估申请人贷款行为。API采用AES加密传输，包含机构数、逾期指标等核心字段，帮助构建贷前风控模型，降低坏账风险。详细接口文档涵盖加密机制、调用示例及字段解析，助力开发者快速集成。

数据结构

防火墙

Python

JSON

文章

问答

视频

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

金融风控实战：全国自然人多头借贷风险查询API接口接入指南与Python实现-腾讯云开发者社区-腾讯云

金融风控实战：全国自然人多头借贷风险查询API接口接入指南与Python实现

金融风控实战：全国自然人多头借贷风险查询API接口接入指南与Python实现

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐