实战：三分钟掌握天远数据个人信用分API接口（JRZQ0L85）的调用与解析

一、 "个人信用分" API

在消费金融、信贷审批、P2P网贷、融资租赁以及担保评估等众多场景中，快速准确地评估个人信用风险是进行贷前准入和风险决策的关键依据。天远API 平台提供的 "个人信用分" API (JRZQ0L85)，能够通过多头趋势、借贷、流量、社交及设备等多维度数据，利用AI机器学习模型，产出一个[300-900]的综合信用分数。本文将作为一份详细的开发文档，深入剖析此API，详细解读其数据传输机制、请求结构和核心字段含义，帮助开发者利用个人综合信用大数据进行更深层次的数据分析与企业风险管理应用集成。

二、 API接口调用示例

1. 调用说明

• 请求方式: POST

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

• 请求头 (Headers): 必须包含 Access-Id，用于身份验证。

• 安全机制 (Body):

  • 所有业务参数（姓名、身份证、手机号）必须组合成一个JSON字符串。
  • 该JSON字符串随后通过 AES-128-CBC 模式加密。
  • 加密时使用16字节的随机IV（初始化向量）。
  • 最终传输的数据为：Base64(IV + 密文)。
  • 此Base64字符串被放入请求体的 data 字段中。

2. cURL 示例

此示例展示了如何使用cURL发送一个已加密的请求。data 字段的值是您在本地根据加密机制生成的最终Base64字符串。

Bash

# 请将 YOUR_ACCESS_ID 替换为您的 Access-Id
# 请将 YOUR_BASE64_ENCRYPTED_DATA 替换为您生成的加密数据
# 请将 13_DIGIT_TIMESTAMP 替换为当前的13位毫秒时间戳

curl -X POST "<https://api.tianyuanapi.com/api/v1/JRZQ0L85?t=13_DIGIT_TIMESTAMP>" \
-H "Content-Type: application/json" \
-H "Access-Id: YOUR_ACCESS_ID" \
-d '{
    "data": "YOUR_BASE64_ENCRYPTED_DATA"
}'

3. Python 示例 (Requests)

这是一个完整的Python调用示例，包含了加密和解密的逻辑占位符。在实际使用中，您需要使用 pycryptodome 库来实现AES加解密。

Python

import requests
import json
import time
import base64
# 实际开发中需要安装 pycryptodome 库
# pip install pycryptodome
from Crypto.Cipher import AES
from Crypto.Util.Padding import pad, unpad
from Crypto.Random import get_random_bytes

# --- 1. 配置您的API凭证 ---
ACCESS_ID = "YOUR_ACCESS_ID"
# 密钥 (Access Key) 是16进制字符串，需转换为16字节的bytes
ACCESS_KEY_HEX = "YOUR_16_BYTE_ACCESS_KEY_HEX"
ACCESS_KEY = bytes.fromhex(ACCESS_KEY_HEX)

# API端点
API_ENDPOINT = "<https://api.tianyuanapi.com/api/v1/JRZQ0L85>"

# --- 2. 加密辅助函数 (AES-128-CBC) ---
def encrypt_data(plain_text, key):
    """
    加密业务数据
    """
    try:
        # 1. 将明文JSON转为bytes
        plain_bytes = plain_text.encode('utf-8')
        
        # 2. 生成16字节的随机IV
        iv = get_random_bytes(16)
        
        # 3. 创建AES-CBC加密器
        cipher = AES.new(key, AES.MODE_CBC, iv)
        
        # 4. 对明文进行PKCS7填充并加密
        padded_data = pad(plain_bytes, AES.block_size, style='pkcs7')
        cipher_text = cipher.encrypt(padded_data)
        
        # 5. 拼接 IV 和 密文
        encrypted_data_with_iv = iv + cipher_text
        
        # 6. Base64编码
        return base64.b64encode(encrypted_data_with_iv).decode('utf-8')
        
    except Exception as e:
        print(f"加密失败: {e}")
        return None

