天远入职背调报告API对接实战：Python构建自动化背景调查中台

应对履历异常：构建数据驱动的雇员背景核验机制

在当前的招聘环境中，履历失真、学历不实或隐瞒潜在法律纠纷等问题，给企业的人力资源管理和业务合规带来了显著挑战。传统的线下背景调查往往耗时较长，且难以全面覆盖候选人深层次的司法记录、信用表现及多维度的社会行为历史。在发放 Offer 或确立核心岗位候选人之前，通过系统级的技术对接引入客观的数据交叉验证，已成为现代企业构建风控体系的标准动作。

天远入职背调报告API 作为一种底层数据对接方案，支持将多维度的核验数据（涵盖学籍学历、婚姻登记、司法涉诉、涉赌涉诈及金融履约等）以组合包的形式输出。本文将详细探讨如何使用 Python 集成该接口，完成复杂的加解密通信，并实现背调数据的自动化清洗与入库。

Python 集成指南：构建高可用背调通信链路

本接口对数据传输的安全性及授权合规性有严格规定。在业务入参中，系统必须强制传入电子授权书的访问地址（authorization_url），以证明该次查询已获取用户同意。在通信层，数据需采用 AES-128-CBC 模式进行加密，配合动态生成的 IV（初始化向量）与 PKCS7 填充，最终将 IV 与密文拼接并进行 Base64 编码传输。

以下 Python 实战代码封装了完整的网络请求与加解密机制，并针对 HR 系统的实际场景配置了异常拦截。

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

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

2. 标准化 API 客户端代码 (Python)

Python

jsx 复制代码

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 BackgroundCheckClient:
    def __init__(self, access_id: str, access_key_hex: str):
        """
        初始化入职背调 API 客户端
        """
        self.base_url = "https://api.tianyuanapi.com/api/v1/COMBTY17"
        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)
        # 执行填充与加密
        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: 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 fetch_report(self, name: str, id_card: str, mobile: str, auth_url: str) -> dict:
        """
        发起组合包背调查询请求
        """
        timestamp = int(time.time() * 1000)
        url = f"{self.base_url}?t={timestamp}"
        
        # 组装核心业务参数，必须包含授权书地址
        params = {
            "name": name,
            "id_card": id_card,
            "mobile_no": mobile,
            "authorization_url": auth_url
        }
        
        # 加密载荷
        encrypted_payload = self._encrypt_data(json.dumps(params))
        body = {"data": encrypted_payload}

        try:
            # 组合包查询涉及多个子产品，建议超时时间略长于普通接口
            response = requests.post(url, headers=self.headers, json=body, timeout=15)
            response.raise_for_status()
            
            res_json = response.json()
            # 假设业务成功时返回加密的 data 字段
            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 = BackgroundCheckClient("YOUR_ACCESS_ID", "YOUR_HEX_KEY")
    
    # 测试调用，需传入真实可访问的电子授权书 URL (支持 pdf/jpg/jpeg/png/bmp)
    report = client.fetch_report(
        name="张三", 
        id_card="11010519900101XXXX",
        mobile="13800138000",
        auth_url="https://your-domain.com/auth/signed_doc_zhangsan.pdf"
    )
    
    if report and "responses" in report:
        print(f"成功获取背调组合包，包含子产品数量: {len(report['responses'])}")

组合包模型解析与多维数据清洗

区别于单一维度的查询，本 API 返回的是一个高度聚合的"组合包"（Array 结构）。解密后的核心数据集中在 responses 数组内，每一个元素代表一个独立子产品（如婚姻查询、学历核验、劳动仲裁等）的探测结果。

在进行数据清洗时，必须先校验 responses[].success 的布尔值状态，确认子产品调用成功后，再提取其内部嵌套的 data 对象进行落库映射。

核心数据域	关键字段路径	业务说明	开发者注意 (业务清洗与映射策略)
组合调度层	`responses[].api_code`
`responses[].success`	子产品标识及调用状态	路由网关：遍历数组时，需根据 `api_code` 将数据分发至对应的表结构。若 `success` 为 `false`，需记录 `responses[].error` 日志以供排查。
学籍学历核验
(IVYZ3P9M)	`educationLevel`	学历层次	硬性指标比对：返回值如 1(专科)、2(本科)、3(硕士) 。需与 ATS 简历库中的填报数据进行绝对值比对（`==`）。
学习形式	`learningForm`	学习形式标识	性质甄别：返回 1(脱产)、2(普通全日制) 与 6(函授)、8(非全日制) 。该字段是系统自动识别"非统招学历包装为全日制"的核心判定依据。
劳动仲裁与人事纠纷
(IVYZ0S0D)	`personnel_disputes.dismissal_dispute`
`labor_disputes.non_compete`	辞退争议及竞业限制纠纷	历史纠纷排查：状态 `2` 表示命中相关风险。若候选人命中竞业限制纠纷，系统应触发预警工单，提示 HR 索要前雇主的解约证明。
涉赌涉诈核验
(DWBG6A2C)	`antiFraudInfo.deceiver`
`antiFraudInfo.gamblerBanker`	疑似欺诈/赌博庄家风险	高危标记：返回 A/B/C/D 四个风险等级，其中 D 代表高风险（近期被交易处罚或定性为涉诈账户）。命中 C 或 D 级需重点标记。

背调数据的业务流嵌入策略

获取到底层的结构化数据后，研发团队可以将其与企业现有的 HR 或风控系统进行紧密整合：

ATS（招聘追踪系统）自动化初筛机制 针对大批量招聘的岗位，将接口串联在候选人授权环节。Python 后端异步触发 API 调用，解析 educationLevel 与 learningForm 。一旦发现学历降级或统招性质造假，系统自动中止入职流，减少人工审核介入。
核心岗位深度合规审查 对于财务、法务及高级研发等高密级岗位，利用 API 输出的 judiciaRiskInfos（个人司法信息，含案由与判决结果）以及 antiFraudInfo（涉赌涉诈风险等级）进行深度交叉验证，排查潜在的职业欺诈、被执行人记录及合规隐患。
众包平台与劳务派遣准入校验 针对流动性较高的外包人员，利用该接口组合包中的 performanceStatistics（履约情况）或 overdueRecord（历史逾期记录）评估其社会信用表现，维护平台服务人员的整体资质底线。

数据合规与隐私保护声明

在对接与处理由天远入职背调报告API反馈的个人履历数据时，系统的架构设计与业务流程必须严格遵守《个人信息保护法》等相关法律法规。本接口在参数层面强制要求提供 authorization_url，这意味着开发者与业务方在发起调用前，必须确保已获取被查询人的明确知情同意及具有法律效力的授权文件（如电子签名协议） 。

技术团队应在数据库层面落实数据的"最小化可用"与"可用不可见"原则。对于解析后的学历、婚姻状况、司法记录等高度敏感的隐私数据，必须实施字段级加密存储，并建立详尽的访问控制与审计日志。此外，API 提供的数据标签仅应作为企业风控模型与 HR 团队审核的客观辅助参考依据，系统不应单凭个别预警指标作出绝对的拒绝录用决策。在利用技术提升核验效率的同时，坚守隐私合规底线，是保障系统长期稳健运行的基础。