Python背调自动化：利用天远劳动仲裁信息查询API排查潜在人事纠纷

天远API
5 阅读8分钟

穿透数据迷雾：精准识别潜在合规与用工风险

在企业招聘背景调查、金融机构信贷审核以及合作伙伴资质评估等高准入门槛的业务场景中，信息的不对称往往潜藏着巨大的法律与经济风险 。传统的尽职调查或人工背调不仅耗时耗力，且难以全面覆盖个人过往的劳动争议、失信记录及复杂的社会保险纠纷 。一旦引入带有严重用工纠纷历史或已被列入失信名单的人员或合作伙伴，极易导致企业陷入无休止的仲裁泥潭或面临直接的资金损失。

为了帮助企业在用人或确立合作前置阶段有效识别风险，天远劳动仲裁信息查询API 提供了一套全方位、时效化的法律风险分析接口 。该接口不仅能够毫秒级核验目标对象的失信与限制高消费状态，还能深度穿透劳动争议（如追索劳动报酬、经济补偿金等）、社会保险纠纷以及人事争议等多维度的底层数据 。通过提供近3年与近5年的历史风险时间轴标记，该API使企业能够彻底告别盲盒式用工与合作，将风控防线前移 。

Python 构建高可用风控查询服务

本接口的数据传输对安全性要求极高，所有业务请求参数均需经过 AES-128 算法加密，并进行 Base64 编码后方可在网络中传输 。解密时则需逆向操作，提取动态生成的 IV 向量进行解密 。

以下 Python 实战代码封装了完整的网络请求机制与加解密管道，包含异常拦截与超时重试逻辑。

1. 核心加密规范与端点配置

  • 请求端点: https://api.tianyuanapi.com/api/v1/IVYZ0S0D?t=13位时间戳
  • 通信协议: POST
  • 加密策略: AES-CBC 模式，128位密钥，PKCS7填充，每次加密随机生成 16 字节 IV，IV 与密文拼接后整体 Base64 编码 。
  • 关键入参: id_card (身份证号) 与 name (姓名) 。

2. 标准化 API 集成代码 (Python)

Python

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

