学生资格认证 · 合作方 API
拿到学生认证卡密即可从你的网站服务端接入。1 次卡、10 次卡、20 次卡、100 次卡使用同一套接口,不需要另申请 API Key。
https://gmail.sanqianke.xyz/api/student快速接入
示例中的值均为占位符。BASE 使用上方基址;CDK 是你收到的卡密;LINK 是申请人本人在活动流程里获得的完整认证链接。不要把真实值粘到公开文档或客户端代码。
1. 验证卡密,取回会话 Token
curl -sS -X POST "$BASE/sessions" \
-H 'Content-Type: application/json' \
--data '{"code":"YOUR_CDK"}'
HTTP 200 返回 {"token":"…","card":{…}}。后续请求把 Token 放到 X-Student-Token,不是 Authorization,也不要放进 URL。收到 STUDENT_AUTH_REQUIRED 时,用原 CDK 重新验卡;不要每次查询都重新验。
2. 先预检,再提交
curl -sS -X POST "$BASE/preview" \
-H "X-Student-Token: $TOKEN" -H 'Content-Type: application/json' \
--data '{"links":["YOUR_SHEERID_LINK"]}'
curl -sS -X POST "$BASE/orders" \
-H "X-Student-Token: $TOKEN" -H 'Content-Type: application/json' \
--data '{"links":["YOUR_SHEERID_LINK"],"idempotency_key":"YOUR_UNIQUE_REQUEST_ID"}'
预检不扣次、不派单。返回 rows、required(本批需要的次数)、available、can_submit。行状态为 VALID、INVALID、DUPLICATE、EXISTING。同时检查 /product 是否允许新申请,最终以提交响应为准。
链接来自 https://services.sheerid.com/verify/…,需含实际申请的 verificationId。只受理符合活动条件的本人申请。HTTP 201 表示创建或返回原有批次,不代表认证通过。响应为 {batch_id,orders,card},记录其中的 orders[].id。
3. 查询原单,读取结果
curl -sS "$BASE/orders?page=1&page_size=50" \
-H "X-Student-Token: $TOKEN"
返回 {items,card,pagination}。按提交时保存的订单 id 匹配;不能假设它永远在第一页。分页从 1 开始,page_size 默认 50、最大 200。pagination 包含 page、page_size、total、pages。
卡密与次数
发卡规格由 /product 的 denominations 返回。目前为 1 / 10 / 20 / 100。每次提交使用 links 数组,单条也传数组;批次上限查询 batch_limit,目前为 100。实际可提交数量以卡片的 available 为准,不按卡密前缀判断。
{"denomination":10,"total":10,"used":2,"reserved":1,"available":7,"status":"ACTIVE"}
以上为 card 的部分字段。available = total - used - reserved。新任务先占用次数,认证成功转为已用;明确失败或未派发任务被成功取消,才释放该单占用。次数不足或存在无效链接时不会部分派单。重复项及已有申请不重复扣次。DISABLED 或 EXHAUSTED 不等于不能查历史;EXHAUSTED 也可能只是次数暂时被占用。
接口表
| 方法 | 相对路径 | 输入与成功响应 |
|---|---|---|
| GET | /product | 无需 Token · 200 · 可用状态、卡规格、批量上限 |
| POST | /sessions | 无需 Token · {code} · 200 · {token,card} |
| GET | /account | 200 · {card} |
| POST | /preview | {links} · 200 · 预检结果 |
| POST | /orders | {links,idempotency_key} · 201 · {batch_id,orders,card} |
| GET | /orders | ?page=1&page_size=50 · 200 · {items,card,pagination} |
| POST | /orders/{id}/cancel | {} · 200 · {order,card};只能取消尚未派发的任务 |
| POST | /export | {order_ids:["…"]} 或 {} · 200 · text/plain;省略 ID 时最多导出本卡最近 1000 条 |
除了前两项,均需 X-Student-Token。请求体使用 JSON;导出成功是纯文本,不作为 JSON 解析。
状态与结果
| 订单状态 | 建议前台显示 |
|---|---|
QUEUED | 等待处理,已受理。 |
RUNNING | 处理中。出现 REVIEW 时展示审核中。 |
UNKNOWN | 结果待核实。不要判为失败,不要重提或自行返还次数。 |
SUCCEEDED | 资格认证通过。仅当 redirect_url 非空且是有效的 https://one.google.com/ 链接时展示后续入口。 |
FAILED | 明确未通过,该单占用已释放。 |
CANCELLED | 已取消,该单占用已释放。 |
订单还包含 batch_id、verification_url、message、created_at、updated_at。receipt_phase 是可选补充说明,可能为 REVIEW、SUBMIT_TIMEOUT、ACTION_REQUIRED 或 APPROVED_PENDING_LINK。缺失或出现新值时按 status 显示。需要补材料或待结果链接都不要重复提交。
错误与重试
接口业务错误返回 {"error":{"code":"…","message":"…"}}。站点程序按 HTTP 状态和 error.code 分支,不按中文文案分支。
| 状态 | 常见 code | 处理建议 |
|---|---|---|
| 400 | INVALID_CDK、INVALID_LINK、INVALID_LINKS、IDEMPOTENCY_REQUIRED | 更正输入;不要原样循环重试。 |
| 401 | STUDENT_AUTH_REQUIRED | 用同一张卡重新换 Token 后查询。 |
| 404 | ORDER_NOT_FOUND | 核对订单号是否属于当前卡密。 |
| 409 | INSUFFICIENT_USES、CDK_DISABLED、NO_NEW_LINKS、IDEMPOTENCY_CONFLICT | 核对次数和原单;不能用同一个标识提交不同请求。 |
| 429 | TRY_LATER | 退避,不要继续密集验卡或轮询。 |
| 503 | STUDENT_UNAVAILABLE、STUDENT_REQUEST_FAILED | 放慢请求,新提交状态不明时先查原单。 |
超时不是失败。每次新申请在提交前保存一个随机幂等键(8–160 个字符,仅字母、数字及 _ . : -),同时保存原 links 数组。网络超时或回执丢失时先查询;确需重发时使用同一张卡、同一个键、完全相同的数组及顺序。不要生成新键来处理未知状态。
独立网站接入
- 你的网页只调用自己的后端,由后端通过 HTTPS 请求本接口。保管 CDK 和 Token,不放入前端 JS、URL、日志或错误回包;不依赖浏览器跨域直连。
- 按自己的用户保存订单 ID 与授权关系。如果多人共用一张多次卡,同一个卡密对应整张卡的订单历史。你的后端必须只向用户返回其本人的订单和结果,不能把上游
items整页透传,也不要把共享 CDK 发给用户。 - 本接口不承诺固定完成时间,不提供回调。建议合并同卡查询,只对尚未终结的订单适度刷新;等待变长时逐步退避,已终结即停止。不要让每个浏览器标签各自轮询。