天远API学历核验：学历信息查询API接口调用代码与接入指南“学历信息查询”API 在企业招聘、人才背景调查、金融信贷等

一、“学历信息查询”API

在企业招聘、人才背景调查、金融信贷等众多场景中，权威、快速的学历信息核验是进行人才风险甄别的关键依据。“学历信息查询”API，能够快速查询和验证高等教育学历信息的真实性，并追溯完整的学习经历。作为天远API数据服务的重要组成部分，本文将作为一份详细的开发文档，深入剖析此API (接口代码: IVYZ9A2B)，详细解读其返回的原始数据结构和每一个核心字段的含义，帮助开发者利用权威学历大数据进行更深层次的数据分析与企业风险管理应用集成。

二、API接口调用示例

1. 调用说明

接口功能：通过姓名和身份证号查询高等教育学历信息。 请求方式：POST请求端点：https://apitest.tianyuanapi.com/api/v1/IVYZ9A2B?t=13位时间戳

安全机制：

请求头：必须包含 Access-Id，即账号的唯一凭证。
请求体加密：业务参数（姓名、身份证号）需要组装成JSON格式，然后使用AES-128-CBC模式 (PKCS7填充) 加密。
IV处理：加密时使用16字节的随机IV，并将 IV + 密文 拼接。
最终传输：将拼接后的数据进行Base64编码，作为请求体中 data 字段的值发送。
响应解密：收到的响应中 data 字段同样为Base64编码的加密数据，解密流程相反（Base64解码 -> 提取前16字节为IV -> AES解密）。

2. cURL 调用示例

# 警告：此处的 'YOUR_ACCESS_ID' 和 'ENCRYPTED_BASE64_DATA' 必须替换为您的真实数据
# ENCRYPTED_BASE64_DATA 是您本地使用 AES-128-CBC 加密并Base64编码后的数据

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

3. Python (requests) 调用示例

以下是一个完整的Python调用示例，包含了加密和解密函数的占位符。

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

# --- 占位符：请替换为您的真实凭证 ---
ACCESS_ID = "YOUR_ACCESS_ID"
# 16进制的Access Key，需要转换为16字节的bytes
ACCESS_KEY = bytes.fromhex("YOUR_16_BYTE_HEX_ACCESS_KEY")
API_ENDPOINT = "<https://apitest.tianyuanapi.com/api/v1/IVYZ9A2B>"
# ------------------------------------

def encrypt_data(payload_json: str) -> str:
    """
    使用 AES-128-CBC 加密业务数据

    """
    try:
        # 1. 准备明文和IV
        plaintext_bytes = payload_json.encode('utf-8')
        iv = get_random_bytes(16)  # 生成16字节的随机IV

        # 2. 初始化加密器
        cipher = AES.new(ACCESS_KEY, AES.MODE_CBC, iv)

        # 3. 加密并应用PKCS7填充
        padded_data = pad(plaintext_bytes, AES.block_size, style='pkcs7')
        ciphertext = cipher.encrypt(padded_data)

        # 4. 拼接 IV 和密文
        encrypted_data = iv + ciphertext

        # 5. Base64编码
        return base64.b64encode(encrypted_data).decode('utf-8')

    except Exception as e:
        print(f"加密失败: {e}")
        return None

def decrypt_data(encrypted_base64_data: str) -> str:
    """
    解密AES-128-CBC响应数据

    """
    try:
        # 1. Base64解码
        encrypted_data = base64.b64decode(encrypted_base64_data)

        # 2. 提取IV和密文 (IV为前16字节)
        iv = encrypted_data[:16]
        ciphertext = encrypted_data[16:]

        # 3. 初始化解密器
        cipher = AES.new(ACCESS_KEY, AES.MODE_CBC, iv)

        # 4. 解密并去除PKCS7填充
        decrypted_padded_data = cipher.decrypt(ciphertext)
        decrypted_data = unpad(decrypted_padded_data, AES.block_size, style='pkcs7')

        return decrypted_data.decode('utf-8')

    except Exception as e:
        print(f"解密失败: {e}")
        return None

def query_education_info(name: str, id_card: str):
    """
    调用天远API查询学历信息
    """
    # 1. 准备业务参数
    payload = {
        "name": name,
        "id_card": id_card
    }
    payload_json = json.dumps(payload)

    # 2. 加密数据
    encrypted_request_data = encrypt_data(payload_json)
    if not encrypted_request_data:
        return

    request_body = {
        "data": encrypted_request_data
    }

    # 3. 准备请求头和URL
    headers = {
        "Access-Id": ACCESS_ID,
        "Content-Type": "application/json"
    }
    # 生成13位时间戳
    timestamp = int(time.time() * 1000)
    url = f"{API_ENDPOINT}?t={timestamp}"

    try:
        # 4. 发送POST请求
        response = requests.post(url, headers=headers, data=json.dumps(request_body), timeout=10)

        if response.status_code == 200:
            response_json = response.json()

            # 5. 检查公共响应参数
            if response_json.get("code") == 0 or response_json.get("err_code") == "200":

                # 6. 解密业务数据
                encrypted_response_data = response_json.get("data")
                decrypted_response_str = decrypt_data(encrypted_response_data)

                if decrypted_response_str:
                    print("--- 解密后响应 (Decrypted Response) ---")
                    print(json.dumps(json.loads(decrypted_response_str), indent=4, ensure_ascii=False))
                else:
                    print("错误：响应数据解密失败。")
            else:
                print(f"API请求失败 (业务层面): code={response_json.get('code')}, message={response_json.get('message')}")
        else:
            print(f"HTTP请求失败: 状态码 {response.status_code}")

    except requests.exceptions.RequestException as e:
        print(f"请求异常: {e}")

