Python对接天远数据多头借贷API：AES加密解密、代码实现与数据深度解析

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

在银行信贷审批 、消费金融授信 、小额贷款风控 以及互联网金融反欺诈等众多场景中，精准评估申请人的多头借贷（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提供的丰富维度数据，企业将能够构建出更加坚固的风险防火墙。