POST/api/v1/auth/verify-code
匿名,需公共头JSON 响应接入指南 ↗

验证码登录

请求参数

面向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。

字段 类型 必填 约束
challengeId string(UUID) 是 发送成功返回的挑战编号
code string 是 开发模式填123456;真实模式填写实际收到的六位数字,必须先申请挑战

无路径参数和查询参数。

请求示例

示例账号、凭证及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/verify-code" \
  -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 '{"challengeId":"22222222-2222-4222-8222-222222222222","code":"123456"}'

成功响应

HTTP 200。

{
  "code": "SUCCESS",
  "message": "操作成功。",
  "data": {
    "tokenType": "Bearer",
    "accessToken": "bda_<示例占位,使用实际返回值>",
    "accessExpiresAt": "2026-11-03T00:15:00Z",
    "refreshToken": "bdr_<示例占位,使用实际返回值>",
    "refreshExpiresAt": "2026-12-03T00:00:00Z",
    "userId": "11111111-1111-4111-8111-111111111111",
    "registrationStatus": "INCOMPLETE",
    "nextStep": "COUNTRY",
    "registrationStep": 1,
    "vipGateEnabled": false,
    "vipActive": false,
    "vipRequired": false
  },
  "errors": []
}
data字段 类型 可空 说明
tokenType string 否 固定Bearer
accessToken string 否 bda_开头的256位随机访问凭证
accessExpiresAt string(date-time) 否 访问过期时间,最长15分钟
refreshToken string 否 bdr_开头的单次刷新凭证
refreshExpiresAt string(date-time) 否 会话创建后30天的绝对期限,刷新不延长
userId string(UUID) 否 当前账号编号
registrationStatus string 否 INCOMPLETE 或 COMPLETE
nextStep string 否 COUNTRY、PROFILE、INTRO、INTERESTS、COMPLETE_REGISTRATION 或 HOME,保留原导航语义
registrationStep integer 否 仅1–4:1国家、2资料、3语言生日介绍、4兴趣;完成后仍为4,由registrationStatus区分
vipGateEnabled boolean 否 当前会话发行渠道的第二层VIP准入开关,动态读取,默认false
vipActive boolean 否 服务端确认的有效VIP权益;未付款、过期或撤销为false
vipRequired boolean 否 资料完成且开关开启、无有效VIP时为true,需进入VIP页

失败响应

HTTP 业务码 条件/处理
400 INVALID_APP_CHANNEL 渠道未知、平台不匹配或prod误用dev,不能当关闭VIP门槛
400 INVALID_CLIENT_HEADERS 元数据缺失、重复或不合法
400 VALIDATION_FAILED / BAD_REQUEST 请求字段、类型或JSON不符合契约
403 FORBIDDEN 本批仅接受app类型客户端
503 SERVICE_UNAVAILABLE 当前渠道VIP策略缺失或数据库暂不可用;不按关闭门槛放行
426 HTTPS_REQUIRED 敏感接口要求HTTPS
400 AUTH_CODE_INVALID 错误、过期、已使用、次数耗尽或安装不匹配
403 ACCOUNT_DISABLED 账号不可用
403 ACCOUNT_BANNED 正确验证码验证后发现账号仍在封禁,含发码后新增处罚;返回受限data,不签发会话
403 NETWORK_BANNED / DEVICE_BANNED / DEVICE_REVIEW_REQUIRED / DEVICE_CHECK_REQUIRED 网络、设备限制或需重新检查,处理见封禁接入
409 CONSENT_VERSION_CHANGED 协议版本已变化
429 AUTH_RATE_LIMITED 验证过于频繁

错误结构与公共协议一致;字段校验使用errors[].field/message,Accept明确不接受可用响应格式时406可无正文。示意:

{
  "code": "AUTH_CODE_INVALID",
  "message": "对应当前请求语言的错误提示",
  "data": null,
  "errors": []
}

接入说明

VIP开关按发行渠道独立读取,沿用既有X-Channel/X-Platform及三个VIP布尔字段。登录绑定会话渠道,访问和刷新须一致;历史NULL会话首次合法使用绑定,之后改头返回401。账号渠道字段缺失时,本次认证成功后自动补录;已有值不覆盖,补录不代表还原历史注册来源。普通Bearer认证请求同样适用,无需新增请求,完整规则见公共请求头。该字段只供展示,不决定当前会话门槛。详见渠道与VIP准入。

手机号与邮箱的已知封禁均提前在申请验证码时提示。本接口继续在验证码正确、身份确认后及会话签发前检查封禁,防止发码后才产生处罚或绕过客户端直接调用。ACCOUNT_BANNED的data使用受限响应,身份已验证时可返回本人的原因、期限和绑定本人/当前安装的申诉凭据;不能把提前提示理解为取消此处校验。

两层跳转与支付边界见注册资料与VIP准入:先完成资料,再判断vipRequired;COMPLETE或nextStep=HOME单独都不足以跳过开启的VIP门槛。渠道开关独立配置(首次初始化默认关闭,升级保留原值),客户端不能自行提交付款成功来获得权益。

步骤对应与重登恢复流程见登录注册步骤说明。每次保存资料成功后由服务端同步落库,登录直接返回registrationStep供前端跳转,无需增加或调用单独进度接口;现有刷新和本人资料也返回同一字段,客户端不提交步骤。第4步及已完成用户均返回4,registrationStatus=COMPLETE后还须判断vipRequired:true进入VIP页,false才进入首页。

仅校验挑战内已绑定的账号,不额外接收 account 或 userId。当前dev固定码为123456;它不能跳过挑战、过期、安装绑定或次数校验。开发身份与真实身份分开,关闭固定模式或进入prod后,开发挑战、访问和刷新Token全部拒绝。成功后新账号进入注册,未完成账号恢复缺失步骤,完整资料账号的nextStep为HOME,但仍须判断vipRequired决定VIP页或首页。每挑战最多5次错误;过期、已使用、安装不符统一失败;并发验证只有一次成功。每小时安装60次、直连IP150次。验证码和原始Token不明文存库;同账号新设备登录会撤销旧会话,旧设备下一次请求返回401并需重新登录。

验证:在服务器隔离PostgreSQL上验证认证、字段校验与失败分支;验证码投递使用仅测试源码中的捕获替身,Google/Apple使用临时RSA密钥完成真实验签测试。未向真实用户发送短信/邮件,未使用真实三方应用完成端到端登录,也未代表Flutter已接入。接口实现位于Java的identity/profile/catalog/media模块;完整接入顺序见登录注册接入。