class LaborRiskQueryClient:
    def __init__(self, access_id: str, access_key_hex: str):
        """
        初始化天远 API 客户端
        :param access_id: 账号的 Access-Id
        :param access_key_hex: 16进制字符串格式的 Access Key
        """
        self.base_url = "<https://api.tianyuanapi.com/api/v1/IVYZ0S0D>"
        self.access_id = access_id
        # 转换为 16 字节的 bytes
        self.access_key = bytes.fromhex(access_key_hex)
        self.headers = {
            "Access-Id": self.access_id,
            "Content-Type": "application/json"
        }

    def _encrypt_data(self, raw_payload: str) -> str:
        """
        AES-128-CBC 加密逻辑
        包含随机 IV 生成、PKCS7 填充及最终的 Base64 编码
        """
        # 随机生成 16 字节的初始化向量 (IV)
        iv = get_random_bytes(16)
        cipher = AES.new(self.access_key, AES.MODE_CBC, iv)
        # 对原始 JSON 字符串进行 PKCS7 填充并加密
        ct_bytes = cipher.encrypt(pad(raw_payload.encode('utf-8'), AES.block_size))
        # 将 IV 和密文拼接，并进行 Base64 编码传输
        return base64.b64encode(iv + ct_bytes).decode('utf-8')

    def _decrypt_data(self, encrypted_b64: str) -> dict:
        """
        解析并解密响应载荷
        """
        try:
            raw_data = base64.b64decode(encrypted_b64)
            # 提取前 16 字节作为解密 IV
            iv = raw_data[:16]
            ct = raw_data[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_labor_risk(self, name: str, id_card: str) -> dict:
        """
        发起劳动仲裁风险查询请求
        """
        # 构造携带 13 位时间戳的 URL
        timestamp = int(time.time() * 1000)
        url = f"{self.base_url}?t={timestamp}"
        
        # 组装明文请求参数
        params = {
            "name": name,
            "id_card": id_card
        }
        
        # 将参数转换为 JSON 并加密
        encrypted_payload = self._encrypt_data(json.dumps(params))
        body = {"data": encrypted_payload}

        try:
            # 设定合理的超时时间，防止网络阻塞
            response = requests.post(url, headers=self.headers, json=body, timeout=10)
            response.raise_for_status()
            
            res_json = response.json()
            # 假定业务成功状态码为 200 或业务层无 error 字段
            if "data" in res_json:
                return self._decrypt_data(res_json["data"])
            else:
                print(f"API 业务报错: {res_json.get('message', '未知错误')}")
                return {}
                
        except requests.exceptions.RequestException as e:
            print(f"网络通信失败: {e}")
            return {}

# 开发者测试调用入口
if __name__ == "__main__":
    client = LaborRiskQueryClient("YOUR_ACCESS_ID", "YOUR_HEX_KEY")
    result = client.query_labor_risk(name="张三", id_card="11010519900101XXXX")
    
    if result:
        basic_flag = result.get('result', {}).get('basic_info', {}).get('risk_flag')
        print(f"全局风险状态: {'有风险' if basic_flag == '2' else '无风险'}")

3. cURL 命令行级联测试

Bash

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

风险标签解析与数据清洗策略

API 成功解密后的核心数据集中在 result 对象内，呈现为一个高密度的嵌套层级结构。它将风险划分为基础风险、失信/限高、劳动争议、社会保险、福利待遇及人事争议等大类 。绝大多数风险标识字段采用二元状态值：1 代表未命中风险，2 代表命中风险 。

在处理解析时，建议建立如下映射字典以规范化数据落库：

核心风险模块关键字段名业务含义开发者注意 (清洗与决策建议)
基础信息basic_info.risk_flag全局风险判定路由分发点：若值为 1，可直接放行；若为 2，系统必须遍历后续详细风险节点，提取具体案由以决定是自动拒绝还是转人工 。
失信/限高dishonesty.dishonesty
high_consumption.high_consumption法院执行黑名单红线指标：一旦值为 2，建议在金融风控或核心岗位招聘场景中直接触发“一票否决”机制 。
劳动争议labor_disputes.labor_relation_3y
labor_disputes.wage_claim_5y近3/5年纠纷记录时效降权：包含确认劳动关系、追索劳动报酬等 。建议根据时间衰减因子赋予不同权重，近3年内的纠纷（值为2）危险系数显著高于近5年。
人事争议personnel_disputes.resignation_dispute
personnel_disputes.dismissal_dispute辞退与辞职纠纷背调重点：命中该项（值为2）提示员工与前雇主存在非正常离职过程 ，需 HR 介入获取原始离职证明或仲裁调解书进行二次核验。
通知函时效notice_letter_period涉诉/仲裁时间跨度数值分段：该字段返回 0（无）、1（近2年）、2（2-4年）、3（5年以上）。可据此判断该人员近期是否处于法律诉讼高活跃期。

架构提示：由于风险点细分极多（涵盖经济补偿、竞业限制、工伤医疗等 ），建议在数据库中采用 JSONB 格式整存整取 result 节点，并通过构建业务宽表或动态规则引擎（如 Drools）来提取特定风险字段，避免频繁变更表结构。

风险数据驱动的业务自动化闭环

单纯的 API 接入只是第一步，挖掘并组合这些高价值的标签数据，才能真正重塑企业的合规与风控流程。

  1. **HR 自动化极速背调 (ATS 整合)**在企业招聘管理系统 (ATS) 中，当候选人接受 Offer 并授权后，系统自动触发查询。若 labor_disputes (劳动争议) 模块下的 non_compete (竞业限制) 返回 2 ，系统可自动生成预警工单，提醒 HR 该候选人可能背负前公司的竞业协议，需立即要求其提供解约证明，从而规避企业连带侵权风险。
  2. 小微信贷与消金秒批拦截在面向个人的信贷审批漏斗中，将 dishonesty (失信) 和 high_consumption (限高) 字段接入前置规则引擎。如果命中，直接触发硬拒策略，阻断资金流入劣质资产。同时，如果 wage_claim (追索劳动报酬) 近3年内频发 ，侧面反映申请人收入极度不稳定或具有较高的恶意讨薪欺诈倾向，系统可自动下调其授信额度。
  3. 零工平台与劳务派遣准入筛查对于外卖、出行等灵活用工平台，大量接入非全日制用工 。批量调用该接口排查 part_time (非全日制用工纠纷) 与 injury_insurance (工伤保险待遇纠纷) 历史 。识别出频繁利用工伤索赔漏洞的“职业碰瓷者”，并将其加入平台灰名单，大幅降低平台的隐性运营成本。

数据合规与隐私保护声明

在集成和使用天远劳动仲裁信息查询API时，开发者与业务方必须严格遵守《个人信息保护法》等相关法律法规。鉴于接口返回的数据涉及高度敏感的个人法律纠纷与征信履历，系统在发起查询请求前，务必确保已获取被查询人的明确授权与知情同意，严禁在未经授权的场景下私自调用或滥用数据。

此外，技术团队应在架构层面落实数据的“可用不可见”原则，建立完善的日志审计、字段级脱敏及加密存储机制。请注意，API 返回的风险标签与历史记录仅代表客观存在的数据快照，应仅作为企业风控与人事背调的辅助参考依据，不可作为拒绝录用或信贷拒批的绝对/唯一决定因素。用技术赋能业务的同时，坚守隐私保护底线，才是构筑企业长期合规运营的真正护城河。

avatar
文章
阅读
粉丝