申请新绑定验证码¶
请求参数¶
正文proofToken必填(最多100),account必填(最多254)。必须使用CHANGE_ACCOUNT旧验证凭证,类型沿用旧手机号/邮箱,不允许添加未验证第三方身份。邮箱小写;手机号E.164,国内11位自动补+86。相同旧地址或已被其他账号绑定返回409。返回challengeId、expiresAt、resendAfterSeconds、verificationMode、maskedAccount。
所有调用发送八项公共头,app/android或ios及当前包渠道,安装ID与会话一致。未知字段拒绝或按本文明确范围处理,身份只来自Bearer。JSON沿用统一响应和AES/JWE,正式要求HTTPS和真实JWE;GET密文放X-Budyoo-JWE。当前固定码dev仅供隔离账号联调,prod禁止HTTP和固定码。message四语,缺省/未知语言英文,code不翻译。
请求示例¶
以下方法路径为契约,UUID/数据为合成示例;通过既有统一客户端发送动态语言、完整元数据和Bearer,禁止记录凭据。
await api.request({path: '/api/v1/me/account/binding-challenges', method: 'POST', body: {"proofToken":"替换为旧绑定验证返回的凭证","account":"new@example.test"}});
统一层必须提供Accept-Language、X-Client-Type=app、X-Platform、X-App-Version、X-App-Build、X-Channel、持久X-Device-Id及每次新X-Request-Id/X-Request-Timestamp,Authorization按当前会话注入。
成功响应¶
HTTP200,外层code=SUCCESS、message为当前语言、data为本页说明的对象(无返回时null)、errors=[]。
{
"code": "SUCCESS",
"message": "操作成功。",
"data": {
"challengeId": "11111111-1111-4111-8111-111111111111",
"expiresAt": "2026-11-04T00:05:00Z",
"resendAfterSeconds": 60,
"verificationMode": "development-fixed",
"maskedAccount": "n***@example.test"
},
"errors": []
}
失败响应¶
| HTTP | code | 处理 |
|---|---|---|
| 400 | BAD_REQUEST/VALIDATION_FAILED/INVALID_CLIENT_HEADERS | 参数或公共头不合法 |
| 400 | AUTH_CODE_INVALID | 验证码或凭证错误、过期、消费、耗尽或会话/用途不符 |
| 401 | UNAUTHORIZED | 无效凭据、安装不一致或会话已撤销 |
| 403 | FORBIDDEN/ACCOUNT_DISABLED/VIP_REQUIRED | 按角色、账号状态及VIP准入处理 |
| 404 | NOT_FOUND | 目标不存在、不可见或不属于本人 |
| 409 | ACCOUNT_BINDING_CHANGED/ACCOUNT_ALREADY_BOUND | 身份、未结事项或并发冲突,不自动覆盖/合并 |
| 426 | HTTPS_REQUIRED | 当前模式要求安全传输 |
| 429 | AUTH_RATE_LIMITED | 验证码、校验或反馈频率超限 |
| 503 | SERVICE_UNAVAILABLE/AUTH_PROVIDER_UNAVAILABLE/AUTH_DELIVERY_FAILED | 依赖或投递不可用,不伪装成功 |
各错误仅在对应操作适用;加密失败沿用公共协议。写请求超时不等于没有执行,不自动盲目重试敏感操作。
接入说明¶
本人UI以真实返回为准,失败保留输入并显示重试;只有成功空结果可显示空态,不以设计昵称、余额、列表补数据。切换账号或退出后取消旧请求,迟到响应不能写入新会话。
验证:373项服务器Java回归通过,覆盖账号安全/注销、通知并发与JWE、关系及归属、钱包、反馈及审计回滚、迁移和媒体清理。另41项真实dev HTTP闭环通过,仅使用本次创建的2个合成账号,完成后均已注销,未发真实短信邮件或支付。后台反馈处理、七天到期任务和媒体物理删除仍以隔离库测试为验证范围。完整对照见我的与设置接入。