深度解析天远API组合包：一站式获取企业主司法、借贷与关联企业数据的 Python 实现

一、一站式解决小微企业“信贷盲区”

在小微企业信贷（SME Lending）和供应链金融场景中，核心难点在于“公私难分”。评估一家小微企业的风险，不仅要看企业本身的经营状况，更要深度穿透企业主（法入/实控人）的个人信用。传统的做法需要分别调用工商、司法、个人借贷、黑名单等多个接口，导致系统耦合度高、响应慢、成本高。

天远API 推出的“全能小微企业报告”接口（COMBQN13），采用了先进的API 聚合技术。它仅需传入企业主的身份信息，即可一次性返回以下四大维度的核心数据：

1. 人企关系加强版：验证申请人名下关联的企业及职位。
2. 全景雷达：企业主的个人借贷申请与还款行为评分。
3. 特殊名单验证：法院失信、网贷黑名单筛查。
4. 司法涉诉查询：详细的裁判文书与涉诉金额统计。

本文将作为一份详尽的开发文档，指导开发者使用 Python 对接此聚合接口，解析其特有的 responses 数组结构，帮助企业快速构建高效的小微风控模型。

二、API接口调用示例

本接口采用 AES-128-CBC 加密传输。由于是聚合接口，响应体不再是单一对象，而是一个包含多个子产品结果的列表，开发者需遍历处理。

1. 接口基础信息

• 接口地址：https://api.tianyuanapi.com/api/v1/COMBQN13?t={13位时间戳}
• 请求方式：POST
• 安全机制：Header (Access-Id) + Body (data 密文)
• 请求参数：name, id_card, mobile_no, authorized (必须传"1")

2. Curl 调用示例

Bash

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

3. Python 完整调用代码 (聚合数据解析)

本示例代码封装了一个 SME_Report_Client，展示了如何发送加密请求，并编写了一个 parse_combined_response 函数，将分散在不同子产品中的关键指标提取到一个扁平的字典中。

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 TianyuanMicroEntAPI:
    def __init__(self, access_id, access_key):
        self.access_id = access_id
        self.access_key = access_key.encode('utf-8')[:16]
        self.api_url = "<https://api.tianyuanapi.com/api/v1/COMBQN13>"

    def _encrypt(self, plain_dict):
        """AES-128-CBC 加密逻辑"""
        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 = cipher.encrypt(pad(plain_text, AES.block_size))
            return base64.b64encode(iv + encrypted).decode('utf-8')
        except Exception as e:
            print(f"[Encryption Error] {e}")
            return None

    def _decrypt(self, base64_str):
        """AES-128-CBC 解密逻辑 (此处暂不涉及响应解密，视具体接口加密策略而定)"""
        # 如果响应Data是加密的，需在此处实现解密，逻辑同上文
        pass 

    def query_report(self, name, id_card, mobile):
        # 1. 构造请求
        payload = {
            "name": name, 
            "id_card": id_card, 
            "mobile_no": mobile, 
            "authorized": "1"
        }
        encrypted_data = self._encrypt(payload)
        
        # 2. 发起请求
        timestamp = int(time.time() * 1000)
        url = f"{self.api_url}?t={timestamp}"
        headers = {"Access-Id": self.access_id}
        
        try:
            resp = requests.post(url, json={"data": encrypted_data}, headers=headers)
            # 注意：组合包接口通常直接返回 JSON 结构，内部子产品的 data 才是具体的业务数据
            # 若整体响应加密，需先解密外层。此处假设外层直接返回 JSON。
            return resp.json() 
        except Exception as e:
            print(f"Network Error: {e}")
            return None

    def parse_combined_response(self, response_json):
        """
        核心清洗函数：从聚合响应中拆解出四大模块的数据
        """
        if not response_json or "responses" not in response_json:
            print("无效的响应格式")
            return

        summary = {}
        
        # 遍历子产品列表
        for item in response_json.get("responses", []):
            api_code = item.get("api_code")
            data = item.get("data") or {}
            
            if not item.get("success"):
                print(f"子产品 {api_code} 调用失败: {item.get('error')}")
                continue

            # 1. 人企关系 (QYGL3F8E)
            if api_code == "QYGL3F8E":
                companies = data.get("items", [])
                summary["关联企业数"] = len(companies)
                if companies:
                    summary["主关联企业"] = companies[0].get("basicInfo", {}).get("name")

            # 2. 全景雷达 (JRZQ7F1A) - 借贷行为
            elif api_code == "JRZQ7F1A":
                behavior = data.get("behavior_report_detail", {})
                apply = data.get("apply_report_detail", {})
                summary["贷款行为分"] = behavior.get("B22170001", "N/A")
                summary["近6个月逾期金额"] = behavior.get("B22170031", "0")
                summary["申请准入分"] = apply.get("A22160001", "N/A")

            # 3. 特殊名单 (JRZQ8A2D) - 黑名单
            elif api_code == "JRZQ8A2D":
                summary["法院失信命中"] = data.get("id", {}).get("court_bad", "未命中")
                summary["网贷高风险命中"] = data.get("cell", {}).get("nbank_lost_allnum", "0")

            # 4. 司法涉诉 (FLXG7E8F)
            elif api_code == "FLXG7E8F":
                stats = data.get("judicial_data", {}).get("lawsuitStat", {}).get("count", {})
                summary["涉案总金额"] = stats.get("money_total", 0)
                summary["未结案数量"] = stats.get("count_wei_total", 0)

        return summary

