一、关于信贷行为数据洞察API
在线上信贷实时审批、贷后风险监控与预警、客户分层与差异化定价等众多场景中，全面掌握用户的借贷行为历史是进行精准风险评估与营销策略制定的关键依据。"信贷行为数据洞察"API，能够基于用户的历史借贷全周期数据，按多时间窗口、多渠道及多业务类型进行细粒度统计与建模，输出高价值的行为评分及趋势分析。
本文将作为一份详细的开发文档，深入剖析此API，详细解读其返回的原始数据结构和每一个核心字段的含义，帮助开发者利用借贷行为大数据进行更深层次的数据分析与企业智能风控应用集成。作为天远API的核心数据产品之一，该接口以其高维度的特征刻画和稳定的服务响应，为金融科技开发者提供了强有力的技术支撑。
二、API接口调用示例
1. 调用说明
本接口采用高安全性的加密传输机制，确保敏感数据在传输过程中的安全性。
-
接口地址：
https://api.tianyuanapi.com/api/v1/JRZQ3C9R?t={13位时间戳} -
请求方式：
POST -
安全机制：
- Header：需携带
Access-Id。 - Body：请求参数需进行 AES-128-CBC 加密并 Base64 编码，封装在
data字段中。 - Response：响应数据同样为加密字符串，需解密后使用。
- Header：需携带
2. curl 调用示例
curl -X POST "<https://api.tianyuanapi.com/api/v1/JRZQ3C9R?t=1716968800000>" \
-H "Content-Type: application/json" \
-H "Access-Id: YOUR_ACCESS_ID_HERE" \
-d '{
"data": "U2FsdGVkX1+..."
}'
# 注：data字段的值为经过AES加密并Base64编码后的JSON字符串
# 原始请求参数结构: {"idCard": "...", "name": "...", "phone": "...", "authorized": "1"}
3. Python完整调用代码示例
本示例包含完整的加密、请求、解密及异常处理流程。
import requests
import json
import time
import base64
# 注意：实际生产需安装 pycryptodome 库
# from Crypto.Cipher import AES
# from Crypto.Util.Padding import pad, unpad
# === 配置信息 ===
API_URL = "<https://api.tianyuanapi.com/api/v1/JRZQ3C9R>"
ACCESS_ID = "YOUR_ACCESS_ID" # 替换为您的 Access-Id
ACCESS_KEY = "YOUR_ACCESS_KEY" # 替换为您的 Access-Key (16位Hex字符串)
class TianYuanAPISdk:
def __init__(self, access_id, access_key):
self.access_id = access_id
self.access_key = access_key
def encrypt_data(self, data_dict):
"""
AES-128-CBC 加密函数 (此处为逻辑占位符)
真实逻辑：
1. JSON dumps data_dict
2. AES CBC Encrypt with random IV
3. Return Base64(IV + CipherText)
"""
print(f"[加密] 正在加密参数: {data_dict.keys()}")
# 模拟返回加密字符串
return "MOCK_ENCRYPTED_BASE64_STRING_======="
def decrypt_data(self, encrypted_str):
"""
AES-128-CBC 解密函数 (此处为逻辑占位符)
真实逻辑：
1. Base64 decode
2. Extract IV (first 16 bytes)
3. AES CBC Decrypt rest
4. Unpad & JSON loads
"""
print(f"[解密] 收到响应长度: {len(encrypted_str)}")
# 模拟解密后的JSON数据结构
return {
"flag": 1,
"ppcm_behav_score": 680,
"ppcm_m3_qynum": 5,
"ppcm_d7_overnum": 0,
"message": "解密成功"
}
def query_credit_insight(self, name, id_card, phone):
"""发起API请求"""
timestamp = int(time.time() * 1000)
url = f"{API_URL}?t={timestamp}"
headers = {
"Access-Id": self.access_id,
"Content-Type": "application/json"
}
payload = {
"name": name,
"idCard": id_card,
"phone": phone,
"authorized": "1" # 必须获得授权
}
try:
# 1. 加密
encrypted_payload = self.encrypt_data(payload)
body = {"data": encrypted_payload}
# 2. 请求
print(f"正在请求天远API: {url}")
response = requests.post(url, headers=headers, json=body, timeout=10)
# 3. 处理响应
if response.status_code == 200:
res_json = response.json()
if res_json.get("code") == "200":
# 4. 解密业务数据
# 接口返回的 data 字段通常为加密串
encrypted_res_data = res_json.get("data")
# 根据实际情况，如果已经是对象则直接返回，如果是字符串则解密
if isinstance(encrypted_res_data, str):
return self.decrypt_data(encrypted_res_data)
return encrypted_res_data
else:
print(f"业务报错: {res_json.get('message')}")
return None
else:
print(f"HTTP错误: {response.status_code}")
return None
except Exception as e:
print(f"请求异常: {e}")
return None
if __name__ == "__main__":
sdk = TianYuanAPISdk(ACCESS_ID, ACCESS_KEY)
result = sdk.query_credit_insight("张三", "11010119900101xxxx", "1380000xxxx")
if result:
print("API调用成功，解析结果:")
print(json.dumps(result, indent=4, ensure_ascii=False))
三、核心数据结构解析
天远API 该接口返回的数据结构经过精心设计，支持扁平化解析，非常适合直接导入大数据风控模型。
-
数据外层：包含标准的
code(状态码),message(提示信息),transaction_id(交易流水号) 以及加密的data业务负载。 -
解密后Data层：
- 标识类：
flag(是否查得),flagdb(库中是否有记录)。 - 评分：
ppcm_behav_score，直观量化风险。 - 特征群：数百个以
ppcm_开头的统计字段。
- 标识类：
-
特殊值处理：
- 1：表示该时间窗口或该维度下无数据（未命中），非零值。
- >0：实际发生的次数或金额等级。
- 小数：表示比率（如查贷比）或均值。
四、字段详解
本接口字段采用 ppcm_[时间段]_[渠道]_[业务]_[指标] 的命名规范，语义清晰。以下为核心字段分类说明：
1. 评分与基础标识
| 字段名 | 含义 | 说明 |
|---|---|---|
| flag | 查得标识 | 0：查无；1：查得 |
| ppcm_behav_score | 支付行为评分 | 范围[300, 900]，分数越高风险越低；-1表示未命中 |
2. 借贷查验统计（多头申请风险）
时间窗口：d7(7天), m1(1月), m3(3月), m6(6月), m12(1年), m24(2年)
| 字段名 | 含义 | 说明/适用类型 |
|---|---|---|
| ppcm_d7_qynum | 近7天总查验次数 | 反映用户近期的资金紧缺程度 |
| ppcm_m1_bank_qynum | 近1个月在银行的查验次数 | 银行渠道的申请活跃度 |
| ppcm_m3_nbank_fin_qynum | 近3个月在消费金融的查验次数 | 消金渠道的申请活跃度 |
| ppcm_m3_qynum_avg | 近3个月月均查验次数 | 反映申请行为的平均密度 |
| ppcm_latest_qytoday | 最近一次查验距今天数 | 离散值(如1代表0-7天)，判断申请是否刚发生 |
3. 借款与放款统计（共债规模）
| 字段名 | 含义 | 说明/适用类型 |
|---|---|---|
| ppcm_m1_loannum | 近1个月总借款次数 | 实际借款成功的笔数 |
| ppcm_d7_loanamt | 近7天借款等级 | 1-23级，数字越大代表借款金额越高 |
| ppcm_m12_loanorg | 近1年总借款机构数 | 反映借贷来源的分散度（共债机构数） |
| ppcm_m1_loanorg_new | 近1个月总新增借款机构数 | 新增负债渠道，预警借新还旧 |
4. 还款行为与逾期风险（履约能力）
| 字段名 | 含义 | 说明/适用类型 |
|---|---|---|
| ppcm_m12_succ_repnum | 近1年总还款成功次数 | 长期履约行为的证明 |
| ppcm_m3_overnum | 近3个月总逾期次数 | 核心风险指标，近期是否有违约 |
| ppcm_m6_p1_overamt | 近6个月M1(30天内)逾期等级 | 轻度逾期的金额规模 |
| ppcm_m6_p4_overamt | 近6个月M4+(90天以上)逾期等级 | 严重坏账/黑名单风险等级 |
| ppcm_m1_fail_neh_repnum_ratio | 近1个月还款失败(余额不足)占比 | [0,1]，反映资金链紧张导致的扣款失败 |
5. 趋势比率分析（行为突变）
| 字段名 | 含义 | 说明/适用类型 |
|---|---|---|
| ppcm_d7_m12_qynum_ratio | 近7天/近1年查验次数比 | 若比值过高，说明近期申请行为异常激增 |
| ppcm_m1_qy_rep_ratio | 近1个月查贷比 | (查验次数/借贷次数)，反映申请通过率 |
五、应用价值分析
1. 贷前反欺诈与准入
通过 天远API 的 ppcm_d7_qynum（7天内多头申请）和 flag 字段，开发者可以在用户注册或申请的第一时间进行拦截。如果一个用户在短期内（d7）频繁在多个非银机构（nbank_fin）发起查询，往往意味着极高的欺诈或共债风险。
2. 精细化额度审批
结合 ppcm_behav_score（行为分）与 ppcm_m12_succ_repamt（还款能力等级），系统可以实现差异化定额。对于评分高且长期还款记录良好的用户，可自动审批更高额度；对于 ppcm_m1_fail_neh_repnum_ratio（余额不足失败率）较高的用户，则应收紧额度。
3. 贷后存量客户预警
在贷后管理中，定期调用此API监控存量客户。一旦发现 ppcm_m3_overnum（逾期次数）出现正值，或 ppcm_m1_loanorg_new（新增借款机构）突然增加，系统应立即触发预警，提示风控人员介入，防止坏账发生。
六、总结
"信贷行为数据洞察"API 是连接金融数据与业务决策的桥梁。它不仅提供了覆盖银行、消金等多渠道的全量借贷数据，还通过科学的特征工程将原始数据转化为可直接用于模型的评分与比率指标。
对于开发者而言，集成 天远API 意味着能够快速获得行业领先的风控能力。无论是构建实时的审批系统，还是搭建复杂的贷后预警模型，该接口提供的数据维度都足以支撑起企业级的数据分析需求。建议在接入过程中，充分利用 ppcm_ 体系的规范性，建立自动化的特征映射流程，最大化数据的应用价值。
七、数据合规与隐私安全声明
无论是使用 Python、Java、PHP 还是 Go 语言接入 天远API，技术实现仅仅是数据赋能业务的起点。在利用 信贷行为数据洞察 等涉及个人信用的高敏感度接口进行风控决策时，数据合规与隐私保护 始终是企业不可逾越的红线。
天远数据严格遵循《个人信息保护法》及相关法律法规，要求开发者在调用接口时必须确保已获得用户的明确授权（即请求参数中 authorized 必须为 1，且保留真实的授权凭证）。我们强烈建议企业在数据采集、传输（全程加密）及存储的全生命周期中建立严格的隐私保护机制。这不仅是满足监管合规的基本要求，更是构建用户信任、保障企业业务长期稳健发展的基石。
