学历验证不再难！学历信息查询API接入教程 + 天远API企业级应用场景解析

天远API
99 阅读8分钟

一、学历查询的重要性和试用场景

在人才招聘背景调查、教育机构学籍核验、金融信贷风险评估、公务员政审材料审核以及在线学历认证平台等众多场景中，真实、权威的学历数据验证是进行身份真实性校验和风险控制的关键依据。

“学历信息查询API”由天远API提供，能够通过姓名与身份证号快速查询用户在高等教育阶段的完整学历记录，包括学历层次、院校类型、学习形式、入学/毕业时间及专业信息，并支持多条学历经历的时间线追溯。本文将作为一份详细的开发文档，深入剖析此API，详细解读其返回的原始数据结构和每一个核心字段的含义，帮助开发者利用结构化学历大数据进行更深层次的数据分析与企业级风控系统、HR SaaS平台或教育管理平台的应用集成。

该学历验证接口采用AES-128-CBC强加密机制，保障数据传输安全，响应速度快，准确度高，是构建可信数字身份体系的重要基础设施。

二、API接口调用示例

调用说明

  • 请求方式：POST

  • 接口地址：https://apitest.tianyuanapi.com/api/v1/IVYZ9A2B?t=<13位时间戳>

  • 认证方式：通过 Access-Id（请求头） + Access Key（用于AES加密）

  • 参数传递：请求体中的 data 字段为 Base64 编码后的 AES-128-CBC 加密字符串

  • 加密规则：

    • 算法：AES-128-CBC
    • 密钥：16字节（由Access Key转换而来）
    • IV：16字节随机生成，拼接在密文前
    • 填充：PKCS7
    • 最终输出：Base64(IV + ciphertext)

⚠️ 注意：以下代码中的 encrypt_data() 和 decrypt_data() 为占位函数，实际使用时需根据您的 Access Key 实现 AES 加解密逻辑。

curl 示例

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

说明：YOUR_ACCESS_ID 替换为您的实际 Access-Id；data 字段需替换为真实加密后的 Base64 字符串。

Python 示例（完整可运行）

import requests
import time
import json
import base64

# === 占位加密函数（开发者需自行实现）===
def encrypt_data(plain_text: str, access_key_hex: str) -> str:
    """
    使用 AES-128-CBC 加密明文，返回 Base64 编码字符串
    :param plain_text: 明文 JSON 字符串，如 '{"name":"张三","id_card":"..."}'
    :param access_key_hex: 16进制字符串格式的 Access Key（32字符）
    :return: Base64 编码的 (IV + ciphertext)
    """
    # TODO: 实现 AES-128-CBC 加密逻辑
    # 示例伪代码（不可直接运行）：
    # key = bytes.fromhex(access_key_hex)
    # iv = os.urandom(16)
    # cipher = AES.new(key, AES.MODE_CBC, iv)
    # padded = pad(plain_text.encode('utf-8'), 16, style='pkcs7')
    # ciphertext = cipher.encrypt(padded)
    # return base64.b64encode(iv + ciphertext).decode('utf-8')
    raise NotImplementedError("请实现 AES 加密逻辑")

# === 占位解密函数 ===
def decrypt_data(encrypted_b64: str, access_key_hex: str) -> str:
    """
    解密 Base64 数据，返回原始明文
    """
    # TODO: 实现 AES 解密逻辑
    raise NotImplementedError("请实现 AES 解密逻辑")

# === 主调用逻辑 ===
def query_education_info(name: str, id_card: str, access_id: str, access_key: str):
    url = f"<https://apitest.tianyuanapi.com/api/v1/IVYZ9A2B?t=>{int(time.time() * 1000)}"

    # 构造明文请求参数
    payload = {
        "name": name,
        "id_card": id_card
    }
    plain_json = json.dumps(payload, ensure_ascii=False)

    try:
        # 加密并编码
        encrypted_data = encrypt_data(plain_json, access_key)
    except Exception as e:
        print(f"[错误] 加密失败: {e}")
        return None

    headers = {
        "Access-Id": access_id,
        "Content-Type": "application/json"
    }
    body = {"data": encrypted_data}

    try:
        response = requests.post(url, headers=headers, json=body, timeout=10)
        response.raise_for_status()
    except requests.RequestException as e:
        print(f"[错误] 网络请求失败: {e}")
        return None

    resp_json = response.json()
    err_code = resp_json.get("err_code")
    if err_code != "200":
        print(f"[错误] API 返回异常: {resp_json.get('err_msg')}")
        return None

    # 解密 data 字段
    encrypted_response = resp_json.get("data")
    try:
        decrypted_result = decrypt_data(encrypted_response, access_key)
        result = json.loads(decrypted_result)
        return result
    except Exception as e:
        print(f"[错误] 响应解密失败: {e}")
        return None