# 使用示例
if __name__ == "__main__":
    client = TianyuanMicroEntAPI("YOUR_ACCESS_ID", "YOUR_ACCESS_KEY_HEX")
    raw_res = client.query_report("张三", "110101199001011234", "13800138000")
    
    clean_report = client.parse_combined_response(raw_res)
    print("\n=== 小微企业主综合风险报告 ===")
    for k, v in clean_report.items():
        print(f"{k}: {v}")

三、核心数据结构解析

理解 responses 数组是处理本接口的关键。API 不会直接返回扁平字段，而是按子产品代码隔离数据。

1. 组合包响应结构

JSON

{
  "responses": [
    {
      "api_code": "QYGL3F8E",  // 人企关系
      "success": true,
      "data": { ... }        // 该产品的独有数据结构
    },
    {
      "api_code": "JRZQ7F1A",  // 全景雷达
      "success": true,
      "data": { ... }
    }
    // ... 其他子产品
  ]
}

2. 四大模块核心字段详解

以下表格列出了针对小微企业授信场景中，最需要关注的“红线”指标。

模块 A：人企关系 (QYGL3F8E)

用于验证借款人是否有真实的经营背景。

字段路径	字段含义	说明	风控价值
items[].basicInfo.name	企业名称	关联的企业全称	核对营业执照一致性。
items[].basicInfo.estiblishTime	成立时间	格式 yyyy-mm-dd	成立不满1年的企业风险较高。
items[].basicInfo.regStatus	经营状态	存续/注销/吊销	红线：若为注销/吊销，直接拒单。

模块 B：全景雷达 (JRZQ7F1A)

评估企业主的个人偿债能力与资金压力。

代码	字段名	说明	风控价值
B22170001	贷款行为分	1-1000	类似信用分，越低风险越大。
B22170031	近6个月逾期金额	区间值 (如 [5000,10000))	核心指标，反映近期还款能力。
A22160003	申请命中机构数	计数	多头借贷指标，机构数过多提示资金链紧张。

模块 C：特殊名单 (JRZQ8A2D)

黑名单筛查，一票否决项。

字段名	含义	值域	决策建议
id_court_bad	法院失信人	0:命中, 空:未命中	命中即拒 (老赖)。
id_bank_lost	银行高风险	0:命中, 空:未命中	意味着在银行有严重违约记录。
cell_nbank_lost	非银高风险	0:命中, 空:未命中	网贷/消金黑名单。

模块 D：司法涉诉 (FLXG7E8F)

量化法律风险成本。

字段路径	字段含义	说明	风控价值
count.money_wei_total	未结案金额	数值 (元)	企业主的潜在负债，需计入负债率计算。
count.count_beigao	被告总数	计数	频繁当被告，说明经营纠纷多，经营不稳。

五、应用价值分析

天远API 的全能小微企业报告在以下场景中具有不可替代的优势：

1. 小微贷“秒批”系统：

   传统流程中，信审员需要人工去天眼查搜企业，去执行网搜失信。使用此接口，Python 脚本可以在 1 秒内自动完成“关联企业校验 -> 个人信用评分 -> 黑名单过滤 -> 涉诉金额计算”的全流程，实现自动化审批。

2. 供应链金融准入：

   在核心企业赊销给下游经销商时，调用此接口查询经销商法人的信用。如果发现法人 B22170031 (逾期金额) 较高，且 id_court_executed (被执行人) 命中，说明其个人资金已断裂，极有可能挪用货款，应拒绝赊销。

3. 贷后预警监控：

   定期（如每月）调用接口，重点监控 FLXG7E8F 中的 money_wei_total (未结案金额)。如果发现涉诉金额突然暴增，说明企业主陷入了新的法律纠纷，银行应及时采取保全措施。

六、总结

“全能小微企业报告”API 是天远针对 B 端风控场景的集大成者。它巧妙地通过 API 聚合技术，解决了小微企业风控中“数据分散”的痛点。

对于 Python 开发者，接入的关键在于编写健壮的解析器，能够容错处理个别子产品查询失败的情况（如 success: false），并从深层嵌套的 JSON 中提取出业务所需的“黄金指标”。通过本文的示例，您可以快速将这一强大的数据源集成到您的风控中台中。