# --- 3. 解密辅助函数 (AES-128-CBC) ---
def decrypt_data(base64_data, key):
    """
    解密响应数据
    """
    try:
        # 1. Base64解码
        encrypted_data_with_iv = base64.b64decode(base64_data)
        
        # 2. 提取 IV (前16字节)
        iv = encrypted_data_with_iv[:16]
        
        # 3. 提取密文 (16字节之后)
        cipher_text = encrypted_data_with_iv[16:]
        
        # 4. 创建AES-CBC解密器
        cipher = AES.new(key, AES.MODE_CBC, iv)
        
        # 5. 解密并去除填充
        decrypted_padded_data = cipher.decrypt(cipher_text)
        original_data = unpad(decrypted_padded_data, AES.block_size, style='pkcs7')
        
        # 6. 转为JSON对象
        return json.loads(original_data.decode('utf-8'))
        
    except Exception as e:
        print(f"解密失败: {e}")
        return None

# --- 4. 主调用逻辑 ---
def get_credit_score(name, id_card, mobile_no):
    
    # 构造13位时间戳
    timestamp = str(int(time.time() * 1000))
    url = f"{API_ENDPOINT}?t={timestamp}"
    
    headers = {
        "Content-Type": "application/json",
        "Access-Id": ACCESS_ID
    }
    
    # 构造请求明文
    request_payload = {
        "name": name,
        "id_card": id_card,
        "mobile_no": mobile_no
    }
    
    # 加密
    encrypted_str = encrypt_data(json.dumps(request_payload), ACCESS_KEY)
    if not encrypted_str:
        print("加密请求数据时出错")
        return

    # 构造最终请求体
    final_request_body = {
        "data": encrypted_str
    }
    
    try:
        # 发送POST请求
        response = requests.post(url, headers=headers, data=json.dumps(final_request_body))
        response.raise_for_status() # 如果HTTP状态码不是200，则引发异常
        
        # 解析公共响应
        common_response = response.json()
        transaction_id = common_response.get("transaction_id", "N/A")
        print(f"请求流水号: {transaction_id}")

        # 检查业务状态码
        if common_response.get("code") == 0:
            print("业务成功 (code: 0)")
            # 解密业务数据
            encrypted_biz_data = common_response.get("data")
            if encrypted_biz_data:
                decrypted_result = decrypt_data(encrypted_biz_data, ACCESS_KEY)
                print("--- 解密后的业务数据 ---")
                print(json.dumps(decrypted_result, indent=4, ensure_ascii=False))
            else:
                print("业务成功，但未返回加密数据。")
        else:
            # 处理业务失败或错误码
            print(f"业务失败 (code: {common_response.get('code')})")
            print(f"错误信息: {common_response.get('message')}")

    except requests.exceptions.RequestException as e:
        print(f"HTTP请求失败: {e}")
    except json.JSONDecodeError:
        print("解析响应失败，非JSON格式")
    except Exception as e:
        print(f"发生未知错误: {e}")

# --- 5. 执行调用 ---
if __name__ == "__main__":
    # 使用示例数据调用 (请替换为真实数据进行测试)
    get_credit_score("张三", "110101199003071234", "13800138000")

三、 核心数据结构解析

此API的数据交互遵循“加密请求，加密响应”的安全模式。

1. 请求数据流

开发者构建的原始业务数据（JSON明文）经过加密和编码后，作为data字段的值，内嵌在最终的请求体中。

[步骤1: 业务明文]
{
    "mobile_no": "string",
    "id_card": "string",
    "name": "string"
}
   |
   V
[步骤2: AES-128-CBC 加密 (IV + 密文)]
   |
   V
[步骤3: Base64 编码]
"xxxx(base64)"
   |
   V
[步骤4: 最终请求体]
{
    "data": "xxxx(base64)"
}

2. 响应数据流

服务器返回的响应中，data字段同样是加密的Base64字符串。开发者需要先检查code是否为0（业务成功），然后再对data字段执行解密流程。

[步骤1: 原始响应 (服务器返回)]
{
    "code": 0,
    "message": "业务成功",
    "transaction_id": "fl1234567890abcdef",
    "data": "yyyy(base64)" // 加密的业务数据
}
   |
   V
[步骤2: 提取 "data" 字段, Base64 解码]
   |
   V
[步骤3: AES-128-CBC 解密 (使用相同的Key)]
   |
   V
[步骤4: 业务明文 (JSON)]
{
    "score_120_General": "480"
}

