天远API支付行为指数接口集成指南：Python代码示例与数据结构解析

一、API功能综述与应用背景

在线上信贷实时审批、贷后风险监控与预警、客户分层与差异化定价等众多场景中，多维度的信用量化评估是进行精准风险决策的关键依据。"支付行为指数"API，能够基于用户的历史借贷全周期数据，按多时间窗口、多渠道及多业务类型进行细粒度统计与建模，输出包括行为评分在内的高价值数据。

本文将作为一份详细的开发文档，深入剖析此API，详细解读其返回的原始数据结构和每一个核心字段的含义，帮助开发者利用借贷全周期大数据进行更深层次的数据分析与企业智能风控应用集成。作为天远API旗下极具竞争力的风控数据产品，该接口通过标准化的数据输出，为金融科技开发者提供了强大的信用评估工具。

二、API接口调用示例

1. 调用说明

本接口采用高安全性的加密传输机制，确保敏感数据安全。

• 接口地址：https://api.tianyuanapi.com/api/v1/JRZQ3C9R?t={13位时间戳}

• 请求方式：POST

• 安全机制：

  • 身份验证：请求头需携带 Access-Id。
  • 数据加密：请求参数需通过 AES-128-CBC 算法加密并进行 Base64 编码，封装在 data 字段中。响应数据同样以加密形式返回。

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": "11010119900101xxxx", "name": "张三", "phone": "13800138xxx", "authorized": "1"}

3. Python requests 调用示例

以下代码展示了完整的调用流程，包括加密占位符、请求发送、响应解密及错误处理。

import requests
import json
import time
import base64