# === 使用示例 ===
if __name__ == "__main__":
    # 替换为您的实际凭证
    ACCESS_ID = "your_access_id"
    ACCESS_KEY = "your_32_char_hex_access_key"  # 如: "a1b2c3d4e5f67890a1b2c3d4e5f67890"

    result = query_education_info("张三", "110101199001011234", ACCESS_ID, ACCESS_KEY)
    if result:
        print("学历查询结果:")
        print(json.dumps(result, indent=2, ensure_ascii=False))

💡 提示：实际部署时，请使用 pycryptodome 或 cryptography 库实现 AES 加解密，并妥善保管 Access Key。

三、核心数据结构解析

API 的最终响应为嵌套 JSON 结构，核心学历数据位于解密后的 data.education_background.data 数组中。

数据层级结构如下：

{
  "data": {
    "query_id": "订单流水号",
    "education_background": {
      "code": "业务状态码（如9100）",
      "msg": "状态描述",
      "data": [               ←←← 核心学历记录数组（可能多条）
        {
          "xl": "大学本科",
          "xxlx": "其他",
          "xxxs": "普通全日制",
          "ksrq": "1809",
          "jsrq": "2206",
          "zymc": "计算机科学与技术"
        },
        ...
      ]
    }
  },
  "err_code": "200",
  "err_msg": "请求成功"
}
  • education_background.data：包含用户所有可查学历记录，按时间倒序排列（最新学历在前）
  • 每条记录代表一个完整的学历阶段（如专科、本科）
  • 时间字段采用 YYMM 格式（如 "1809" 表示 2018年9月）

四、字段详解

1. 公共响应字段

字段名含义说明
err_code全局状态码"200" 表示请求成功，非200表示网络或鉴权错误
err_msg全局状态信息如“请求成功”、“缺少Access-Id”等
data加密响应体需用 Access Key 解密后获取真实数据

2. 业务响应字段（解密后）

字段名含义说明
query_id查询流水号唯一标识本次查询，可用于对账或日志追踪
education_background.code业务状态码"9100" 表示查询成功有结果，"1000" 表示无学历记录
education_background.msg业务状态描述如“查询成功有结果”
education_background.data学历记录数组可能为空（无记录）或多条

3. 学历记录字段（每条学历对象）

字段名含义说明
xl学历层次如“大学专科”、“大学本科”、“硕士研究生”等
xxlx院校类型如“普通高校”、“成人高校”、“网络教育”等（示例中为“其他”）
xxxs学习形式如“普通全日制”、“非全日制”、“函授”等
ksrq入学时间格式 YYMM，如 "1809" 表示 2018年9月
jsrq毕业时间格式 YYMM，如 "2206" 表示 2022年6月
zymc专业名称如“计算机科学与技术”、“工商管理”等（部分可能为“其他”）

五、应用价值分析

1. 典型业务场景

  • 招聘风控：HR 在候选人入职前自动核验学历真伪，防范简历造假。
  • 金融授信：银行或消费金融公司在审批贷款时，将学历作为信用评估因子之一。
  • 教育监管：教育局或高校用于学籍比对、学历备案核查。
  • 政务审核：公务员、事业单位报考资格审查中的学历材料自动化验证。
  • SaaS 平台集成：背调平台、人才数据库、在线认证服务嵌入学历验证能力。

2. 数据分析建议

  • 将 ksrq 与 jsrq 转换为标准日期，计算学制时长，识别异常（如2年读完本科）。
  • 结合 xl 与 xxxs 分析用户教育路径，构建人才画像标签。
  • 对比多条记录的时间连续性，判断是否存在学历断层或重叠。

3. 系统集成建议

  • 在用户提交简历或注册时异步调用，避免阻塞主流程。
  • 缓存查询结果（以身份证+姓名为Key），避免重复调用。
  • 记录 query_id 用于审计和计费对账。
  • 设置熔断机制，当接口异常时降级处理（如标记“待人工审核”）。

4. 实际价值

通过天远API提供的学历信息查询服务，企业可将学历核验从“人工查证”升级为“秒级自动化”，显著提升效率、降低用人风险，并增强业务合规性。尤其在大规模招聘或高风险金融场景中，该API成为不可或缺的数据基础设施。

六、总结

本文全面介绍了学历信息查询API的调用流程、安全机制、数据结构及字段含义，并提供了可直接参考的 curl 与 Python 调用示例。该接口由天远API提供，具备高安全性（AES-128-CBC加密）、高准确性（对接权威学历数据库）和高可用性（无频率限制），适用于招聘、金融、政务、教育等多个关键场景。

对于开发者而言，只需完成一次加密逻辑封装，即可在各类业务系统中无缝集成学历验证能力。建议在正式上线前充分测试加解密流程，并做好错误码处理与日志记录。未来，结合更多维度的身份数据（如学信网验证码、学位信息等），学历验证将更加精准可靠。

avatar
文章
阅读
粉丝