四、 字段详解

1. 请求头 (Request Headers)

字段名	类型	必填	描述
Access-Id	string	是	平台分配的账号 Access-Id，用于标识调用者身份。
Content-Type	string	是	固定值为 application/json。

2. 请求业务参数 (Request Body - data 加密前)

以下字段用于构建加密前的JSON明文。

字段名	类型	必填	描述
mobile_no	string	是	手机号（11位标准号码）
id_card	string	是	身份证号（15或18位）
name	string	是	姓名

3. 公共响应参数 (Common Response)

无论业务成功或失败，API均会返回以下公共参数。

字段名	类型	描述
code	int	业务状态码。0 表示业务成功，其他值表示失败或异常。
message	string	状态码的描述信息。
transaction_id	string	唯一流水号，用于问题排查和对账。
data	string	业务响应数据。注意： 当 code 为 0 时，此字段为AES加密的Base64字符串；当 code 不为 0 时，此字段可能为空或不返回。

4. 业务响应参数 (Business Response - data 解密后)

当 code 为 0 时，解密 data 字段可得到以下JSON结构。

字段名	类型	描述
score_120_General	string	个人信用分。范围 [300-900]，分数越高，信用越好。如果返回 -1，表示未命中或无法评估。

5. 错误码 (Error Codes)

当公共响应中的 code 不为 0 时，代表接口调用异常或业务失败。

code	message	描述
0	业务成功	请求成功，且 data 字段包含加密的有效数据。
1000	查询为空	成功查询，但未命中该用户数据（此时 data 解密后 score_120_General 通常为 -1）。
1001	接口异常	服务器内部错误，请稍后重试或联系技术支持。
1002	参数解密失败	服务器无法解密 data 字段。请检查您的AES密钥、IV生成或填充方式是否正确。
1003	基础参数校验不正确	检查 Access-Id 或时间戳 t 是否缺失或格式错误。
1004	未经授权的IP	调用IP未在平台IP白名单中。
1005	缺少Access-Id	请求头中未包含 Access-Id 字段。
1006	未经授权的AccessId	Access-Id 无效或已被禁用。
1007	账户余额不足，无法请求	账户余额不足，请及时充值。
1008	未开通此产品	该 Access-Id 未开通 JRZQ0L85 接口的调用权限。
2001	业务失败	因其他业务逻辑（如参数不合规等）导致的失败。

五、 应用价值分析

个人信用分 (JRZQ0L85) API的核心价值在于提供了一个快速、量化的风险评估标准，帮助企业实现自动化和智能化的风险控制。

1. 核心应用场景

• 贷前准入策略:

  在信贷申请的第一道防线，企业可使用此分数进行快速筛选。例如，根据提供方的建议策略：

  • score < 450：高风险客群，系统可自动拒绝，减少人工审核成本。
  • score > 650：优质客群，可进入快速审批通道，提升用户体验。
  • 450 < score < 650：中等风险客群，转入人工审核或要求补充更多材料。

• 风险定价与差异化服务:

  金融机构可以根据信用分数的高低，对不同客户群体实行差异化的利率定价或授信额度。分数越高的客户，可享受越低的利率和越高的额度。

• 存量客户风险监控:

  对于已放款的客户，可定期（如每季度）调用此接口，监控其信用分数变化。若分数显著下降，可触发预警机制，及时采取催收或调整额度等贷后管理措施。

2. 系统集成建议

天远API 的 JRZQ0L85 接口可以轻松集成到企业现有的风险管理系统（RMS）、客户关系管理系统（CRM）或自动化审批流中。

建议在调用此API前，先通过身份验证API（如身份证二要素）确认用户身份的真实性，再将真实的姓名、身份证、手机号传入本接口，以保证信用评估的准确性。

个人信用分API (JRZQ0L85) 是风险管理体系中的重要工具。它通过先进的AI模型，将复杂的多维度数据转化为一个直观的[300-900]分数，极大地简化了企业的风险识别流程。开发者在接入时，应重点关注AES-128-CBC的加密和解密实现，确保 IV 的随机性和 PKCS7 填充的正确性。通过合理利用此API代码，企业能够有效降低信用风险，优化审批效率，实现精细化运营。