Agent Ready•SMS Verification Service

短信验证码服务 API 文档

基于 Go + Gin 的短信验证码服务，部署在云函数上。支持发送验证码与校验验证码两个核心能力，已适配阿里云短信、腾讯云 CloudBase 等多种后端。

查看工作流示例

基础信息

Base URL: https://sms-service.wuxia.cool
Content-Type: application/json; charset=utf-8
统一响应: 所有接口统一返回 JSON：成功时 `code` 字段为 "OK" 且 `data` 为业务对象；失败时 `code` 为具体错误码，`message` 给出人类可读原因。
鉴权: 当前示例无独立鉴权层，请通过网关或反向代理加入鉴权（如 API Key、JWT、IP 白名单等）。所有请求使用 HTTPS。

POST/api/v1/sms/send

发送短信验证码

向指定手机号发送短信验证码，返回用于校验的 verification_id。

服务端会生成（或沿用上游已生成的）6 位数字验证码并通过短信下发，返回的 `verification_id` 必须在校验接口原样回传，用于关联发送与校验。

请求参数

字段	类型	必填	说明
phone_number	string	必填	手机号。必须为合法的 E.164 / 国内 11 位手机号格式，具体规则视下游短信通道而定。
verify_code	string	否	可选的预生成验证码。当上游身份提供方已经生成好验证码时传入，否则由服务端生成。
code_length	integer	否	验证码长度，默认 6 位，范围 4–8。
expires	integer	否	验证码有效期，单位分钟。`0` 表示使用默认 5 分钟；`-1` 表示不校验过期时间、仅下发。

响应

字段	类型	说明
verification_id	string	验证 ID，校验验证码时必须原样回传；通常为 32 位十六进制字符串。
expires_in	integer	验证码有效期，单位秒。

成功示例json

{
  "code": "OK",
  "message": "success",
  "data": {
    "verification_id": "9f3c0b1d6a2e4f8c8e7b5a0d1c2e3f40",
    "expires_in": 300
  }
}

失败示例json

{
  "code": "INVALID_PHONE",
  "message": "phone_number 格式不合法",
  "data": null
}

调用示例

cURLbash

curl -X POST "https://sms-service.wuxia.cool/api/v1/sms/send" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "13800138000",
    "code_length": 6,
    "expires": 5
  }'

POST/api/v1/sms/check

校验短信验证码

校验用户提交的验证码是否正确、是否在有效期内。

通过 `verification_id`（推荐）或 `out_id`（兼容旧用法）将本次校验与某次发送关联。返回 `verify_result` 为 "PASS" 表示通过，"FAIL" 表示失败，`err` 字段给出错误原因。

请求参数

字段	类型	必填	说明
phone_number	string	必填	发送验证码时使用的手机号，需与发送时一致。
verify_code	string	必填	用户输入的短信验证码。
verification_id	string	否	发送验证码接口返回的 verification_id。推荐使用此字段与发送进行精确关联。
scheme_name	string	否	方案名称，留空则使用「默认方案」，最长 20 个字符。
out_id	string	否	外部流水号，兼容旧用法，与 verification_id 二选一。
case_auth_policy	integer	否	大小写策略：`1` 不区分大小写，`2` 区分大小写。

响应

字段	类型	说明
verify_result	string	校验结果，`PASS` 表示通过，`FAIL` 表示未通过。
err	string	错误描述。当 verify_result = FAIL 时携带人类可读的错误原因，通过时为空字符串。

成功示例json

{
  "code": "OK",
  "message": "success",
  "data": {
    "verify_result": "PASS",
    "err": ""
  }
}

失败示例json

{
  "code": "OK",
  "message": "success",
  "data": {
    "verify_result": "FAIL",
    "err": "验证码错误或已过期"
  }
}

调用示例

cURLbash

curl -X POST "https://sms-service.wuxia.cool/api/v1/sms/check" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "13800138000",
    "verify_code": "482931",
    "verification_id": "9f3c0b1d6a2e4f8c8e7b5a0d1c2e3f40"
  }'

端到端工作流：发送 → 校验

标准流程：先调用发送接口拿到 `verification_id`，在前端让用户输入收到的验证码，再调用校验接口完成登录/注册。

End-to-endjavascript

// 1) 发送验证码
const sendResp = await fetch("https://sms-service.wuxia.cool/api/v1/sms/send", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ phone_number: "13800138000", code_length: 6, expires: 5 }),
});
const { data: sendData } = await sendResp.json();
// 把 sendData.verification_id 与该手机号绑定后下发验证码

// 2) 用户输入验证码后，调用校验接口
const checkResp = await fetch("https://sms-service.wuxia.cool/api/v1/sms/check", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    phone_number: "13800138000",
    verify_code: "482931", // 用户在页面上输入的 6 位验证码
    verification_id: sendData.verification_id,
  }),
});
const { data: checkData } = await checkResp.json();
if (checkData.verify_result === "PASS") {
  // 校验通过，业务放行
} else {
  // 失败原因：checkData.err
}