学生认证台返回兑换页

学生资格认证 · 合作方 API

拿到学生认证卡密即可从你的网站服务端接入。1 次卡、10 次卡、20 次卡、100 次卡使用同一套接口,不需要另申请 API Key。

正式 API 基址
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/account200 · {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处理建议
400INVALID_CDK、INVALID_LINK、INVALID_LINKS、IDEMPOTENCY_REQUIRED更正输入;不要原样循环重试。
401STUDENT_AUTH_REQUIRED用同一张卡重新换 Token 后查询。
404ORDER_NOT_FOUND核对订单号是否属于当前卡密。
409INSUFFICIENT_USES、CDK_DISABLED、NO_NEW_LINKS、IDEMPOTENCY_CONFLICT核对次数和原单;不能用同一个标识提交不同请求。
429TRY_LATER退避,不要继续密集验卡或轮询。
503STUDENT_UNAVAILABLE、STUDENT_REQUEST_FAILED放慢请求,新提交状态不明时先查原单。

超时不是失败。每次新申请在提交前保存一个随机幂等键(8–160 个字符,仅字母、数字及 _ . : -),同时保存原 links 数组。网络超时或回执丢失时先查询;确需重发时使用同一张卡、同一个键、完全相同的数组及顺序。不要生成新键来处理未知状态。

独立网站接入

  1. 你的网页只调用自己的后端,由后端通过 HTTPS 请求本接口。保管 CDK 和 Token,不放入前端 JS、URL、日志或错误回包;不依赖浏览器跨域直连。
  2. 按自己的用户保存订单 ID 与授权关系。如果多人共用一张多次卡,同一个卡密对应整张卡的订单历史。你的后端必须只向用户返回其本人的订单和结果,不能把上游 items 整页透传,也不要把共享 CDK 发给用户。
  3. 本接口不承诺固定完成时间,不提供回调。建议合并同卡查询,只对尚未终结的订单适度刷新;等待变长时逐步退避,已终结即停止。不要让每个浏览器标签各自轮询。