需完成系统级对接与数据通道配置：一、申请API Key及白名单，获取AppID/AppSecret；二、建立字段映射并测试验证；三、部署异步轮询与Webhook双向同步；四、调用批量接口提交并归档结果；五、嵌入iframe报告组件并集成PDF导出。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您希望将批改网AI检测工具接入学校统一教学管理平台，实现学生作业、论文等文本内容的自动推送与检测结果回传，则需完成系统级对接与数据通道配置。以下是完成此对接的具体步骤：
一、确认接口支持类型与权限准备
批改网AI检测工具提供RESTful API与Webhook两种主流对接方式，适用于不同技术架构的学校系统。RESTful API适合主动调用检测服务并获取结构化报告；Webhook则用于接收批改网在检测完成后自动推送的结果通知。对接前须确保学校系统具备公网可访问地址或内网穿透能力，并由校方IT管理员申请批改网开放平台的API Key及回调域名白名单权限。
1、登录批改网机构管理后台，进入【开发者中心】→【API接入管理】页面。
2、点击【新建应用】，填写学校名称、系统类型（如教务系统/学习平台/毕业论文系统）、应用描述。
3、勾选所需接口权限：包括“提交文本检测”、“查询检测报告”、“接收检测完成回调”三项。
4、提交后获取唯一AppID与AppSecret，并记录系统生成的API调用根地址（如https://api.pigai.org/v3）。
二、配置学校端数据源与字段映射
为保障检测结果能准确关联至学生、课程、作业批次等实体，需在双方系统间建立标准化字段映射关系。批改网要求必传字段包括student_id、course_id、assignment_id、content_text，其中student_id必须与学校学籍系统中的全局唯一标识一致，避免因编码规则差异导致数据错位。
1、导出学校教务系统中当前学期的课程-学生-作业绑定关系表，字段至少包含：学号（student_id）、课程代码（course_id）、作业编号（assignment_id）、作业标题（title）、截止时间（deadline）。
2、在批改网【数据映射配置】界面，将本地字段与批改网标准字段逐项绑定，例如将“学号”拖拽至“student_id”输入框，将“课程代码”绑定至“course_id”。
3、对content_text字段启用UTF-8编码强制转换，并勾选“自动截断超长文本（≥50000字符）”选项，防止因单次提交内容过大导致接口拒绝响应。
4、保存映射模板后，点击【测试验证】上传一份含3条样本数据的JSON文件，确认字段解析无误且返回状态码为200。
三、部署双向数据同步机制
学校系统需同时支持向批改网推送待检文本，以及接收批改网返回的检测报告。建议采用异步轮询+事件驱动双模式：首次提交后启动轮询任务查询状态；检测完成时通过Webhook实时接收JSON格式结果包，包含相似度分值、AI生成概率、段落级风险标记、原文高亮定位等字段。
1、在学校服务器部署定时任务脚本（如Python cron），每3分钟调用GET /v3/jobs/{job_id}/status接口，检查未完成任务状态。
2、在校园防火墙中放行批改网Webhook回调IP段（官方公布为202.108.192.0/20与202.108.224.0/20），并在学校系统后端配置接收路径（如/api/pigai/webhook）。
3、对接收的Webhook请求头中X-Pigai-Signature字段进行HMAC-SHA256签名验签，密钥为步骤一中获取的AppSecret，防止伪造回调。
4、解析回调体中result_url字段，调用该地址获取完整JSON报告；若返回code=404，说明报告尚未生成完成，延迟10秒后重试，最多尝试5次。
四、启用批量作业检测与结果归档
针对期中/期末集中提交场景，需支持按教学班或课程批量触发检测，并将结果自动写入学校数据库指定表结构。批改网提供/batch/submit接口支持一次提交最多200份文档，返回批次ID用于后续整体状态追踪与结果拉取，避免高频单条调用引发限流。
1、构造批量请求体，以JSON数组形式组织每份作业对象，每个对象包含student_id、course_id、assignment_id、content_text、submit_time（ISO8601格式）五项必填字段。
2、使用POST方法调用https://api.pigai.org/v3/batch/submit，Header中携带Authorization: Bearer {access_token}，其中access_token通过AppID/AppSecret向/oauth/token接口换取，有效期2小时。
3、收到响应后提取batch_id字段，存入学校系统batch_job_log表，并设置初始status=“submitted”。
4、调用GET /v3/batch/{batch_id}/report获取汇总报告，解析其中每条record的ai_probability与similarity_score，按学校设定阈值（如ai_probability＞0.65且similarity_score＜15%）自动标记为“疑似AI生成”，并写入student_assignment_report表。
五、配置检测结果可视化与教师端集成
检测结果需嵌入教师日常使用的教学平台界面，避免切换系统操作。批改网提供iframe嵌入式报告查看组件，支持按student_id动态加载对应报告，且默认隐藏原始文本与高亮细节，仅展示教师可授权查看的核心指标与修改建议。
1、在教师端作业批阅页面，插入代码片段。
2、{teacher_jwt}需由学校系统后端生成，使用HS256算法签名，载荷包含teacher_id、exp（7200秒）、scope（"report:read"），密钥为批改网分配的JWT Secret。
3、点击报告内【导出PDF】按钮时，触发学校系统调用批改网/export/pdf接口，传入student_id与timestamp参数，获取带学校LOGO水印的检测报告PDF文件流。
4、将PDF文件保存至学校云存储（如腾讯云COS），路径按“/pigai_reports/{year}/{semester}/{course_id}/{student_id}.pdf”组织，并在教务系统作业详情页添加下载链接。