# --- 执行查询 ---
if __name__ == "__main__":
    # 使用文档中的示例参数
    query_education_info("张三", "110101199001011234")

三、核心数据结构解析

API的响应数据分为两层：外层公共响应和内层加密业务数据。

外层公共响应 返回基础的http响应信息，data 字段中包含经Base64编码的加密业务数据。

{
    "code": 0, // 0表示业务成功
    "message": "业务成功",
    "transaction_id": "string", // 流水号
    "data": "ENCRYPTED_BASE64_DATA" // 加密数据
}

内层解密业务数据 (Decrypted Data) 将外层data字段解密后，得到如下结构。真正的学历信息位于 data.education_background.data 数组中。

{
    "data": {
        "query_id": "202505213797602437204758911904",
        "education_background": {
            "msg": "查询成功有结果",
            "data": [
                {
                    "jsrq": "1806",
                    "xxxs": "普通全日制",
                    "xl": "大学专科",
                    "xxlx": "其他",
                    "zymc": "其他",
                    "ksrq": "1509"
                },
                {
                    "jsrq": "2206",
                    "xxxs": "普通全l制",
                    "xl": "大学本科",
                    "xxlx": "其他",
                    "zymc": "其他",
                    "ksrq": "1809"
                }
            ],
            "code": "9100"
        }
    },
    "err_msg": "请求成功",
    "err_code": "200"
}

注：根据示例，education_background 对象位于第一层 data 对象内部。

四、字段详解

1. 请求参数 (加密前)

以下字段需组合为JSON字符串后加密，放入请求体的data字段。

字段名	类型	必填	含义
`name`	string	是	姓名
`id_card`	string	是	身份证号

2. 公共响应参数 (外层)

字段名	类型	含义
`code`	int	公共状态码，例如 0、1001等
`message`	string	公共状态描述
`transaction_id`	string	接口调用流水号
`data`	string	加密后的业务数据 (Base64编码)

3. 业务响应参数 (解密后)

3.1 业务数据根对象 (示例)

字段名	类型	含义
`data`	object	业务数据主体，包含查询ID和学历信息
`err_msg`	string	业务错误信息
`err_code`	string	业务错误码

3.2 学历信息对象 (`education_background`)

字段名	类型	含义
`msg`	string	业务查询状态详情，如 "查询成功有结果"
`data`	array	学历信息数组，包含一条或多条学历记录
`code`	string	业务查询状态码，如 "9100"
`query_id`	string	订单号/查询流水号
(注：根据文档结构，`query_id` 实际在 `education_background` 的同级)

3.3 学历记录详情 ( `education_background.data` 数组元素)

字段名	类型	含义	说明
`xl`	string	学历	如：大学专科、大学本科
`xxlx`	string	学校类型	如：普通高校、成人高校、其他
`xxsx`	string	学习形式	如：普通全日制、非全日制 (注：示例中为`xxxs`)
`ksrq`	string	入学时间	格式：YYMM，如 "1809"
`jsrq`	string	毕业时间	格式：YYMM，如 "2206"
`zymc`	string	专业名称

五、应用价值分析

学历信息查询 API (IVYZ9A2B) 在多个关键业务流程中具有重大的应用价值：

人力资源与招聘 在候选人筛选阶段，HR或用人单位可实时调用此API，验证候选人简历上填写的学历信息是否属实。这能有效防范学历造假，提高招聘效率，确保入职人员的资质符合岗位要求。
专业背景调查 对于专业的背调服务机构，该API可作为核心数据源之一，纳入标准背调流程，为客户提供权威、可信的学历核验报告。
金融与信贷风控 在银行、消费金融、小额贷款等场景中，申请人的学历水平是评估其还款能力和信用风险的参考维度之一。将此API集成到风控模型中，有助于更准确地描绘用户画像，优化信审决策。
教育与培训 教育机构在招生（尤其是专升本、研究生）时，可使用此接口快速核验前置学历的有效性。

天远API 提供的此接口，采用先进的加密技术确保数据传输安全，响应速度快，数据准确度高，是企业实现人事风控和业务流程自动化的可靠工具。

六、总结

本文详细介绍了天远API的学历信息查询API (IVYZ9A2B) 的接入方法、安全机制、请求与响应结构，并提供了完整的curl和Python调用代码示例。该接口通过提供权威、即时的学历数据核验服务，帮助企业在招聘、背调和风控等场景中有效防范履历造假风险。开发者可以参照本文档和代码示例，快速将其集成到现有的HRM、CRM或风控系统中，提升业务处理的自动化水平和数据准确性。

天远API学历核验：学历信息查询API接口调用代码与接入指南