发送登录验证码¶
请求参数¶
面向App,服务端使用PostgreSQL;dev/prod表示运行配置,不代表不同服务器。当前公网入口使用HTTPS;仅显式启用的dev固定码HTTP例外可访问隔离开发身份。任何prod组合均关闭固定码与HTTP例外,不能靠X-Forwarded-Proto绕过。
八项公共请求头全部必填;X-Client-Type只能为app,平台ios/android。成功及业务错误响应设置Cache-Control:no-store,合法请求ID回传X-Request-Id。不需要Authorization。
| 字段 | 类型 | 必填 | 约束 |
|---|---|---|---|
| type | string | 是 | email 或 phone |
| account | string | 是 | 最长254;邮箱去首尾空格并转小写;手机号接受+和8–15位数字,国内11位手机号自动补+86 |
| agreed | boolean | 是 | 必须为true,用户明确勾选协议 |
| termsVersion | string | 是 | 当前用户协议版本,最长64 |
| privacyVersion | string | 是 | 当前隐私政策版本,最长64 |
无路径参数和查询参数。
请求示例¶
示例账号、凭证及UUID为合成数据。当前唯一正式部署环境处于上线前阶段,dev运行配置下手机号和邮箱统一使用123456,仍须先申请challengeId,不发送短信或邮件。公网HTTPS已验收;真实发送供应商及正式开放前的配置检查仍待完成。
base_url='https://api.budyoo.cn' # 当前正式域名;上线前阶段使用隔离开发身份
device_id='4d4ae3ea-6a4a-4f34-a292-8e94551851d7' # 同一安装持久保存
request_id=$(uuidgen | tr '[:upper:]' '[:lower:]')
timestamp="$(date +%s)000"
curl -i --fail-with-body \
-X POST "$base_url/api/v1/auth/challenges" \
-H 'Accept: application/json' \
-H 'Accept-Language: zh-CN' \
-H 'X-Client-Type: app' \
-H 'X-Platform: android' \
-H 'X-App-Version: 1.0.0' \
-H 'X-App-Build: 1' \
-H 'X-Channel: dev' \
-H "X-Device-Id: $device_id" \
-H "X-Request-Id: $request_id" \
-H "X-Request-Timestamp: $timestamp" \
-H 'Content-Type: application/json' \
--data '{"type":"email","account":"person@example.com","agreed":true,"termsVersion":"2026-11-02-draft","privacyVersion":"2026-11-02-draft"}'
成功响应¶
HTTP 200。
{
"code": "SUCCESS",
"message": "操作成功。",
"data": {
"challengeId": "22222222-2222-4222-8222-222222222222",
"expiresAt": "2026-11-03T00:05:00Z",
"resendAfterSeconds": 60,
"verificationMode": "development-fixed"
},
"errors": []
}
| data字段 | 类型 | 可空 | 说明 |
|---|---|---|---|
| challengeId | string(UUID) | 否 | 本次验证挑战,绑定账号、设备及协议版本 |
| expiresAt | string(date-time) | 否 | 5分钟后过期 |
| resendAfterSeconds | integer | 否 | 60秒重发间隔 |
| verificationMode | string | 否 | development-fixed或delivery;固定模式不会真正发短信/邮件 |
失败响应¶
| HTTP | 业务码 | 条件/处理 |
|---|---|---|
| 400 | INVALID_APP_CHANNEL | 渠道未知、平台不匹配或prod误用dev,不能当关闭VIP门槛 |
| 400 | INVALID_CLIENT_HEADERS | 元数据缺失、重复或不合法 |
| 400 | VALIDATION_FAILED / BAD_REQUEST | 请求字段、类型或JSON不符合契约 |
| 403 | FORBIDDEN | 本批仅接受app类型客户端 |
| 403 | ACCOUNT_BANNED | 手机号或邮箱对应当前身份空间中的账号已封禁;data为受限信息,不创建挑战或投递验证码,不进入验证码输入页 |
| 403 | NETWORK_BANNED / DEVICE_BANNED / DEVICE_REVIEW_REQUIRED | 命中网络或设备限制;data及处理见封禁接入 |
| 403 | DEVICE_CHECK_REQUIRED | 当前平台已强制设备检查且缺失/过期,先完成设备检查 |
| 426 | HTTPS_REQUIRED | 敏感接口要求HTTPS |
| 400 | INVALID_PHONE_FORMAT | type=phone时,account不是受支持的手机号格式;message会直接说明手机号格式不正确 |
| 400 | INVALID_EMAIL_FORMAT | type=email时,account不是受支持的邮箱格式;message会直接说明邮箱格式不正确 |
| 409 | CONSENT_VERSION_CHANGED | 协议版本已变化,重新展示并勾选 |
| 429 | AUTH_RATE_LIMITED | 同账号60秒冷却尚未结束,或账号/安装/IP的本小时获取额度已满;message区分原因,Retry-After返回剩余秒数 |
| 503 | AUTH_PROVIDER_UNAVAILABLE | 真实模式供应商未配置,或数据库/验证码秘密未就绪 |
| 503 | AUTH_DELIVERY_FAILED | 发送未成功接受,稍后重试 |
错误结构与公共协议一致;字段校验使用errors[].field/message,Accept明确不接受可用响应格式时406可无正文。示意:
{
"code": "INVALID_EMAIL_FORMAT",
"message": "邮箱格式不正确,请检查后重试。",
"data": null,
"errors": []
}
接入说明¶
VIP开关按发行渠道独立读取,沿用既有X-Channel/X-Platform及三个VIP布尔字段。登录绑定会话渠道,访问和刷新须一致;历史NULL会话首次合法使用绑定,之后改头返回401。首次注册来源字段只做归因,不决定当前会话门槛。详见渠道与VIP准入。
手机号和邮箱均在申请挑战时检查账号封禁:先按各自规则规范化账号,再匹配当前身份空间。合法请求、协议、供应商可用性及小时额度检查通过后,若账号正在封禁,返回HTTP403、ACCOUNT_BANNED,不生成challengeId、不使旧挑战失效,也不发送短信或邮件;该限制优先于60秒重发冷却。未登记账号不在此创建用户,继续原发码流程。客户端收到限制后展示受限提示,只有HTTP200成功取得挑战才进入验证码页。
发码阶段尚未验证手机号/邮箱所有权,data.kind=ACCOUNT,reason和expiresAt均为null,appealToken仍是24小时且绑定当前安装的独立申诉凭据;该凭据不绑定用户ID、不证明账号归属,也不能访问普通业务。示例:
{
"code": "ACCOUNT_BANNED",
"message": "此账号已被限制使用,可查看限制详情并提交申诉。",
"data": {"kind":"ACCOUNT","reason":null,"expiresAt":null,"appealToken":"当前安装的短期受限凭据","appealSubmitted":false},
"errors": []
}
原因和期限未知时不得显示为已知处罚详情或永久封禁。字段定义与申诉入口见封禁接入。验证码验证成功后仍重新检查账号限制,阻止发码后才被封禁的账号获取会话;刷新、需登录的业务API、媒体及长连接的服务端检查继续保留,提前提示不能替代这些检查。
appealSubmitted为服务端持久化的同次限制收件状态;为true时直接提示已提交过申诉并禁止重复提交。手机/邮箱重新登录、新凭据或更换安装均恢复同次账号处罚的状态,不依赖本地缓存;解封后新的处罚按新记录重新判断。
开发固定模式下通过上述检查并创建挑战才返回成功,验证码为123456且不调用发送供应商。关闭固定模式后,只有真实发送渠道明确接受才返回成功,不代表短信或邮件必然送达。重发再次调用本接口,使用新challengeId,旧挑战失效。每账号60秒冷却;每个固定整点小时内账号10次、安装20次、可信来源IP50次,失败尝试(含账号封禁拒绝)同样计数。成功响应不返回验证码或是否已有账号,封禁失败仅额外告知受限状态,不公开用户ID和处罚详情。固定模式身份分别保存为dev_phone/dev_email,与同账号的真实phone/email身份隔离。
限流提示优化已部署:HTTP429和AUTH_RATE_LIMITED保持不变,data仍为null、errors仍为[]。冷却时按最近申请时间返回“请在 N 秒后重新获取验证码。”;小时额度已满时返回“本小时验证码获取次数已达上限,请在 N 分钟后重试。”。提示支持中英日韩,未知/缺省语言回退英文;秒数或分钟数向上取整,不泄露受限账号、设备或IP。
这两类业务429同时返回Retry-After,值为正整数秒:冷却剩余最多60秒,小时额度等待当前固定窗口结束、最多3600秒;小时提示中的分钟数由同一秒数向上取整。验证码已验证成功、进入注册或返回登录都不会取消原发送冷却。客户端直接展示message;需要倒计时可读取Retry-After,不通过解析本地化文案判断原因,不自动重发请求。JWE模式的错误正文仍须认证解密,HTTP头不属于JWE认证正文;网关429遵循独立入口协议。
例如距首次申请50秒时再次申请,返回HTTP429、Retry-After:10,正文为:
{"code":"AUTH_RATE_LIMITED","message":"请在 10 秒后重新获取验证码。","data":null,"errors":[]}
验证:在服务器隔离PostgreSQL上验证认证、字段校验与失败分支;验证码投递使用仅测试源码中的捕获替身,Google/Apple使用临时RSA密钥完成真实验签测试。未向真实用户发送短信/邮件,未使用真实三方应用完成端到端登录,也未代表Flutter已接入。接口实现位于Java的identity/profile/catalog/media模块;完整接入顺序见登录注册接入。
2026-11-05手机/邮箱发码前封禁提示已部署,通过484项服务器全量回归,零失败/错误/跳过。新增14项验证覆盖两类账号的规范化、固定模式身份隔离、无投递和无新增挑战、匿名申诉、四语及英文回退、真实双向JWE、解封/到期恢复、小时计数、发码后封禁以及直接业务API、刷新和旧Token拒绝;原IP/设备和长连接限制回归保持通过。未向真实手机号/邮箱投递,不为验收创建或封禁运行用户;Flutter端实际页面验证另行完成。
2026-11-07手机号/邮箱格式提示已部署,通过818项服务器全量回归,零失败/错误/跳过。新增校验覆盖两类格式错误的独立业务码、中文提示及英文/日文/韩文消息;服务器真实HTTP请求已验证HTTP400、INVALID_PHONE_FORMAT和INVALID_EMAIL_FORMAT,未创建challenge或投递验证码。