元析开放平台
首页/短信验证码接入

短信验证码接入

托管式短信验证码服务。业务方传 mobile + scene, 平台生 6 位数字码、落库、调阿里云发送; verify 接口校验后一次性失效。

目录

概述

  1. 在控制台注册账号 → 创建应用 → 在应用详情页生成一把 sk-live-… 形式的 API Key。
  2. 订阅「短信验证码」能力。
  3. 联系平台管理员把你的业务场景登记到模板表 (scene 名 + 阿里云模板 ID), 一个 scene 对应一个三方模板。
  4. 业务后端调 /sms/code/send 发码, 平台生码并发短信。
  5. 用户在你的页面输入收到的码, 业务后端调 /sms/code/verify 校验, 命中即一次性失效。
接口前缀: https://open.zcode.team/api/v1
验证码有效期: 发送后 5 分钟内有效; 同一码只能 verify 命中一次。

鉴权

所有接口都在 Authorization Header 携带 API Key: 

Authorization: Bearer sk-live-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

应用必须先在控制台订阅「短信验证码」能力, 否则 verify-key 阶段会被拒。

安全建议: 不要把 Key 写到前端 / 客户端代码里。所有 send / verify 调用都从业务后端发起。

发送验证码

POST /sms/code/send

请求 Body

{
  "mobile": "13800138000",   // 11 位手机号
  "scene":  "login"          // 业务场景, 对应 admin 注册的模板 code
}

响应

{
  "code": 0,
  "msg": "ok",
  "data": {
    "providerResp": "{\"Message\":\"OK\",\"RequestId\":\"...\",\"BizId\":\"...\"}"
  }
}

curl 示例

curl -X POST https://open.zcode.team/api/v1/sms/code/send \\
  -H "Authorization: Bearer sk-live-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \\
  -H "Content-Type: application/json" \\
  -d '{"mobile":"13800138000","scene":"login"}'
scene 是什么: 业务场景标识, 例如 login、register、reset_pwd。 平台用它去模板表找对应的阿里云模板 ID, 用同一签名发出。你可以为多个场景注册多个模板。

校验验证码

POST /sms/code/verify

请求 Body

{
  "mobile": "13800138000",
  "scene":  "login",
  "code":   "535179"         // 6 位数字, 用户输入
}

响应

{
  "code": 0,
  "msg": "ok",
  "data": { "verified": true }
}

curl 示例

curl -X POST https://open.zcode.team/api/v1/sms/code/verify \\
  -H "Authorization: Bearer sk-live-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \\
  -H "Content-Type: application/json" \\
  -d '{"mobile":"13800138000","scene":"login","code":"535179"}'
一码只能用一次: 命中后立即 mark used, 二次 verify 同一码会返回 code not requested or expired。

限流策略

防刷限流, 命中返回业务 code 429:

维度上限
同手机号1 条 / 分钟; 10 条 / 天
同 IP1 条 / 分钟
同应用 + 同手机号20 条 / 天

错误码

code含义
0成功
400参数错误 / 手机号格式不合法 / scene 模板未配置 / 码错误或过期
401鉴权失败 (Key 无效 / 已禁用)
403应用未订阅 sms 能力
429触发限流, 见上一节
500服务器内部错误
文档有疑问? 反馈到 tech@yunshee.com。