# ================= 配置区域 =================
# 接口地址 (需拼接时间戳)
API_BASE_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 PaymentIndexSDK:
    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. 将 data_dict 转换为 JSON 字符串
        2. 生成随机 IV (16字节)
        3. 使用 AES-CBC 模式加密 (PKCS7填充)
        4. 拼接 IV + 密文
        5. 进行 Base64 编码
        """
        print(f"[加密] 正在加密请求参数: {data_dict.keys()}")
        # 模拟返回加密字符串
        return "MOCK_ENCRYPTED_BASE64_STRING_======="

    def decrypt_data(self, encrypted_str):
        """
        AES-128-CBC 解密函数 (占位符)

        真实逻辑：
        1. Base64 解码
        2. 提取前16字节 IV
        3. 使用 AES-CBC 模式解密剩余密文
        4. 去除 PKCS7 填充
        5. 解析 JSON
        """
        print(f"[解密] 收到响应数据，长度: {len(encrypted_str)}")
        # 模拟解密后的数据结构
        return {
            "flag": 1,
            "ppcm_behav_score": 720,
            "ppcm_d7_qynum": 2,
            "ppcm_m3_overnum": 0,
            "message": "解密成功"
        }

    def get_payment_behavior_index(self, name, id_card, phone):
        """
        调用支付行为指数API
        """
        # 1. 准备时间戳
        timestamp = int(time.time() * 1000)
        url = f"{API_BASE_URL}?t={timestamp}"

        headers = {
            "Access-Id": self.access_id,
            "Content-Type": "application/json"
        }

        # 2. 构造原始参数
        payload = {
            "name": name,
            "idCard": id_card,
            "phone": phone,
            "authorized": "1" # 必须获得用户授权
        }

        try:
            # 3. 加密参数
            encrypted_payload = self.encrypt_data(payload)
            body = {"data": encrypted_payload}

            # 4. 发送请求
            print(f"正在请求接口: {url}")
            response = requests.post(url, headers=headers, json=body, timeout=10)

            # 5. 处理响应
            if response.status_code == 200:
                res_json = response.json()

                # 检查业务状态码
                if res_json.get("code") == "200":
                    # 获取加密的 data 字段
                    encrypted_res_data = res_json.get("data")

                    # 6. 解密响应数据
                    # 根据实际情况，如果已经是对象则直接返回，如果是字符串则解密
                    if isinstance(encrypted_res_data, str):
                        return self.decrypt_data(encrypted_res_data)
                    return encrypted_res_data
                else:
                    print(f"业务错误: {res_json.get('message')} (Code: {res_json.get('code')})")
                    return None
            else:
                print(f"HTTP请求失败: {response.status_code}")
                return None

        except Exception as e:
            print(f"调用过程发生异常: {e}")
            return None

if __name__ == "__main__":
    # 初始化 SDK
    sdk = PaymentIndexSDK(ACCESS_ID, ACCESS_KEY)

    # 发起调用
    result = sdk.get_payment_behavior_index("李四", "11010119900101xxxx", "1390000xxxx")

    if result:
        print("\n=== 支付行为指数API 调用结果 ===")
        print(json.dumps(result, indent=4, ensure_ascii=False))

三、核心数据结构解析

响应数据经过解密后，是一个包含丰富维度的 JSON 对象。理解其数据结构对于风控特征工程至关重要。

• 数据位置：核心业务数据位于响应体 data 字段解密后的对象中。

• 数据模块：

  • 标识与评分：如 flag (查得标识) 和 ppcm_behav_score (支付行为评分)。
  • 时间窗口统计：覆盖 d7 (7天), m1 (1个月), m3, m6, m12, m24 (24个月) 的多维度统计。
  • 业务类型统计：细分为 查验 (qy) 、借款 (loan) 、还款 (rep) 、逾期 (over) 四大类。

• 特殊值说明：

  • 1：表示该维度无数据（未命中），在特征处理时需注意区分“0”和“-1”。
  • 小数：通常表示比率（Ratio）或均值（Avg）。

四、字段详解

本接口返回字段采用结构化命名 ppcm_[时间段]_[渠道]_[业务]_[指标]，以下按功能模块分类解析关键字段。

1. 综合评分与基础标识

字段名	含义	说明
flag	查得标识	0：查无；1：查得
ppcm_behav_score	支付行为评分	范围 [300, 900]，分数越高风险越低；-1 表示未命中

2. 查验行为统计 (Query Behavior)

反映用户的借款意愿与资金紧缺程度

字段名	含义	说明/适用类型
ppcm_d7_qynum	近7天总查验次数	高危指标，反映短期多头申请情况
ppcm_m1_bank_qynum	近1个月在银行的查验次数	银行渠道的申请活跃度
ppcm_m3_nbank_fin_qynum	近3个月在消费金融的查验次数	非银机构的申请活跃度
ppcm_latest_qytoday	最近一次查验距今天数	离散区间值 (如1代表0-7天)，判断申请是否刚发生

3. 还款与逾期风险 (Repayment & Overdue)

反映用户的履约能力与信用状况

字段名	含义	说明/适用类型
ppcm_m12_succ_repnum	近1年总还款成功次数	长期良好还款习惯的证明
ppcm_m3_overnum	近3个月总逾期次数	核心风险指标，近期是否存在违约
ppcm_m1_fail_neh_repnum_ratio	近1个月还款失败(余额不足)占比	[0,1]，反映资金链紧张程度
ppcm_m6_p4_overamt	近6个月M4+(90天以上)逾期等级	严重坏账或黑名单风险等级

4. 借款与共债分析 (Loan & Debt)

字段名	含义	说明/适用类型
ppcm_m1_loannum	近1个月总借款次数	实际发生的放款笔数
ppcm_d7_loanamt	近7天借款等级	1-23级，数字越大金额越高
ppcm_m12_loanorg	近1年总借款机构数	衡量共债广度（在多少家机构借款）
ppcm_m1_loanorg_new	近1个月总新增借款机构数	是否存在“借新还旧”的迹象

五、应用价值分析

通过集成天远API的支付行为指数，企业可以在信贷全生命周期中挖掘数据的深度价值：

1. 智能评分模型构建：

   • 直接利用 ppcm_behav_score 作为基准分，或将 ppcm_m12_succ_repnum（还款成功数）与 ppcm_m3_overnum（逾期数）作为核心特征（Feature），训练自有的机器学习风控模型，提升模型的KS值（区分度）。

2. 差异化定价策略：

   • 对于 ppcm_behav_score 高且 ppcm_m12_loanorg（共债机构）少的优质用户，可提供更低的利率和更高的额度，提升用户留存率。
   • 对于 ppcm_d7_qynum（短期查询）激增的用户，系统可自动降额或要求补充资料。

3. 贷后预警系统集成：

   • 实时监控存量客户的 ppcm_m1_fail_neh_repnum_ratio（余额不足失败率）。一旦该指标异常升高，系统自动触发预警任务，提示催收人员提前介入，降低坏账风险。

六、集成建议与最佳实践

"支付行为指数"API 是一款专为金融风控场景设计的硬核数据产品。它不仅仅提供了一个简单的分数，而是通过数百个细粒度的行为指标，还原了用户在不同时间窗口、不同机构间的借贷全貌。

对于开发者而言，该接口的接入流程标准化程度高，字段命名规范清晰（ppcm_体系），极大地降低了数据清洗与对接的成本。建议在实际开发中，充分利用 天远API 返回的 -1 标识机制来处理稀疏数据，并将API数据实时注入到企业的决策引擎中，构建起坚不可摧的数字化风控防线。

七、数据合规与隐私安全声明

无论是使用 Python、Java、PHP 还是 Go 语言接入 天远API，技术实现仅仅是数据赋能业务的起点。在利用 信贷行为数据洞察 等涉及个人信用的高敏感度接口进行风控决策时，数据合规与隐私保护 始终是企业不可逾越的红线。

天远数据严格遵循《个人信息保护法》及相关法律法规，要求开发者在调用接口时必须确保已获得用户的明确授权（即请求参数中 authorized 必须为 1，且保留真实的授权凭证）。我们强烈建议企业在数据采集、传输（全程加密）及存储的全生命周期中建立严格的隐私保护机制。这不仅是满足监管合规的基本要求，更是构建用户信任、保障企业业务长期稳健发展的基石。