Python 接入天远劳动仲裁 API 构建企业风控体系

穿透非标简历黑盒：从盲目背调到数据驱动的合规管理

在现代企业人力资源管理与金融信贷业务中，个人背景的真实性与合法性审查是构筑风控体系的第一道防线。传统的背景调查往往依赖人工核实与候选人主动披露，这种模式不仅效率低下，且极易遗漏关键的法律纠纷记录。特别是频繁产生劳动争议、或身负失信记录的人员，一旦引入企业内部或赋予信贷额度，将给业务带来难以预估的经济损失与名誉风险。

为了解决这一行业痛点，天远劳动仲裁信息查询 API 提供了一套全方位、时效化的法律风险查询机制。该接口专门针对企业招聘背景调查、金融机构信贷审核、合作伙伴资质评估等场景设计。通过输入核心身份信息，系统能够深度聚合该人员的劳动争议、社会保险纠纷、人事争议及失信限高记录，为企业的每一次用人或合作决策提供坚实的数据支撑。

Python 集成实战：AES 加密与高可用请求管道构建

本接口在数据传输层面采用了严格的安全策略，所有业务请求参数均需进行加密处理。加密机制规定使用 AES-128 算法的 CBC 模式，配合 PKCS7 填充，且每次加密需生成随机的 16 字节 IV（初始化向量）。最终传输的数据是将 IV 与密文拼接后进行 Base64 编码的字符串。

下面这段代码展示了如何使用 Python 语言结合 pycryptodome 和 requests 库，优雅地封装这套复杂的加密解密逻辑，并实现具备超时控制与异常捕获的高可用请求类。

1. 核心请求参数配置

• 接口地址: https://api.tianyuanapi.com/api/v1/IVYZ0S0D?t=13 位时间戳
• 请求方式: POST
• 明文入参: id_card (身份证号), name (姓名)

2. 标准化调用代码 (Python)

import json
import base64
import time
import requests
import os
from Crypto.Cipher import AES
from Crypto.Util.Padding import pad, unpad

class LaborArbitrationClient:
    def __init__(self, access_id, access_key_hex):
        """
        初始化天远 API 客户端
        """
        self.base_url = "https://api.tianyuanapi.com/api/v1/IVYZ0S0D"
        self.access_id = access_id
        # 密钥要求为 16 进制字符串，转换为 16 字节 bytes
        self.access_key = bytes.fromhex(access_key_hex)
        self.headers = {
            "Access-Id": self.access_id,
            "Content-Type": "application/json"
        }

    def _encrypt_payload(self, raw_data: dict) -> str:
        """
        AES-128-CBC 加密逻辑
        1. 随机生成 16 字节 IV
        2. PKCS7 填充
        3. 拼接 IV + 密文 -> Base64 编码
        """
        payload_str = json.dumps(raw_data)
        iv = os.urandom(16)  # 每次加密生成随机 IV
        cipher = AES.new(self.access_key, AES.MODE_CBC, iv)
        ct_bytes = cipher.encrypt(pad(payload_str.encode('utf-8'), AES.block_size))
        # 拼接并进行 Base64 编码
        return base64.b64encode(iv + ct_bytes).decode('utf-8')

    def _decrypt_payload(self, encrypted_b64: str) -> dict:
        """
        解密响应数据
        1. Base64 解码
        2. 提取前 16 字节作为 IV
        3. AES-CBC 解密并移除 PKCS7 填充
        """
        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 {}

    def query_arbitration_risk(self, name: str, id_card: str) -> dict:
        """
        发起劳动仲裁风险查询
        """
        # 拼接带有 13 位时间戳的 URL
        timestamp = int(time.time() * 1000)
        url = f"{self.base_url}?t={timestamp}"
        raw_params = {
            "name": name,
            "id_card": id_card
        }
        # 构造加密请求体
        encrypted_data = self._encrypt_payload(raw_params)
        body = {"data": encrypted_data}
        try:
            # 增加超时控制机制
            response = requests.post(url, headers=self.headers, json=body, timeout=10)
            response.raise_for_status()
            res_json = response.json()
            # 校验外层状态码
            if res_json.get("code") == 200:
                # 解密 data 字段内容
                return self._decrypt_payload(res_json.get("data"))
            else:
                print(f"网关错误或业务拒绝：{res_json.get('message')}")
                return {}
        except requests.exceptions.RequestException as req_e:
            print(f"网络层请求失败：{req_e}")
            return {}

