** Python集成企业司法涉诉API：构建合规审查自动化的企业级实战 (腾讯云版)
在商业合作、供应链准入、信贷授信以及投融资场景中，全面了解目标企业的司法涉诉情况是风控的核心环节。传统的人工背调不仅耗时费力，且往往只能获取表面信息，难以追踪复杂的案件串联关系、金额纠纷及潜在的失信或限高风险。 该平台提供的企业司法涉诉API，为企业级风控系统提供了一站式的数据核验解决方案。通过接入该接口，开发者可以在传入企业名称及授权文件后，直接获取目标企业在民事、刑事、行政、执行等多个维度的诉讼详情。系统直连的穿透能力，使得将“司法审查”无缝嵌入到自动化审批流程中成为可能，大幅提升了风控决策的客观性与时效性。 ## Python 加密通信集成：构建高可用审核管道 本接口在设计上强制要求对业务负载（Payload）进行加密传输，并传递 Base64 格式的授权文件，这对数据的一致性与客户端代码的健壮性提出了要求。 ### 1. 核心参数与加密配置 - **接口地址**: `https://api.haiyudata.com/api/v1/JRZQ2PV2` (需附加 `?t=13位时间戳`) - **请求方式**: `POST` - **请求头**: 需包含 `Access-Id` 并在载荷中使用 `Content-Type: application/json`。 - **关键入参**: - `ent_name` (必填，String): 目标查询的企业名。 - `auth_authorize_file_base64` (必填，String): 授权书 PDF 文件的 Base64 编码数据，文件大小不得超过 500KB。 - **鉴权与加密机制**: 使用账户的 16 进制 Access Key 作为密钥，采用 AES-128 算法的 CBC 模式。每次请求需动态生成 16 字节的 IV（初始化向量），并配合 PKCS7 填充，最终将 IV 与密文拼接后进行 Base64 编码，放入 `data` 字段中请求。 ### 2. 标准化调用代码 (Python) ```python import json import base64 import time import requests import os from Crypto.Cipher import AES from Crypto.Util.Padding import pad, unpad class JudicialRiskClient: def __init__(self, access_id, access_key_hex): self.base_url = "https://api.haiyudata.com/api/v1/JRZQ2PV2" self.access_id = access_id # 确保 16 进制密钥转换为 16 字节的 bytes 类型 self.access_key = bytes.fromhex(access_key_hex) if len(self.access_key) != 16: raise ValueError("Access Key 必须为 16 字节") self.headers = { "Access-Id": self.access_id, "Content-Type": "application/json" } def _encrypt_data(self, raw_payload): iv = os.urandom(16) cipher = AES.new(self.access_key, AES.MODE_CBC, iv) ct_bytes = cipher.encrypt(pad(raw_payload.encode('utf-8'), AES.block_size)) return base64.b64encode(iv + ct_bytes).decode('utf-8') def _decrypt_data(self, encrypted_b64): try: raw = base64.b64decode(encrypted_b64) iv = raw[:16] ct = raw[16:] cipher = AES.new(self.access_key, AES.MODE_CBC, iv) pt = unpad(cipher.decrypt(ct), AES.block_size) return json.loads(pt.decode('utf-8')) except Exception as e: print(f"数据解密或解析异常: {e}") return None def execute_query(self, ent_name, auth_pdf_path): # 读取并编码授权文件 with open(auth_pdf_path, 'rb') as f: pdf_b64 = base64.b64encode(f.read()).decode('utf-8') timestamp = int(time.time() * 1000) url = f"{self.base_url}?t={timestamp}" params = { "ent_name": ent_name, "auth_authorize_file_base64": pdf_b64 } body = {"data": self._encrypt_data(json.dumps(params))} try: resp = requests.post(url, headers=self.headers, json=body, timeout=10) resp.raise_for_status() res_json = resp.json() # 判断有效载荷，由业务方决定成功状态 if res_json.get("data"): decrypted = self._decrypt_data(res_json.get("data")) return {"tx_id": res_json.get("transaction_id"), "result": decrypted, "code": res_json.get("code")} else: return {"error": res_json.get('message'), "code": res_json.get("code")} except requests.exceptions.RequestException as e: print(f"网络通信失败: {e}") return None # --- 调用示例 --- if __name__ == "__main__": client = JudicialRiskClient(os.getenv("API_ACCESS_ID"), os.getenv("API_ACCESS_KEY")) report = client.execute_query(ent_name="测试科技有限公司", auth_pdf_path="dummy_auth.pdf") if report and "result" in report: print(f"核验流水号: {report['tx_id']}") # 保护敏感数据，不直接输出全量明文 print("已获取企业涉诉信息") ``` ### 3. 终端验证 ```bash curl -X POST "https://api.haiyudata.com/api/v1/JRZQ2PV2?t=1710748432000" \ -H "Access-Id: YOUR_ACCESS_ID" \ -H "Content-Type: application/json" \ -d '{"data": "'$ENCRYPTED_DATA'"}' ``` > **提示**：为安全起见，`$ENCRYPTED_DATA` 应当由前述代码生成的密文经环境变量注入，不建议在此直接粘贴含有敏感参数的密文。时间戳必须动态生成，确保防重放保护有效。 ## 返回数据对照与解读 接口公共响应层包含 `code`、`message` 和 `transaction_id`，而业务核心数据全部封装在 `data` 字段内的加密串中。解密后，开发者可获得包括 `ss` (涉诉信息)、`sxbzxr` (失信被执行人) 和 `xgbzxr` (限制消费人员) 在内的深层分析。 ### 关键字段解析 | **参数代码** | **字段说明** | **数据类型** | **开发者注意 (业务映射建议)** | | --- | --- | --- | --- | | `ss.count.count_total` | 案件总数 | INT | **整体风险评估指标**。反映企业的涉诉活跃度，数值过高通常触发预警规则，需进一步查看原告/被告分布。 | | `ss.count.money_wei_total` | 未结案金额等级 | INT | **资金冻结风险**。该字段以等级形式返回，需映射为对应的金额区间。作为授信评估的负面指标直接影响信用评分。 | | `ss.*.cases.n_laay_tag` | 立案案由标签 | STRING | 用于过滤如“合同纠纷”、“劳动仲裁”等特定类型的业务风险，有助于精确定位业务影响面。 | | `sxbzxr[].xwqx` | 失信具体情形 | STRING | **强违约信号**。一旦该数组不为空，通常在审批流中属于“一票否决”或“转入强人工干预”的高风险状态。 | | `xgbzxr[].ah` | 限高案号 | STRING | 结合发布时间使用，判断限制消费状态是否仍然活跃。 | > **技术提示**：解析金额和数量等数值时注意空值与默认 0 的处理；日志保存时应对涉诉当事人的真实姓名、统一社会信用代码及敏感案号进行脱敏，遵循数据最小化存储原则。 ## 应用场景 结合接口返回的全景式司法数据，可以赋能以下核心业务场景： ### 1. 供应链准入自动化风控 在招投标或供应商入库阶段，系统可通过调用本接口查询供应商涉诉情况。通过提取 `ss.count.count_beigao` (被告总数) 和 `sxbzxr` (失信名单)，若发现企业作为被告的未结案件超过阈值或被列入失信被执行人名单，自动化风控引擎即可直接阻断准入流程，防范后续履约风险。该接口主要作为辅助评估手段，最终决策结合企业实地考察。 ### 2. 商业信贷授信辅助决策 在金融授信审批节点，风控平台可利用 `ss.count.money_wei_total` (未结案金额等级) 评估企业当前的或有负债压力。该数据作为辅助决策变量输入信用评估模型中，协助判定是否调整授信额度。系统并不会单纯依赖该数据直接完成放款或拒签，而是结合内部财务分析报告与人工复核，形成严谨的审批闭环。 ## 安全与合规边界 在生产环境中处理企业司法及相关敏感数据时，技术团队应坚守以下合规红线： 1. **强授权基础**：由于入参必须包含 `auth_authorize_file_base64`（授权文件），调用方务必确保该文件真实合法，严禁在未取得企业明示授权前擅自进行静默数据查询。 2. **端到端加密机制**：AES-128 CBC 的加密传输保障了数据在网络层的不可见性，但落地系统后，相关的加密凭据 (Access-Id/Key) 必须通过云端 KMS 或环境变量隔离，禁止硬编码或泄露于前端。 3. **数据最小化利用**：司法数据仅用于约定的风控辅助评估，严禁挪作他用。系统落库记录时建议仅存储流水号和决策结果，敏感案件明细信息定期销毁，避免造成数据合规隐患。