# 运行测试
if __name__ == "__main__":
    client = LaborArbitrationClient("YOUR_ACCESS_ID", "YOUR_16_HEX_KEY")
    result = client.query_arbitration_risk(name="张三", id_card="11010519900101XXXX")
    if result:
        print(f"基础风险标记：{result.get('basic_info')}")
        print(f"劳动争议风险：{result.get('labor_disputes')}")

3. Curl 测试命令对照

在进行代码开发前，建议通过 Shell 终端快速验证网络与账户连通性（注意：data 字段需填入已加密的 Base64 字符串）：

curl -X POST "https://api.tianyuanapi.com/api/v1/IVYZ0S0D?t=1708811111000" \
-H "Access-Id: YOUR_ACCESS_ID" \
-H "Content-Type: application/json" \
-d '{"data": "ENCRYPTED_BASE64_STRING_HERE"}'

风险数据模型穿透：多维诉讼指标深度解析

解密后的 result 返回内容是一个高度结构化的扁平对象，覆盖了从基础风险到多维度纠纷的具体状态。接口通过严格的枚举值（1 代表无风险，2 代表命中风险）对结果进行量化。以下是开发者在入库和制定规则引擎时需要重点关注的核心字段：

字段名称	参数 Key	业务含义	开发者注意
基础风险总览	basic_info	评估该人员是否有任何维度的潜在风险	核心路由字段。若为 1，业务流可直接放行；若为 2，需继续解析后续的具体风险点进行拦截或人工复审。
失信人员风险	dishonesty	判断是否被纳入失信被执行人名单	高危红线指标。在金融信贷审核场景下，一旦命中此项（返回 2），建议直接触发系统的一票否决（Decline）策略。
劳动争议风险	labor_disputes	包含劳动合同、薪资报酬、经济补偿等纠纷	需结合 labor_disputes_3y 和 labor_disputes_5y 进行时效性衰减计算。3 年内发生的争议对当前背调的影响权重应高于 5 年前。
社会保险纠纷	social_insurance	涉及养老、工伤、医疗等险种争议	招聘特殊工种（如高危作业、物流配送）时需重点关注其中的 injury_insurance (工伤保险待遇纠纷)。
通知函时效	notice_letter_period	记录仲裁、调解、涉诉距今的时间周期	枚举值说明：0-无，1-近 2 年，2-2~4 年，3-5 年以上。建议将时间距今越近的数据赋予越高的风险预警级别。

技术提示：该接口采用异步历史溯源机制，每个风险项不仅提供当前状态，还精细划分了'近 3 年'和'近 5 年'的历史标记（例如 wage_claim_3y / wage_claim_5y）。这要求开发者在构建数据表时，需保留完整的时间维度切片，以便训练更加精确的风控模型。

驱动业务增长：场景化风控矩阵落地

仅仅调用接口获取数据是不够的，将天远 API 的数据深度整合到企业的核心工作流中，才能释放出真正的业务价值：

1. 构建全自动化的 HR 智能入职闸机 在中大型企业的批量招聘季，HR 团队面临海量的简历筛查。通过将接口接入企业内部的 ATS（招聘申请系统），在发放 Offer 的前置环节，系统自动触发 API 查询。一旦发现候选人存在近 3 年的 non_compete（竞业限制纠纷风险）或 part_time（非全日制用工纠纷风险），系统可自动生成预警报告并抄送至法务部门进行人工评估，从而将雇佣法律风险拦截在企业门外。

2. 金融信贷反欺诈与准入过滤 对于消费金融或小微企业贷，个人的信用不仅体现在征信报告中，其社会纠纷记录同样是还款意愿和能力的重要参考。利用接口返回的 dishonesty（失信风险）与 high_consumption（限制高消费风险）数据，信贷引擎可以动态调整授信额度。对于深陷 wage_claim（追索劳动报酬纠纷）的人群，模型可判定其现金流不稳定，进而提升信贷准入门槛。

构筑企业合规护城河：从信息获取到风险阻断

在这个合规监管日益趋严的时代，利用数据消除信息不对称是企业的必修课。通过 Python 高效对接天远劳动仲裁信息查询 API，就是以极低的接入成本获得了精准的风险识别能力。开发者不应只把自己当做接口的'搬运工'，更应利用这些标准化、结构化的数据，为企业打造出一套不可逾越的风控防火墙，让隐性的法律隐患无所遁形。